JavaScript CIBA-mapping rule

This document covers all the interfaces available for CIBA JavaScript mapping rule.

1. STSUniversalUser

In CIBA JavaScript mapping rule, the CIBA hint is available under AttributeContainer and all the request parameters are available under ContextAttribute section.

When the hint is coming from the login_hint parameter, the value can be retrieved directly from the login_hint request parameter or from the attribute sub in the AttributeContainer.

When the hint is coming from the login_hint_token or id_token_hint parameters, which are in the form of JWT, the JWT information is displayed in the AttributeContainer.

For more information, see STSUniversalUser.

2. Client and definition

In the CIBA-mapping rule JavaScript, the Client object is under oauth_client and the Definition object is underoauth_definition.

3. ciba object

The other object that is displayed in the mapping rule is the ciba object.

3.1. ciba object for notify user JavaScript

The notify user JavaScript is used to notify the hinted user about this CIBA authentication request. At the end of the JavaScript, the expectation is to let the system know what is the type of authenticator used.

The flow in the JavaScript might be as follows:

• Based on user hint, retrieve more information about this user, such as:
  • Notification preference
  • User device information
  • Email or phone number
• Validate the incoming user_code (if any)
• Validate whether binding_message is acceptable. For example, when the user is notified by SMS rather than email, the maximum length differs.
• Decide the type of authenticator used, and notify the user. Some of the possible scenarios are:
  • When an internal authenticator is used, send the user authorization endpoint as part of the notification message to the user. The notification message might depend on notification preference such as email or SMS.
  • When an external authenticator with check status endpoint is used, call the external authenticator with the information about the user to be notified. Expect that the external authenticator returns with the URL to check the status.
    Set this URL in the ExternalAuthenticatorWithCheckStatusEndpoint() object.
  • When an external authenticator without check status endpoint is used, call the external authenticator with the information about the user to be notified. Also, include the status update endpoint, and the bearer token to be used. The expectation here, the external authenticator does a callback to the status update endpoint after the authentication is done.

3.1.1. InternalAuthenticator

Use this setting when user authentication is done through the hosted endpoint /oauth2/ciba_user_authorize.

Example usage:

  ciba.setAuthenticator(new InternalAuthenticator());

3.1.2. ExternalAuthenticator

Use this setting when user authentication is done by external authenticator that can notify the authorization server when the authentication is done, by calling the /oauth/ciba_status_update endpoint.

Example usage:

  ciba.setAuthenticator(new ExternalAuthenticator());

3.1.3. ExternalAuthenticatorWithCheckStatusEndpoint

Use this setting when user authentication is done by an external authenticator. It checks authentication status endpoint, which must be called by authorization server.

To use this authenticator type, specify the checkStatusEndpoint and optionally a bearer token. The checkStatusEndpoint must contain the full URL and include any id that is needed to identify this particular transaction. When a bearer token is not specified, it is assumed this endpoint doesn't require a bearer token.

Example usage:

  ciba.setAuthenticator(new ExternalAuthenticatorWithCheckStatusEndpoint(checkStatusEndpoint, bearer));

3.2. ciba object for Check Status JavaScript

The check status JavaScript is used to call the external authenticator check status endpoint and return the status result. However, after the user is authenticated, it is also expected to gather information about the user that can be used for token enrichments. The system is at least looking for an attribute uid (or attribute as indicated in subject_attribute_name) in the metadata, which becomes the sub of the id_token.

At the end of JavaScript, either pending(), failed() or success() is called.