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:

A bearer token of a Client ID, obtained by authenticating against the HID Authentication Service OPENID API

To get such a token, see Client ID authentication with a password or Client ID authentication with JWT (PKI).
A created user
A phone number registered for the user (in the attributes)
The out-of-band SMS authenticator AT_OOBSMS created for the user (see Creating an Out-of-Band SMS Authentication for a User)
The activation code used for registering the AT_OOBSMS authenticator user (see Creating an Out-of-Band SMS Authentication for a User)

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:

A bearer token of a Client ID, obtained by authenticating against the HID Authentication Service OpenID API

To get such a token, see Client ID authentication with a password or Client ID authentication with JWT (PKI).
A created user (see Managing Users, Groups and Roles)
A phone number registered for the user, see Managing Users, Groups and Roles
The out-of-band SMS authenticator AT_TXOOB created for the user, see Creating an Out-of-Band SMS Authentication for a User

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}