Interface: Authentication

Authentication

Exposes the functions and constants of the Webcom Authentication service. This service is configured by the Authentication property passed to the configuration of the associated WebcomApp.

The signInXXX(...) methods make it possible to authenticate the user and sign her·him in: signInAsGuest, signInWithCredentials, signInWithWassup, signInWithOAuth, signInWithCustomProvider, signInWithToken.

The signOut method signs the user out.

The currentState property, and the subscribe and unsubscribe methods makes it possible to watch the authentication state.

Many other methods make it possible to manage user accounts (creating, updating, removing).

Instances of this interface are provided by the WebcomApp#authentication property.

Since:
  • 2.11 (moved from AuthenticationService since 3.0)

Extends

  • WebcomService

Classes

State

Members

(readonly) currentState :Authentication.State

The current authentication state.
Note: When working together with a ServerlessDb that uses this Authentication instance, this property is slightly delayed wrt. ServerlessDb#currentState. If you need a real time value, rather use the latter property.

Type:

Methods

addIdentity(provider, details, messageopt) → {Promise.<Authentication.AuthenticationDetails>}

Creates a new identity managed by the Webcom Authentication Service. If the Authentication#useCurrentContextForNextAuthOperation method is called just before this method, then the new identity is bound to the Webcom account of the currently authenticated user. Otherwise, or if no user is currently authenticated, the new identity is bound to a new Webcom account (to be created at the same time). Currently, Webcom is able to manage email- and phone-based identities.

Parameters:
Name Type Attributes Description
provider "password" | "phone"

The internal provider to use to create the identity. Currently, only "password" (for email-based identities) and "phone" (for phone-based identities) are supported.
details

The details associated with the identity to create.

Properties
Name Type Attributes Description
id string

The identifier of the identity to create. For an email-based identity, it is an email address. For a phone-based identity, it is the MSISDN of a phone device able to receive SMS (without the "+" prefix).
password string

(email-based identities only)
The password associated to the email-based identity to create.
displayName string <optional>

A human-readable display name for the identity to create. This piece of information can be further retrieved within the displayName attribute of the providerProfile property of the returned Authentication.AuthenticationDetails object.
profile * <optional>

A user-profile structure for the identity to create. This piece of information can be further retrieved within the providerProfile property of the returned Authentication.AuthenticationDetails object.
message <optional>

The parameters to apply to the verification message to be sent to the user.

Properties
Name Type Attributes Default Description
template string <optional>
 "create"

The identifier of the verification message to send to the user. It must be picked among the template messages defined in the Webcom developer console.
sender string <optional>

(phone-based identities only)
The identifier of the SMS sending implementation to use to send the verification message to the user (the implementations must be set up in the Webcom developer console).
locale string <optional>

The locale of the verification message to send to the user (e.g. en for English whatever its variant, en_US for the american English, etc.). It must be in the ll_CC format, where ll is the ISO 639 alpha-2 code for the language and CC is the ISO 3166 alpha-2 code for the country variant.
See:
Returns:
Type
Promise.<Authentication.AuthenticationDetails>

authenticationRevoked(authState, message)

Notifies the Authentication from the outside that the current authentication was revoked.

This method is not intended to be called directly from an application.
It is rather intended to Webcom service implementations that depend on an Authentication.

Parameters:
Name Type Description
authState Authentication.State

New authentication state (it should be such that authState.isAuthenticated() is false).
message string

Notification message explaining the revocation.

removeAccount() → {Promise}

Deletes the Webcom account associated with the currently authenticated identity. This method deletes also all the identities associated with this account. In order to succeed, this sensible operation requires a fresh authentication. If the current authentication token is too old, then the operation fails, in this case you have to refresh the user authentication by authenticating her⋅him afresh explicitly before renewing the operation.

See:
Returns:
Type
Promise

removeIdentity() → {Promise}

Deletes the currently authenticated identity. This method doesn't delete the associated Webcom account unless there is no other identity associated with it. In order to succeed, this sensible operation requires a fresh authentication. If the current authentication token is too old, then the operation fails, in this case you have to refresh the user authentication by authenticating her⋅him afresh explicitly before renewing the operation.

See:
Returns:
Type
Promise

sendOtp(provider, id, messageopt) → {Promise.<string>}

