Identifier-first Authentication

Identifier-first authentication allows identifying the individuals prior to authenticating them. It retrieves the identity of the user without using authentication information and uses that identity to control the authentication flow.

You can implement identifier-first authentication using a custom local authenticator. For more information, see Identifier-first Flow Handler. WSO2 Open Banking consists of an identifier-first authenticator by default. Configure identifier-first authentication in two stages as given in the below instructions:

  • Before server start
  • After server start

Before server start

If you have not started the Identity Server and API Manager servers, follow the below instructions to configure identifier-first authentication.

  1. Locate the following configuration in <IS_HOME>/repository/conf/deployment.toml and update the value of the parameters.authRequestURL
    configuration with the host name of the Identity Server:

    name = "IdentifierExecutor"
    parameters.ValidateUsername = true
    parameters.throttleLimit = 3
    parameters.throttleTimePeriod = 300
    parameters.authRequestURL = "https://<IS_HOST>:9446/api/identity/auth/v1.1/data/AuthRequestKey/"
    EnableAccountLockingForFailedAttempts = true
    BackupCode = false
    TokenExpiryTime = 60

  2. Add the following configuration in <IS_HOME>/repository/conf/deployment.toml to make the default identifier-first authenticator the primary authenticator:

    name = "IdentifierExecutor"
    display = "ob-identifier-first"

  3. Update the <IS_HOME>/repository/conf/common.auth.script.js file with the following steps:

    var psuChannel = 'Online Banking';
    function onLoginRequest(context) {
        publishAuthData(context, "AuthenticationAttempted", {'psuChannel': psuChannel});
    var doLogin = function(context) {
        executeStep(1, {
            onSuccess: function (context) {
                //identifier-first success
  "Authentication Successful");
                publishAuthData(context, "AuthenticationSuccessful", {'psuChannel': psuChannel});
            onFail: function (context) { //identifier-first fail
  "Authentication Failed");
                publishAuthData(context, "AuthenticationFailed", {'psuChannel': psuChannel});
    var OTPFlow = function(context) {
        executeStep(2, {
            onSuccess: function (context) {
                context.selectedAcr = "";
                publishAuthData(context, "AuthenticationSuccessful", {'psuChannel': psuChannel});
            onFail: function (context) {
                publishAuthData(context, "AuthenticationFailed", {'psuChannel': psuChannel});

  4. If you are using WSO2 Open Banking Identity Server Accelerator Level or above, add the following configuration to the <IS_HOME>/repository/conf/deployment.toml file to set authenticator steps.

    name = "<IDP_NAME>"
    step = "<IDP_STEP>"

    For example, to add the SMS Authenticator IDP named SMSAuthentication as the second authenticator step, add the following configuration:

    name = "SMSAuthentication"
    step = "2"

After server start

If you have already started the Identity Server and API Manager servers, follow the below instructions to configure identifier-first authentication.

Configuring SMS OTP authenticator

  1. Sign in to WSO2 Identity Server Management Console at https://<IS_HOST>:9446/carbon.
  2. On the Main tab, click Home > Identity > Identity Providers > Add. select-identity-providers
  3. Give Identity Provider Name as SMSAuthentication. identity-provider-name
  4. Expand Federated Authenticators > SMS OTP Configuration.
  5. Select both the Enable and Default checkboxes. This is to enable and make the SMSAuthentication authenticator the default one. Based on your SMS provider, fill out the SMS OTP configurations.


    Currently, WSO2 Identity Server supports only the following SMS providers.

    • Twilio
    • Nexmo
    • Clickatell
    • Plivo
    • Bulksms

    If Twilio is used as the SMS provider,

    1. Go to and create an account.
    2. While registering the account, verify your mobile number and click on console home to get free credits (Account SID and Auth Token).
    3. Twilio uses a POST method with headers and the text message and phone number are sent as the payload. So the fields would be as follows:

    HTTP Method POST
    HTTP Headers Authorization: Basic base64{AccountSID:AuthToken}
    HTTP Payload Body=$ctx.msg&To=$ctx.num&From=urlencode{TrialNumber}


    If you pass the text message and the phone number in any field, you have to replace them with $ctx.num and $ctx.msg respectively. For example, Body=$ctx.msg&To=$ctx.num&From=+12345678.


  6. Click Register to add the Identity Provider.

Configure account locking

  1. On the Main tab, click Home > Identity > Identity Providers > Resident. select-resident
  2. Expand Login Attempts Security > Account Lock. expand-account
  3. Select Lock user accounts and click Update. enable-account-locking

Configure mobile as a mandatory claim

  1. On the Main tab, click Home > Identity > Claims > List.


  2. Select from the list. select-claim-from-list

  3. Locate Mobile from the list and select Edit. select-mobile
  4. Select Required and click Update. select-required-and-update