User Authentication with Out-of-Band SMS

Creating an Out-of-Band SMS Authentication for a User

What you need:

  • A bearer token (Access token) obtained by authenticating a privileged user (Organization Administrator, Client ID M2M) through an authentication flow

    You need a privileged user to have enough permissions to perform the actions listed below. Using a bearer token from a non-privileged user / Client ID will result in 401 / 403 HTTP responses from the HID Authentication Service APIs. To get a token, see Enabling User Authentication.

  • A created User, see Managing Users, Groups and Roles

To set up the out-of-band with SMS, we need to create and assign an Authenticator to the user, by selecting a Device based Authentication policy.

The available policies are:

  • AT_OOBSMS - Out-of-band SMS policy designed to be used with SCIM API's only

    This policy requires an activation code.

  • AT_TXOOB - Out of band SMS policy designed to be used for transaction signing

For further details regarding these authentication policies, see Authentication Policies in the HID Authentication Service.

The first step is to get the internal Id of the user, so we will search for the user whose external ID is jsmith@company.com (for further information, see Internal IDs vs External IDs).

Copy
POST https://[base-server-url]/SCIM/tenant/v2/Users/.search HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: "application/scim+json"
  
{
    "schemas":[
        "urn:ietf:params:scim:api:messages:2.0:SearchRequest"
    ],
    "filter":"externalId eq \"jsmith@company.com\"",
    "sortBy":"id",
    "sortOrder":"descending",
    "startIndex":0,
    "count":100
}

The response contains the internal ID, here 52276.