Sends a one time password (OTP) to a user through a given identity. This method is particularly useful before calling the Authentication#signInWithCredentials method, which may requires a temporary password to complete depending on the chosen identity provider.

Parameters:
Name Type Attributes Description
provider "password" | "phone"

The provider associated with the identity, which to send the OTP to. Currently, possible values are "password" (for email-based identities) or "phone" (for phone-based identities)
id string

The identifier of the identity, which to send the OTP to
message <optional>

The parameters to apply to OTP message to be sent

Properties
Name Type Attributes Default Description
template string <optional>
 "login"

The identifier of the OTP message to send to the user. It must be picked among the template messages defined in the Webcom developer console.
sender string <optional>

(phone-based identities only)
The identifier of the SMS sending implementation to use to send the OTP message to the user (the implementations must be set up in the Webcom developer console).
locale string <optional>

The locale of the OTP message to send to the user (e.g. en for English whatever its variant, en_US for the american English, etc.). It must be in the ll_CC format, where ll is the ISO 639 alpha-2 code for the language and CC is the ISO 3166 alpha-2 code for the country variant.
Returns:

The returned promise will be resolved once the OTP successfully sent with the corresponding OTP identifier or challenge. This identifier is required for further methods such as Authentication#signInWithCredentials.

Type
Promise.<string>

sendPasswordResetCode(provider, id, messageopt) → {Promise}

Sends a code to the user, which allows her⋅him to reset her⋅his password for a given Webcom internally manged identity. Currently, only email-based identities are supported (parameter provider equal to "password").

Parameters:
Name Type Attributes Description
provider "password"

The internal provider of the identity, which to send the password reset code to. Currently, only "password" is supported.
id string

The identifier of the identity, which to send the password reset code to.
message <optional>

The message template to use to send the password reset code

Properties
Name Type Attributes Default Description
template string <optional>
 "password-reset"

The identifier of the message to send to the user. It must be picked among the template messages defined in the Webcom developer console.
locale string <optional>

The locale of the message to send to the user (e.g. en for English whatever its variant, en_US for the american English, etc.). It must be in the ll_CC format, where ll is the ISO 639 alpha-2 code for the language and CC is the ISO 3166 alpha-2 code for the country variant.
Returns:
Type
Promise

sendVerificationCode(provider, id, messageopt) → {Promise.<string>}

Sends a code to the user, which makes it possible to verify one of her⋅his unverified identities internally managed by Webcom (i.e. email- and phone-based identities). This method fails on an already verified identity.

Parameters:
Name Type Attributes Description
provider "password" | "phone"

The internal provider that manages the identity to verify. Current supported values are "password" (for email-based identities) and "phone" (for phone-based identities).
id string

The identifier of the identity to verify. It is either an email address (for email-based identities) or a MSISDN without the "+" prefix (for phone-based identities).
message <optional>

The message template to use to send the verification code to the user

Properties
Name Type Attributes Default Description
template string <optional>
 "create"

The identifier of the verification message to send to the user. It must be picked among the template messages defined in the Webcom developer console.
sender string <optional>

(phone-based identities only)
The identifier of the SMS sending implementation to use to send the verification message to the user (the implementations must be set up in the Webcom developer console).
locale string <optional>

The locale of the verification message to send to the user (e.g. en for English whatever its variant, en_US for the american English, etc.). It must be in the ll_CC format, where ll is the ISO 639 alpha-2 code for the language and CC is the ISO 3166 alpha-2 code for the country variant.
Returns:

A promise that will be resolved once the verification message successfully sent. In case of success, the resolve callback is passed a "challenge" string that must be used to eventually verify the identity using the Authentication#verifyIdentity method.

Type
Promise.<string>

signInAsGuest() → {Promise.<Authentication.AuthenticationDetails>}

Authenticates the user using a guest temporary account (to be lost at next sign out or at authentication token expiration) with no explicit credentials.

Returns:
Type
Promise.<Authentication.AuthenticationDetails>

signInWithCredentials(provider, credentials) → {Promise.<Authentication.AuthenticationDetails>}

