Adaptive Authentication JS API Reference¶

With adaptive authentication, it is possible to configure dynamic sequences based on runtime parameters such as the user’s IP address, user role, etc. WSO2 Identity Server allows you to define a dynamic authentication sequence using authentication scripts written in JavaScript.

For more information on adaptive authentication, see Adaptive Authentication

The following sections present the core API reference for the JavaScript-based conditional authentication functions and fields.

Core functions¶

onLoginRequest(context)¶

This function is called when the initial authentication request is received by the framework. It includes the following parameters.

executeStep(stepId, options, eventCallbacks)¶

This function is called to execute an authentication step. Authentication steps need to be configured prior to using this function. This method accepts an object as a parameter and should include the following.

The API can be called in either of the following ways:

• With only the stepId . Example:

  executeStep(1)

• With only the stepId and eventCallbacks . Example:

  executeStep(1, {
      onSuccess: function(context) {
          //Do something on success
      }
  });

• With the stepId, options, and an empty eventCallbacks array. Different properties can be defined in the options object such as authenticationOptions, authenticatorParams, stepOptions. See the following examples:

  executeStep(1,{
      authenticationOptions:[{
          authenticator: 'totp'
      }]},
  }, {});

  executeStep(1, {
      authenticatorParams: {
          local: {
              SessionExecutor: {
                  MaxSessionCount: '1'
              },
              totp: {
                  enableRetryFromAuthenticator: 'true'
              }
          }
      }
  }, {} );

  executeStep(1, {
      stepOptions: {
          forceAuth: 'true'
      }
  }, {} );

  Note

  The API cannot be called with only the stepId and options .

Authentication step filtering

Filters out some of the authentication options of a step based on a condition. This can be achieved by specifying an array named ‘ authenticationOptions ’ to the options map. Each array item will require an ' idp' for federated IdPs or an ' authenticator' for local authenticators.

Example code

