Tutorial: Authentication state

The Webcom Authentication Service basically maintains an authentication state that identifies the end-user currently signed in to a given Webcom application on a given device (where the Webcom client application is executed).

The Webcom SDK provides with proper APIs to:

• update the authentication state by signing a user in or out,
• track the authentication state updates using authentication callbacks.

Authentication model

The authentication state (AuthState) gathers the following attributes about the currently signed in end-user:

• AccountUid: unique identifier of the Webcom “account” associated with the end-user. This id is unique across all users of the Webcom application whatever the authentication method used to sign in. This id should be used within the application data to refer to the end-user.

• Token: Webcom authentication token that encodes the current authentication state. If your application uses a specific backend, this token may be passed along to requests that require user privileges.

• ExpirationDate: date that the authentication state (and hence the token) is valid until.

• SignedInIdentity: “identity” used by the end-user to sign in (that is, the data recognized by some identity provider to identify the user). In Webcom model, identities in turn gather the following attributes:

  • Provider: gives the authentication method used to sign the user in. Each identity is associated to a unique and specific authentication method. Each authentication method corresponds to a specific “identity provider”, which can be external to Webcom platform. The complete list of available authentication methods or identity providers is given in the “Signing in and out” chapter.

  • ProviderUid: identifier representing the identity used to sign in. This identifier is unique relatively to the authentication method, that is, unique across all users that are authenticated by a given identity provider. However, the same identifier may refer to distinct users relatively to distinct providers. That's why this identifier is strongly discouraged to identify end-users within an application.

  • CreationDate: date/time when the identity was first associated to the Webcom account of the user. In other words, it is the creation date of the identity from the Webcom viewpoint (and not from the identity provider one).

  • DisplayName: optionally indicates (depending on the identity provider) a friendly display name for the signed-in user.

  • ProviderProfile: gives some optional additional information about the signed-in user, which is provided by the identity provider. This piece of information is completely specific to the authentication method.

  • ExtraProviderData: some optional sensible data, which are also provided by the identity provider. In contrary to the ProviderProfile, these are not stored persistently within the authentication state and are excluded from the Webcom authentication token. They typically include the user Access Token in case of an OAuth2-based authentication method.

• Context: gives the list of other identities used by the end-user to authenticate within this authentication session. In other words, a user may authenticate with several identities. The Webcom Authentication Service actually implements multi-factor authentication using multi-identity authentication. Each authentication factor corresponds to an identity of the user. Each factor contained in the authentication “context” provides in turn the following pieces of information:

  • Provider: identity provider associated with the authentication factor,
  • ProviderUid: identifier of the user (relatively to the identity provider) associated with the authentication factor,
  • SignInDate: date when the user authenticated with this factor. It is useful for example to control that a secondary factor is not too old wrt. the main one.

  Thus, when the authentication context is empty, the user is authenticated with a single factor and this “main factor” is described by the Provider and ProviderUid attributes at the first level of the authentication state. When the authentication context contains n factors (n > 0), the user is authenticated with n+1 factors. The most recent factor is the one described by the Provider and ProviderUid attributes at the first level of the authentication sate, the second-to-last one is described by the first element of the Context attribute... and the oldest factor is described by the last element of the context attribute.

Authentication callbacks

The main way to watch the current authentication state maintained by the Webcom Authentication Service is to register authentication callbacks. These functions are called each time the authentication state changes and are passed the authentication state.

If an authentication operation is performed but doesn't change the current authentication state, the callbacks are not called. If an authentication operation fails, then the current authentication state is unchanged (it remains in the previous state) and callbacks are called with the failure error.

// const app = Webcom.App("<your-app>"); // UNCOMMENT if you haven't yet an instance of your app!
// Get an instance of the authentication service
const auth = app.authentication;
// Define an authentication callback
const authCb = (error, authState) => {
  if (error) {
    switch (error.code) {
      case "INVALID_CREDENTIALS":
        console.log("The email or password is incorrect.");
        break;
      case "PROVIDER_DISABLED":
        console.log("The email/password method is disabled in the application. It must be enabled in the Webcom developer console.");
        break;
      default:
        console.log("An unexpected error occurs, please retry and contact your administrator.", error);
    }
  } else {
    console.log("Authentication succeeded");
    console.log("Authentication state", authState.state);  // "none"|"some"|"required"
    console.log("Authentication details", authState.details);
  }
};
// Register it
auth.subscribe(authCb);
// 'authCb' is called a first time with the current authentication state
// { ...
//     Within this fragment, 'authCb' is called each time the authentication state changes
// ... }
// Unregister it
auth.unsubscribe(authCb);

val myApp = WebcomApplication.default // the app defined by the 'webcom.properties' asset file
val authenticator = myApp.authenticationService

val subscription = authenticator.subscribe { // it: AuthenticationEvent
    when (it) {
        is AuthenticationState.Authenticated ->
            print("${it.details.displayName} has logged in")
        is AuthenticationState.Unauthenticated ->
            print("The user has logged out")
        is AuthenticationState.Invalid ->
            print("The previous authentication has expired, waiting for logging in or out")
        is AuthenticationEvent.Rejected ->
            print("An authentication attempt has failed: ${it.data.error.errorCode}")
    }
}
// ...and then later...
subscription.cancel()

let authenticationService = Webcom.defaultApplication.authenticationService // application is configured in the `Info.plist` file
authenticationService.subscribe { event in
    // This code is called each time the authentication state changes.
    switch event {
    case let .change(state: .authenticated(details: details)):
        print("successfully authenticated as:", details.uid)
    case .change(state: .invalid):
        print("authentication expired")
    case .change(state: .unauthenticated):
        print("logout succeeded")
    case let .failure(reason: error):
        print("authentication failed:", error)
    }
}

Limitations

1. The authentication state is purely local to the client device where the Authentication Service is executed, there is no central state (or session) maintained at the Webcom application level by the back end.
   For example, if the same user is signed in to your app both on a mobile phone and on a desktop web interface, then signing out from the mobile phone doesn't sign s/he out from the web interface.

2. Only one end-user can sign in at a time to a given Webcom application instance on the same device.
   For example, if Mary signs in first to app A on a tablet, and then Peter signs in to the same instance of app A on the same tablet (within the same user session from the tablet OS viewpoint), then Mary is eventually signed out from app A and Paul signed in to app A.

3. However, the same end-user can sign in to various application instances at a time on the same device.
   For example, Mary can sign in to both apps A and B on her tablet, or to two different instances of app A on her tablet.

4. The authentication state of a given user for a given Webcom application instance on a given device is valid until:

   • either the user signs out from this application on this device,
   • or the corresponding authentication token expires.