Authenticates the user using a given Webcom internally managed authentication method among:

  • Email-based authentication, with a personal password as credentials,
  • Phone-base authentication, with a one time password (OTP) as credentials. In this case, an OTP must be sent to the user beforehand using the Authentication#sendOtp method and the returned challenge identifier must be kept (see the credentials.challenge parameter).
Parameters:
Name Type Description
provider "password" | "phone"

The authentication method to use: "password" for email-based authentication or "phone" for phone-based authentication.
credentials

The user's credentials. Their content depends on the chosen authentication method.

Properties
Name Type Attributes Description
id string

The identifier of the user's identity. For email-based authentication, it is her⋅his email address, for phone-based authentication, it is her⋅his MSISDN (without the "+" prefix, eg: "33612345678").
challenge string <optional>

(mandatory for phone-based authentication only)
The challenge identifier associated with the one time password sent to the user to sign in.
password string

The personal password of the user (for email-based authentication) or the one time password received by the user on her⋅his mobile phone (for phone-based authentication).
Returns:
Type
Promise.<Authentication.AuthenticationDetails>

signInWithCustomProvider(provider, credentials) → {Promise.<Authentication.AuthenticationDetails>}

Authenticates the user using credentials provided by a third-party ad-hoc identity provider.

Parameters:
Name Type Description
provider string

Identifier of the custom provider to use.
credentials string

Credentials for the user to authenticate, to be supplied by the 3rd-party identity provider.
See:
Returns:
Type
Promise.<Authentication.AuthenticationDetails>

signInWithOAuth(provider, optionsopt) → {Promise.<(Authentication.AuthenticationDetails|string)>}

Authenticates the user using a 3rd-party OAuth2 provider.

Parameters:
Name Type Attributes Description
provider string

The OAuth2 provider to use. Please refer to Login with OAuth2.0 for more details.

Currently, supported providers are:

  • facebook
  • google
  • apple
  • github
  • gitlab
  • orange
  • mobileconnectOFR (Orange France)
  • mobileconnectOJO (Orange Jordan)
  • mobileconnectOMG (Orange Madagascar)
  • mobileconnectOMA (Orange Morocco)
  • mobileconnectOCI (Orange Ivory Coast)
  • mobileconnectOEG (Orange Egypt)
  • mobileconnectOCD (Orange Congo)
  • mobileconnectOBW (Orange Botswana)
  • mobileconnectOGN (Orange Guinea Conakry)
  • mobileconnectOTN (Orange Tunisia)
  • mobileconnectOSN (Orange Senegal)
  • mobileconnectOGW (Orange Guinea Bissau)
  • mobileconnectOCM (Orange Cameroon)
  • mobileconnectOLR (Orange Liberia)
  • mobileconnectOML (Orange Mali)
  • mobileconnectONE (Orange Niger)
  • mobileconnectOBF (Orange Burkina Faso)
options <optional>

The authentication options to use.

Properties
Name Type Attributes Default Description
mode "popup" | "redirect" | "code" <optional>
 "popup"

Currently 3 authentication modes are supported:

  • "popup": the calling window opens a popup window to play the OAuth2 authorization call-flow and closes it when completed,
  • "redirect": the calling window is redirected to the OAuth2 provider authentication endpoint and will be reloaded at the end of the authorization call-flow.
  • "code": this mode is relevant when using an OAuth2 provider-specific SDK to play the authorization call-flow and that SDK returns an OAuth2 authorization code. In this case, the returned code must be provided in the code parameter.
scope string <optional>

mode "popup" or "redirect" only
The OAuth2 scope requested to OAuth2 provider. This value is provider-specific and documented in the OAuth API of the targeted provider.
If not set, the minimal scope is used (see the Default Scope section).
code string <optional>

mode "code" only
The OAuth2 authorization code to use.
state string <optional>

mode "code" only
The OAuth2 state parameter to use.
popupFeatures * <optional>

