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. in the WSO2 Identity Server. This feature allows you to define a dynamic authentication sequence using authentication scripts written in JavaScript. For more information, see Adaptive Authentication.

This document contains the core API reference for the JavaScript-based conditional authentication functions and fields. the following are the sections available in this documentation.

Core functions

onInitialRequest(context)

The function that gets called when the initial authentication request is received by the framework. The authentication context is also passed as a parameter, which contains the context information about the request.

executeStep(stepId, options, eventCallbacks)

The function that is called to execute an authentication step. Authentication steps need to be configured in order to use this function. This method accepts an object as a parameter, which should contain the following.

• ‘stepId’ : The step no (Mandatory)
• ‘options’ : (IS 5.7.0+) An optional map that can configure the step execution. Currently supports authentication option filtering (see section below).   
• ‘eventCallbacks’: The object that contains the callback functions to be called based on the result of the step execution. Supported results are “onSuccess” and “onFail”, which can have their own optional callbacks as anonymous functions. (Optional)

Authentication step filtering

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

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

Utility functions

hasRole(user, role)

Returns true if the user given by ‘user’ (type: user object) has the role given by ‘role’. False if the user haven’t.

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

sendEmail(user, templateId, placeholderParameters)

Sends an email to the user given by ‘username’. The email body will be taken from the email template configured by ‘templateId’, and the ‘placeholderParameters’ will be used to replace any placeholders in the template.

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

sendError(url,parameters)

Sends the user to an error page defined by ‘url’. If url is provided as null, It will default to the ‘retry.do’ error page. In addition the key value map passed as parameters will be converted to query parameters in the URL.

Note that any relative URL will assumed as relative to host’s root.  

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.'});
}

setCookie(response, name, value, properties)

Sets a cookie named ‘name’ with the value as ‘value’. ‘Properties’ is a map that may contain optional attributes of the cookie with two other custom attributes ‘encrypt’ and‘sign’.

If ‘sign’ is true, then the value will be signed. Default value will be false.

If ‘encrypt’ is true, then value will be encrypted. Default value will be false.

Here is a sample function

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

Size of the value has to be less than the RSA key pair length if the encrypt is enabled.

getCookieValue(request, name, properties)

Get the plan text cookie value for cookie ‘name’ if present.  ‘Properties’ is an optional map that may contain optional attributes ‘decrypt’ and ‘validateSignature’.

If ‘validateSignature’ is true, then the signature will be validated before returning. Default value will be false.

If ‘decrypt’ is true, then value will be decrypted. Default value will be false.

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

callAnalytics(metadata, payloadData, eventHandlers)

Call analytics engine (at the moment WSO2 Stream Processor 4.2.0) to get decision.

• metadata: metadata is a JSON object and it can has below attributes.

• Application: Siddhi application name (mandatory)

• InputStream: Input stream name (mandatory)

• payloadData: data need to send to the analytics engine

• eventHandlers: callback event handlers

publishToAnalytics(metadata, payloadData)

Publish data to analytics engine (at the moment WSO2 Stream Processor 4.2.0).

• metadata: metadata is a json object and it can has below attributes.

• Application: Siddhi application name (mandatory)

• InputStream: Input stream name (mandatory)

• payloadData: data need to send to the analytics engine

prompt(templateId, data, eventHandlers)

Prompt for user input.

• templateId: Identifier of the template need to be prompted

• data: data to send to the prompt

• eventHandlers: callback event handlers

function onInitialRequest(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);
			 }
		   });
       }
   });
}

Object Reference

context Object

Contains the authentication context information. They can be accessed as belows,

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

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

• context.request: Access the http authentication request information. See “request” for more information.
• context.response: Access the http response which will be sent back to the client. See “response” 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 still not executed. See “user” for more information
• step.idp: Gives the Idp name which was used to authenticate this user.

user Object

• user.username: The user’s username.
• user.tenantDomain: The user’s tenant domain (only for local users, Federated users will have this as carbon.super).
• user.userStoreDomain: user’s userstore domain (only for local users).
• user.roles: 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.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>”]: Request’s parameter value for the given parameter name by <parameter_name>
• 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

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