Copy
{
    "schemas":[
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults":1,
    "resources":[
        {
            "schemas":[
                "urn:ietf:params:scim:schemas:core:2.0:User",
                "urn:hid:scim:api:idp:2.0:UserDevice",
                "urn:hid:scim:api:idp:2.0:UserAttribute",
                "urn:hid:scim:api:idp:2.0:UserAuthenticator"
            ],
            "id":"52276",
            "externalId":"jsmith@company.com"
         (...)
        }
    ]
}

Now we can create the Authenticator. Simply use the Authenticator endpoint with a POST request.

Date attributes follow the ISO 8601 format (see Date formats in the SCIM API).

Copy
POST https://[base-server-url]/SCIM/tenant/v2/Authenticator HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: "application/scim+json"
 
{
    "schemas":[
        "urn:hid:scim:api:idp:2.0:Authenticator"
    ],
    "policy":{
        "value":"AT_OOBSMS"
    },
    "owner":{
        "value":"52276"
    },
    "policy": {
        "value": "AT_OOBSMS"
    },
    "activationCode":"activationSecretCode",
    "urn:hid:scim:api:idp:2.0:Action": {
        "action": "REGISTER-OOB",
        "attributes": [
            {
                "name": "OOB_DEVICETYPE_CODE",
                "value": "DT_OOBSMS"
            }
        ]
    },
    "useActivationCode": "true"
}
  • Complete the policy attribute with the required out-of-band SMS policy

  • The owner attribute points to the internal ID of the user

  • The activationCode attribute is optional and it can be an alphanumeric or numeric string

    If it's not present and useActivationCode is true or also not present, the server will generate a random value.

  • The useActivationCode attribute (boolean) is optional and the default value is true

    If set to false, no activationCode will be bound to the authenticator.

  • The Action attribute is an object containing the name of the device type associated with out-of-band SMS (DT_OOBSMS for the authenticator AT_OOBSMS) and the key word for registering the out-of-band authenticator

    When registering the authenticator type AT_TXOOB, the credential type needs to be explicitly added to the 'Action' element:

    Copy
    "urn:hid:scim:api:idp:2.0:Action": {
        "action": "REGISTER-OOB",
        "attributes": [
            {
                "name": "OOB_CREDENTIALTYPE_CODE",
                "value": "CT_TXOOB"
            },
            {
                "name": "OOB_DEVICETYPE_CODE",
                "value": "DT_TXOOB"
            }
        ]
    }

The user's authenticator is then ready. See the next section for authenticating the user against the HID Authentication Service.

The response contains new attributes:

  • The id attribute, that the HID Authentication Service generated by concatenating the user internal ID and the Authentication policy code (here 52276.AT_OOBSMS)

  • The statistics object

  • The activation code

Copy
{
    "schemas":[
        "urn:hid:scim:api:idp:2.0:Authenticator",
    ],
    "id":"52276.AT_OOBEML",
    "externalId":"jsmith@company.com",
    "meta":{
        "resourceType":"Authenticator",
        "created":"2015-05-15T18:15:21Z",
        "location":"https://[base-server-url]/SCIM/tenant/v2/Authenticator/52276.AT_OOBSMS",
        "version":"1"
    },
    "status":{
        "status":"ENABLED",
        "active":true,
        "expiryDate":"2020-05-15T18:15:21Z",
        "startDate":"2015-05-15T18:15:21Z"
    },
    "owner":{
        "type":"User",
        "display":"jsmith@company.com",
        "value":"52276",
        "$ref":"https://[base-server-url]/SCIM/tenant/v2/Users/52276"
    },
    "statistics":{
        "consecutiveFailed":"0",
        "consecutiveSuccess":"0",
        "maximumNumberOfUsages":"0",
        "totalFailed":"0",
        "totalSuccess":"0"
    },
    "policy":{
        "display":"AT_OOBSMS",
        "value":"AT_OOBSMS",
        "$ref":"https://[base-server-url]/SCIM/tenant/v2/Policy/Authenticator/AT_OOBSMS"
    },
    "activationCode":"activationSecretCode"
}

For further information about Authenticators, see Managing a User or Client ID's Authenticators.

Authenticating a User with Out-of-Band SMS using AT_OOBSMS

What you need:

The authentication of the user with out-of-band SMS is a two step process - the first step is to send the SMS to the user, then the user has to enter this secret code and authenticate.

Both steps are using the authn/token endpoint, but where some parameters in the two requests are different.

Send an SMS to the User with the Secret Code

Copy
POST https://[base-server-url]/{tenant}/authn/token HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: application/x-www-form-urlencoded
 
grant_type=password&username=jsmith@company.com&password=activationSecretCode&channel=CH_EXTRAPP&authType=AT_OOBSMS&noToken=1
Important:  
  • In this request, the password that needs to be provided is the activation code of the authenticator

  • If the activation code is incorrect, the HID Authentication Service response contains a HTTP 400 bad request error

  • Remember to URL-encode the password and username attributes!

    Failing to do so can lead to the HID Authentication Service misinterpreting the characters you pass and thus authenticators being disabled for too many wrong attempts.

The user will then receive a SMS with a secret code. This code is a numeric string of 8 characters (for example, 45895919).

Authenticate the User with the Secret Code

Copy
POST https://[base-server-url]/{tenant}/authn/token HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: application/x-www-form-urlencoded
 
grant_type=password&username=jsmith@company.com&password=45895919&channel=CH_EXTRAPP&authType=AT_OOBSMS
Important:  
  • In this request, the password that needs to be provided is the secret code received by SMS

  • If the secret code is incorrect, the HID Authentication Service response contains a HTTP 400 bad request error

  • Remember to URL-encode the password and username attributes!

    Failing to do so can lead to the HID Authentication Service misinterpreting the characters you pass and thus authenticators being disabled for too many wrong attempts.

The Response

The returned response is an access token allowing you to use the HID Authentication Service APIs and identifies your user's unique session:

Copy
{"access_token":"OdFQIwAAAW+y3ZIdJ4fdsaY6qcWpDkmQyejctRGNkp","token_type":"Bearer","expires_in":86400}

To see what we can do with the response, see Making the most of OPENID Tokens.

Transaction Validation via SMS

What you need:

The transaction validation via out-of-band SMS is a two step process - the first step is to send the SMS to the user with custom transaction content, then the user has to enter this secret code and authenticate to accept the transaction.

Send an SMS to the User with the Secret Code

Copy
POST https://[base-server-url]/{tenant}/authn/token HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: "application/scim+json"
 
{
    "schemas":[
        "urn:hid:scim:api:idp:2.0:Action"
    ],
    "urn:hid:scim:api:idp:2.0:Action": {
        "action": "DELIVER-CHALLENGE",
        "attributes":[ 
            { 
                "name":"tds",
                "value":"To validate your 50 EUR payment to ExamplePayee, please enter the code : {$secret}"
            },
            { 
                "name":"correlationid",
                "value":"1123"
            },
            { 
                "name":"DEVICETYPE",
                "value":"DT_TXOOB"
            },
            { 
                "name":"USER.EXTERNALID",
                "value":"jsmith@company.com"
            }
        ]
    }
}
  • In the tds attribute, you can customize the SMS message that the user will receive on their phone

    You can refer to the secret code using the variable {$secret}.

  • The attribute DEVICETYPE has to be fixed to DT_TXOOB

  • The attribute USER.EXTERNALID is the external ID of the user

  • The correlationid attribute is optional

    It can be used to identify the transaction with an external ID. If present, this correlationid needs to be passed as parameter in the authentication request (described in Authenticate the User with the Secret Code).

The response from the HID Authentication Service is:

Copy
POST https://[base-server-url]/{tenant}/authn/token HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: "application/scim+json"
 
{
    "schemas":[
        "urn:hid:scim:api:idp:2.0:Action"
    ],
    "attributes":[
        { 
            "name":"CHALLENGE",
            "type":"string",                              
            "value":"e0lWPdLgnNHUaLKUPqDR1m5O0q8sQUVTMn0uGbbmkgV3p7l2z+EhtyMZy8xD1ffwgdB7DSSE4XCqtLkQ5FV06aGOJjSyxIghN1M+KJa0iMkn/goP4g48aEV5djSGFIawJrzioznsgwPsgdGTXbFB8NLekgzk73XUtjxKCfELyjE48E6CEJEu1fUPFudGQe1cBnvBFWzmXhVTsuCQjqERMQkGy5s0GIHbtd+UbM4wTFELymFzjaXAp1eJkkXhP0ETG4xdqauIP9pI5H4=;RU5DX0tFWT1ISUQtSUEtNFQuQ1JFRFMuMQ==",
            "readOnly":false
        },
        { 
            "name":"CHALLENGE.ID",
            "type":"string",
            "value":"96003",
            "readOnly":false
        },
        { 
            "name":"REQUEST.STATUS",
            "type":"string",
            "value":"1",
            "readOnly":false
        },
        { 
            "name":"REQUEST.REASON",
            "type":"string",
            "value":"-1",
            "readOnly":false
        },
        { 
            "name":"REQUEST.ERROR_MESSAGE",
            "type":"string",
            "readOnly":false
        }
    ] 
}
  • The important information in the response is the CHALLENGE.ID value

    This value will be used for authentication so it needs to be kept.

  • The challenge is returned in the response but its value is encrypted

  • The other information is in case of error, and an error message will be returned

The user will then receive an SMS with the customized message and the secret code. This code is a numeric string of 8 characters (for example, 45895919).

Authenticate the User with the Secret Code

Copy
POST https://[base-server-url]/SCIM/tenant/v2/Authenticator/.AT_TXOOB HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: application/x-www-form-urlencoded
 
grant_type=password&username=jsmith@company.com&password=70755246&context=correlationId:4039:false+txID:96003:false&channel=CH_EXTRAPP&authType=AT_TXOOB&noToken=1
  • In this request, the password that needs to be provided is the secret code received by SMS

  • There are two parameters supported for the "context" parameter and it is formatted as follows:

    context=PARAM1:VALUE1:isForAUDIT PARAM2:VALUE2:isForAudit

    (isForAudit can be true or false - if false, the authentication will not appear in the audit)

    Where the supported parameters are:

    • correlationId - only required if it is passed for DELIVER-CHALLENGE

      If present, will be checked against the value saved in challenge

    • txID - Required, the challenge ID generated during DELIVER-CHALLENGE
Note: noToken is a common parameter for OpenID token endpoint (on the HID Authentication Service). It is useful if your application just needs to validate the password without generating a session.
Copy

Response with noToken=1 (no session created):

{"access_token":"IA==","context":{"LEVEL_OF_ASSURANCE":"1"},"token_type":"Bearer"}
Copy

Response with noToken=0 (session created for the user):

{"access_token":"lGBtAgAAAW+zX1Qsa3whYOsf03QBQPO6zBvino+L","context":{"LEVEL_OF_ASSURANCE":"1"},"token_type":"Bearer","expires_in":360}