executeStep(1,{
  authenticationOptions:[{authenticator:'basic'},{idp:'google'}]
   },{
       onSuccess: function (context) {
           // Do something on success
};

Authentication step options

stepOptions is an optional property that can be defined in the executeStep. This will allow adding the additional forceAuth authentication option. The forceAuth option can force the authenticator in the steps to prompt again event if it was already authenticated.

Example code

executeStep(1, {
    stepOptions: {
        forceAuth: 'true'
     }
}, {});

Utility functions¶

The implementation of utility functions can be found in the WSO2 extensions code repository.

hasRole(user, role)¶

This function returns true if the specified ‘ user ’ belongs to the specified ‘ role ', and returns false if the user does not. It includes the following parameters.

Example code

var user = context.steps[1].subject;
var isAdmin = hasRole(user, 'admin');
Log.info('--------------- Has Admin ' + isAdmin);
if (isAdmin) {
    executeStep(2);
}

assignUserRoles(user, assigningRoles)¶

This function assigns each of the roles specified in the ‘ assigningRoles ’ parameter to the specified ‘ user ’ object. It returns true if all the roles are successfully assigned and returns false if not.  It includes the following parameters.

executeStep(1, {
    onSuccess: function (context) {
        // Extracting authenticated subject from the first step.
        let user = context.currentKnownSubject;
        assignUserRoles(user, ['exampleRole1', 'exampleRole2']);
    }
});

removeUserRoles(user, removingRoles)¶

This function removes each of the roles specified in the ‘ removingRoles ’ parameter to the given ‘ user ’ object. It returns true if all the roles are successfully removed and returns false if not. It includes the following parameters.

executeStep(1, {
    onSuccess: function (context) {
        // Extracting authenticated subject from the first step.
        let user = context.currentKnownSubject;
        removeUserRoles(user, ['exampleRole1', 'exampleRole2']);
    }
});

sendEmail(user, templateId, placeholderParameters)¶

This function sends an email to the specified user. It includes the following parameters.

Example code

var user = context.steps[1].subject;
var firstName = user.localClaims['http://wso2.org/claims/givenname'];
sendEmail(user, 'myTemplate', {'firstName':firstName});

sendError(url,parameters)¶

This function redirects the user to an error page. It includes the following parameters.

Example code

var user = context.steps[1].subject;
var isAdmin = hasRole(user, 'admin');
if (!isAdmin) {
    sendError('http://www.example.com/error',{'errorcode':'000403','errorMsg':'You are not allowed to login to this app.'});
}

fail()¶

This function redirects the user to the redirect URI provided in the authorization request failing the authorization flow.

This function takes a map as an optional parameter. When a map is provided as the parameter, the redirect URL will be appended with following properties which should be contained in the map, otherwise the default parameters will be passed. All the properties passed in the map are also optional.

Example code

var parameterMap = {'errorCode': 'access_denied', 'errorMessage': 'login could not be completed', "errorURI":'http://www.example.com/error'};
if (!isAuthenticated) {
    fail(parameterMap);
}

setCookie(response, name, value, properties)¶

This functions sets a new cookie. It includes the following parameters.

setCookie(context.response, "name", "test", {"max-age" : 4000,
                                            "path" : "/",
                                            "domain" : "localhost",
                                            "httpOnly" : true,
                                            "secure" : true,
                                            "version" : 1,
                                            "comment" : "some comments",
                                            "encrypt" : true,
                                            "sign" : true})

getCookieValue(request, name, properties)¶

This function gets the plain-text cookie value for the cookie ‘ name ’ if present.  It includes the following parameters.

getCookieValue(context.request,"name", {"decrypt" : true,"validateSignature" : true })

callAnalytics( metadata, payloadData, eventHandlers )¶

This function calls the analytics engine (i.e., WSO2 Stream Processor) to get a decision. It includes the following parameters.

publishToAnalytics( metadata, payloadData )¶

This function publishes data to the analytics engine (WSO2 Stream Processor). It includes the following parameters.

prompt(templateId, data, eventHandlers)¶

This function prompts for user input. It includes the following parameters.

var onLoginRequest = function(context) {
   executeStep(1, {
       onSuccess: function (context) {
           var username = context.steps[1].subject.username;
           prompt("genericForm", {"username":username, "inputs":[{"id":"fname","label":"First Name"},{"id":"lname","label":"Last Name"}]}, {
             onSuccess : function(context) {
                var fname = context.request.params.fname[0];
                var lname = context.request.params.lname[0];
                Log.info(fname);
                Log.info(lname);
             }
           });
       }
   });
}

getUserSessions(user)¶

This function returns a session object (i.e. all the active user sessions of the specified user and returns an empty array if there are no sessions). It includes the following parameters.

var user = context.currentKnownSubject;
var sessions = getUserSessions(user);
for (var key in sessions) {
    Log.info(“Session ID: ” + sessions[key].id);
}

terminateUserSession(user, sessionId)¶

This function returns a session object (i.e. all the active user sessions of the specified user and returns an empty array if there are no sessions). It includes the following parameters.

var user = context.currentKnownSubject;
var sessions = getUserSessions(user);
if (sessions.length > 0) {
    var result = terminateUserSession(user, sessions[0]);
    Log.info(“Terminate Operation Successful?: ” + result);
}

getValueFromDecodedAssertion(String jwt, String parameterName,boolean isParameterInPayload)¶

This function returns a string which contains the value of the parameter in a decoded JWT. It includes the following parameters:

The following example shows how to obtain a parameter from the request object, which is a signed jwt.

var state = getValueFromDecodedAssertion(context.request.params.request[0],"state",true);

getUniqueUserWithClaimValues(claimMap, context, profile)¶

The utility function will search on the underlying user stores and return a unique user with the claim values. The claim map will consist of the claim and value. The function will get the first key from the map and get all users with the claim and add them to the list. Then, remove the users that do not have the other claims from that list. Thereby, the order of the map will decide the performance of this function. The first claim in this must have a low number of users.

var claimMap = {};
claimMap[MAPPED_FEDERATED_USER_NAME_CLAIM] = federatedUserName;
claimMap[MAPPED_FEDERATED_IDP_NAME_CLAIM] = idpName;
var mappedUsername = getUniqueUserWithClaimValues(claimMap, context);

getAssociatedLocalUser(federatedUser)¶

This function prompts user input. It includes the following parameters.

doAssociationWithLocalUser(fedUser, localUsername, tenantDomain, userStoreDomain)¶

This function prompts user input. It includes the following parameters.

Object Reference¶

context Object¶

Contains the authentication context information. The information can be accessed as follows.

• context.steps[<n>] :  Access the authentication step information, where <n> is the step number (1-based). See step Object for more information.

  Note

  The step number is the one configured at the step configuration, not the actual order in which they get executed.

• context.request :  Access the HTTP authentication request information. See request Object for more information.

• context.response :  Access the HTTP response which will be sent back to the client. See response Object for more information.
• context.serviceProviderName :  Get the application name.

step Object¶

Contains the authentication step information. May be null or invalid step number.

• step.subject :  Contains the authenticated user’s information from this step. May be null if the step is not yet executed. See user Object for more information.
• step.idp :  Gives the Idp name which was used to authenticate this user.

user Object¶

• user.username : (Read/Write) The user’s username.
• user.tenantDomain : (Read/Write) The user’s tenant domain (only for local users; federated users will have this as carbon.super ).
• user.userStoreDomain : (Read/Write) The user’s user store domain (only for local users).
• user.roles : (Read/Write) List of user’s roles.

• user.localClaims[“<local_claim_url>”] : (Read/Write) User’s attribute (claim) value for the given “local_claim_url”. If the user is a federated user, this will be the value of the mapped remote claim from the IdP.

• user.claims[“<local_claim_url>”]: (Read/Write) Sets a temporary claim value for the session.

  Note

  user.localClaims[“<local_claim_url>”] updates the claim value in the user store as well. user.claims[“<local_claim_url>”] is an alternative to set a claim for temporary basis.

• user.remoteClaims[“<remote_claim_url”] : (Read/Write) User’s attribute (claim) as returned by IdP for the given “remote_claim_url”. Applicable only for federated users.

request Object¶

• request.headers[“<header_name>”] : Request’s header value for the given header name by <header_name>
• request.params.param_name[0] : Request’s parameter value for the given parameter name by the <param_name> index (param_name is an array).
• request.cookies[“<cookie_name”] : Request’s cookie value for the given cookie name by <cookie_name>
• request.ip : The client IP address of the user who initiated the request. If there are any load balancers (eg. Nginx) with connection termination, the ip is retrieved from the headers set by the load balancer.

response Object¶

• response.headers[“<header_name>”] : (Write) Response header value for the given header name by <header_name>

session Object¶

• session.userAgent :  This is userAgent object of the user session.. See userAgent Object for more information.
• session.ip :  This is the session’s IP address.
• session.loginTime :  This is the session’s last login time.
• session.lastAccessTime :  This is the session’s last accessed time.
• session.id :  This is the session’s id.
• session.applications :  This is the list of application objects in the session. See application Object for more information.

application Object¶

• application.subject :  This is the subject of the application.
• application.appName :  This is the name of the application.
• application.appId :  This is the id of the application.

userAgent Object¶

• userAgent.raw :  This is the raw userAgent string.
• userAgent.browser :  This is the Web Browser property that is extracted from the raw userAgent string.
• userAgent.platform :  This is the Operating System property that is extracted from the raw userAgent string.
• userAgent.device :  This is the Device property that is extracted from the raw userAgent string.