Tutorial: Authentication state

The Webcom SDK for JavaScript represents the authentication state using a JSON object with the following properties and correspondence to the authentication state attributes:

Only the displayName and providerProfile properties are optional. The context property is mandatory but may be an empty array when the user is signed in with a single identity.

Note that this JSON object (without the webcomAuthToken property) is also embedded within the Webcom authentication token and is therefore passed to security rules.
Consequently, security rules can accommodate the authentication method or the available additional authentication factors used to sign in, as shown in this complete example.

The Webcom SDK for Android represents the authentication state using the OnAuth.Identity class with the following getters and correspondence to the authentication state attributes:

The Webcom SDK for iOS represents the authentication state using the AuthenticationDetails struct with the following properties and correspondence to the authentication state attributes:

When a user is successfully authenticated, the completion callback of the authenticate() method is called with the .success case having an AuthenticationDetails associated value.

let method = /* ... */ // any authentication method
WebcomApplication.default.authenticationService.authenticate(with: method) { result
    switch result {
    case let .failure(error):
        print("authentication failed:", error)
    case let .success(details):
        print("authenticated with:", details.provider.prettyName, "as:", details.uid)
    }
}

Authentication callbacks in JavaScript are passed two parameters:

• error: it is not null if the authentication operation that triggers the callback has failed. In this case, it is a JSON object whith 2 mandatory properties: code (the error code, see the Error messages) and message (a non-localized human-readable message).
• authState: it must be considered only if the error parameter is null. If so, it is either null if no user is currently signed in, or the JSON object representing the authenticated user if a user is currently signed in.

Authentication callback functions may be registered or unregistered using the registerAuthCallback() and unregisterAuthCallback() methods on instances of the Webcom class. All Webcom instances on the same Webcom application share their authentication callbacks (and of course, instances on different applications have separate pools of authentication callbacks). The following snippet shows a complete example (replace “<your-app>” with your actual application identifier):

// Create a reference to a Webcom application
var ref = new Webcom("<your-app>");
// Define an authentication callback
var authCb = function(error, auth) {
  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", auth);
  }
};
// Register it
ref.registerAuthCallback(authCb);
// { ...
// Within this fragment, 'authCb' is called each time the authentication state changes
// ... }
// Unregister it
ref.unregisterAuthCallback(authCb);

Authentication callbacks in Android must implement the OnAuth interface, which provides two methods:

• onComplete(): it is called when the authentication operation that triggers the callback has succeeded. If the operation was a sign in operation, this method is passed the resulting authentication state embedded into an AuthResponse. If it was a sign out operation, this method is passed null.
• onError(): it is called when the authentication operation has failed and is passed an object describing the error.

Authentication callback functions may be registered or unregistered using the registerAuthCallback() and unregisterAuthCallback() methods on instances of the Webcom class. All Webcom instances on the same Webcom application share their authentication callbacks (and of course, instances on different applications have separate pools of authentication callbacks). The following snippet shows a complete example (replace “<your-app>” with your actual application identifier):

// Create a reference to a Webcom application
try {
    Webcom ref = new Webcom(new WebcomApp("<your-app>"));
    OnAuth listener = new OnAuth() {
        @Override
        public void onComplete(@Nullable AuthResponse response) {
            if (response == null) { // Successfull Logout
                System.out.println("Logout succeeded");
            } else { // Successfull login
                Identity authState = response.getIdentity();
                System.out.println("Authentication succeeded as " + authState.getUid());
            }
        }
        @Override
        public void onError(WebcomError error) {
            System.out.println(error.getMessage());
        }
    };
    ref.registerAuthCallback(listener);
    // { ...
    // Within this fragment, 'listener' is called each time the authentication state changes
    // ... }
} catch (WebcomException e) {
    e.printStackTrace();
}

In Swift, authentication callbacks are functions receiving an AuthenticationEvent parameter.

This type is an enum with three cases:

• .authenticated indicates that an end user has signed in. This case has an AuthenticationDetails associated value.
• .notAuthenticated indicates that the end user has signed out. This case does not have an associated value.
• .rejected indicates that an authentication operation has been rejected. This case has a WebcomError associated value giving the cause of this rejection.

Registering (resp. unregistering) an authentication callback consists in subscribing to (resp. unsubscribing from) an event corresponding to the change of the authentication state. Subscribing is done with the subscribeToChange() of an AuthenticationService object. Unsubscribing is done with the unsubscribe() of the AuthenticationSubscription object returned by the subscription.

The following snippet shows a complete example:

let authenticationService = WebcomApplication.default.authenticationService // application is configured in the `Info.plist` file
authenticationService.subscribeToChange { event in
    // This code is called each time the authentication state changes.
    switch event {
    case let .authenticated(details: details):
        print("successfully authenticated as:", details.uid)
    case .notAuthenticated:
        print("logout succeeded")
    case let .rejected(cause: error):
        print("authentication failed:", error)
    }
}