mode "popup" only
Customization properties of the popup window (among the ones accepted by the features parameter of the window#open method).
See:
Returns:
Type
Promise.<(Authentication.AuthenticationDetails|string)>

signInWithServerKey(serverKey, privateKey) → {Promise.<Authentication.AuthenticationDetails>}

This method is available on Webcom SDK for Node.js ONLY.
Authenticates a server with an RSA public/private key pair associated with this server. In order to work, the public/private key must be provisioned on the Webcom developer console beforehand.
Take care of keeping the key PRIVATE on your server to ensure the safety of this authentication!

Parameters:
Name Type Description
serverKey string

The name of the server key (as defined in the Webcom developer console).
privateKey string | object

The private key to use for singing the authentication request to the Webcom back end. It may be passed:

  • either as a string: in this case, it refers to the PEM file containing the private key
  • either as a JSON object with the key property.
Properties
Name Type Description
key string

The content of the private key in the PEM format.
Since:
  • 3.1
See:
Returns:
Type
Promise.<Authentication.AuthenticationDetails>

signInWithToken(token) → {Promise.<Authentication.AuthenticationDetails>}

Authenticates a user with a Webcom token. This method is mainly intended for Node.js back end applications.

Parameters:
Name Type Description
token string

The Webcom token for authentication
Returns:
Type
Promise.<Authentication.AuthenticationDetails>

signInWithWassup(options) → {Promise.<(Authentication.AuthenticationDetails|string)>}

Authenticates the user implicitly based on the Orange Wassup Translator service. This method works only for mobile devices connected through the Orange mobile data network. It is rather intended to Webcom mobile SDKs, it should not be needed in pure JavaScript applications.

Parameters:
Name Type Description
options

The authentication options to use.

Properties
Name Type Description
mcc string

The Mobile Country Code of the SIM card used by the device to connect the data network.
The "wisp" value may also be used for countries that don't use a WaaaT server.
See:
Returns:
Type
Promise.<(Authentication.AuthenticationDetails|string)>

signOut() → {Promise}

Signs the currently authenticated user out.

Returns:
Type
Promise

subscribe(callback, firstopt) → {Authentication.SubscriptionCallback}

Subscribes to the authentication state maintained by this service.

Parameters:
Name Type Attributes Default Description
callback Authentication.SubscriptionCallback

The function that receives authentication state changes.
first boolean <optional>
 true

Indicates when the passed callback will be called on a notification event:
if true the callback is called first but after already subscribed callbacks in first=true mode,
if false the callback is called last but before already subscribed callbacks in first=false mode.
Returns:

The passed callback. It is intended to be passed to the Authentication#unsubscribe method, especially when the callback parameter is given as an inline function.

Type
Authentication.SubscriptionCallback

unsubscribe(callbackopt, firstopt) → {number}

Unsubscribes a given callback from the authentication state maintained by this service.

Parameters:
Name Type Attributes Description
callback Authentication.SubscriptionCallback <optional>

The callback function to unsubscribe. If not specified, unsubscribes all callbacks.
first boolean <optional>

If specified, unsubscribes the callback among the ones subscribed with the given first parameter (see Authentication#subscribe), otherwise unsubscribes the callback whatever its subscribed mode.
Returns:

The count of actually unsubscribed callback functions.

Type
number

updateIdentityProfile(data, pathopt) → {Promise}

Updates some data within the profile associated with the currently authenticated email- or phone-based identity. This method fails if no user is currently authenticated or if the currently authenticated user is not identified with an email- or phone-based identity.

Parameters:
Name Type Attributes Default Description
data any

The new profile data to set (as a JSON value).
path string <optional>
 "/"

The path within the profile where to set the data, given as a slash-separated string.
Returns:
Type
Promise

updatePassword(id, currentPassword, newPassword) → {Promise}

Changes the password of an existing email-based identity (this method doesn't require to be authenticated).

Parameters:
Name Type Description
id string

The email address of the identity, the password of which has to be updated
currentPassword string

The current password of the identity
newPassword string

The new password to set
Returns:
Type
Promise

useCurrentContextForNextAuthOperation()

After this method is called, the next authentication operation will be performed in the context of the current authentication state. An authentication request will end in a multi-factor token (including at least the identity currently signed in). An identity creation request will add a new identity to the currently signed in Webcom account.

Once the next authentication operation performed, the effect of this method is forgotten, that is, further authentication operations are executed starting from an empty authentication context event if a user is authenticated.
If you need to cancel the effect of this method before the next authentication operation, simply call the Authentication#useNewContextForNextAuthOperation method.

useNewContextForNextAuthOperation()

Cancels the effect of the Authentication#useCurrentContextForNextAuthOperation method. Once called, the next authentication operation will be performed without any context of authentication state, even if a user is currently signed in.

verifyIdentity(provider, id, data) → {Promise.<Authentication.AuthenticationDetails>}

Verifies an identity newly created using the Authentication#addIdentity method. If the verification is successful, this method also signs the user in with this identity.

Parameters:
Name Type Description
provider "password" | "phone"

The internal provider used to create the identity to verify. Currently, only "password" (for email-based identities) and "phone" (for phone-based identities) are supported.
id string

The identifier of the identity to verify. For email-based identities, it is an email address. For phone-based identities, it is a MSISDN (without the "+" prefix).
data

The verification data.

Properties
Name Type Description
token string

(email-based identities only)
The verification token received by the user at her⋅his email address.
auth *

(phone-based identities only)
The authentication data returned by the Authentication#addIdentity method that created the identity to verify.
password string

(phone-based identities only)
The one time password received by the user at her⋅his MSISDN.
Returns:
Type
Promise.<Authentication.AuthenticationDetails>

Type Definitions

API

Constants and static methods associated to the Authentication service.

Such an object is available through the Webcom.Authentication property.

Properties:
Name Type Description
avatarURL Authentication.avatarURL

Function that gets the user's avatar URL (if known) from the identity referred to by an authentication state.
Since:
  • 3.5

AuthenticationDetails

Provides all the attributes of a succeeded authentication, following the model of the Webcom Authentication Service.

Properties:
Name Type Attributes Description
uid string

Webcom account unique identifier.
provider string

The authentication provider.
providerUid string

Account uid within the base of the 3rd-party provider.
providerProfile Object <optional>

Provider-specific data about the account, provided by the 3rd-party provider.
extra Object <optional>

Additional provider-specific data that will not be saved within the local storage. They typically include sensitive pieces of information such as the OAuth access token.
webcomAuthToken string

The authentication token.
expires number

The expiration date of the authentication (in seconds since the Unix epoch).
Since:
  • 2.11
See:

avatarURL(user) → {string|undefined}

Function that gets the user's avatar URL (if known) from the identity referred to by an authentication state.

Such a function is available through the avatarURL property of the Webcom.Authentication property.

Parameters:
Name Type Description
user Authentication.AuthenticationDetails

The authentication details of the user (can be found in authentication state objects).
Since:
  • 3.5
Returns:

The user's avatar URL if known or undefined otherwise.

Type
string | undefined

Configuration

Represents the description of the configuration of an Authentication associated with a WebcomApp. It is typically passed to the Authentication property of a WebcomApp.Configuration.

Properties:
Name Type Attributes Description
from WebcomApp <optional>

If set, the configured WebcomApp will share its Authentication with the one of the given WebcomApp instance. In this case, all other properties are meaningless.
baseUrl URL | string <optional>

Base URL for the Authentication.
If not set, the Webcom standard one is used.
storage string | function <optional>

Specifies where to store the authentication state of the Authentication:

  • If a string is given, it is interpreted as a storage key in the browser localStorage,
  • If a function is given, it will be called each time the state must be stored with its JSON serialized value as argument,
  • Otherwise, the localStorage is used with a key specific to the associated WebcomApp.
initialState string <optional>

JSON serialization of the initial Authentication.State of the Authentication to create. If not set:

  • If the storage property is given as a string, the state is initialized with the value stored at the given key within the browser localStorage,
  • If the storage property is given as a function, the state is initialized as unauthenticated,
  • If no storage property is set, the state is read from the browser localStorage at a key specific to the associated WebcomApp.
Since:
  • 3.0

SubscriptionCallback(errornullable, statenullable)

A callback function that is called when the authentication state changes. Such a callback is registered or unregistered using the Authentication#subscribe and Authentication#unsubscribe methods.

Parameters:
Name Type Attributes Description
error Error <nullable>

If not null, indicates that the last authentication-related operation failed.

Properties
Name Type Description
code string

A machine-readable code that identifies the error.
message string

A human-readable description of the error.
state Authentication.State <nullable>

Relevant only when error is null
Indicates the new authentication state resulting from the last successful authentication-related operation. Is null in case of error, that is, if error is not null.
Since:
  • 3.0
See:
show
deprecated