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 Authentication Service APIs. To learn how to get a token, see Enabling User Authentication.
A created User. To learn how to create a user, see Managing Users, Groups and Roles.

In order 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@gmail.com. To know more about internal ID vs external ID, see Internal IDs vs External IDs.

POST https://AAAS_PLATFORM/scim/YOUR_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@gmail.com\"",
   "sortBy":"id",
   "sortOrder":"descending",
   "startIndex":0,
   "count":100
}

The response contains the internal ID, here 52276.

{
   "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@gmail.com"
  
         (...)    
  
      }
   ]
}

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

Date attributes follow the ISO 8601 format. Refer to Date formats in the SCIM API.

POST https://AAAS_PLATFORM/scim/YOUR_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"
          }
   ]}
}

Complete the policy attribute with the desired out-of-band SMS policy.
The owner attribute is pointing to the internal ID of the user.
The activationCode attribute is mandatory when using AT_OOBSMS policy. It can be an alphanumeric or numeric string. For the other policies, it can be set to false.
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:

"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 all set. See the next section to see how to authenticate the user against the Authentication Service.

The response contains new attributes:

The id attribute, that the Authentication Service generated by concatenating the user internal ID and the Authentication policy code. Here 52276.AT_OOBSMS.
The statistics object.
The activation code.

To learn more about Authenticators, see Managing a User or Client ID's Authenticators.

{
   "schemas":[
      "urn:hid:scim:api:idp:2.0:Authenticator",
   ],
   "id":"52276.AT_OOBEML",
   "externalId":"jsmith@gmail.com",
   "meta":{
      "resourceType":"Authenticator",
      "created":"2015-05-15T18:15:21Z",
      "location":"https://AAAS_PLATFORM/scim/YOUR_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@gmail.com",
      "value":"52276",
      "$ref":"https://AAAS_PLATFORM/scim/YOUR_TENANT/v2/Users/52276"
   },
   "statistics":{
      "consecutiveFailed":"0",
      "consecutiveSuccess":"0",
      "maximumNumberOfUsages":"0",
      "totalFailed":"0",
      "totalSuccess":"0"
   },
   "policy":{
      "display":"AT_OOBSMS",
      "value":"AT_OOBSMS",
      "$ref":"https://AAAS_PLATFORM/scim/YOUR_TENANT/v2/Policy/Authenticator/AT_OOBSMS"
   },
   "activationCode":"activationSecretCode"
}

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 Authentication Service OPENID API. To learn how 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, refer to the previous paragraph on this page.
The activation code used for registering the AT_OOBSMS authenticator, refer to the previous paragraph on this page.

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

POST https://AAAS_PLATFORM/idp/YOUR_TENANT/authn/token HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: application/x-www-form-urlencoded
 
grant_type=password&username=jsmith@gmail.com&password=activationSecretCode&channel=CH_EXTRAPP&authType=AT_OOBSMS&noToken=1

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

POST https://AAAS_PLATFORM/idp/YOUR_TENANT/authn/token HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: application/x-www-form-urlencoded
 
grant_type=password&username=jsmith@gmail.com&password=45895919&channel=CH_EXTRAPP&authType=AT_OOBSMS

In this request, the password that needs to be provided is the secret code received by SMS.
If the secret code is incorrect, the 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 Authentication Service misinterpreting the characters you passed and thus authenticators being disabled for too many wrong attempts.

The Response

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

{"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 Authentication Service OPENID API. To know how to get such a token, see Client ID authentication with a password or Client ID authentication with JWT (PKI).
A created user. To know how to create a 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, refer to the previous paragraph on this page.

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

POST https://AAAS_PLATFORM/idp/YOUR_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@gmail.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 the next paragraph).

The response from the Authentication Service is:

POST https://AAAS_PLATFORM/idp/YOUR_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 the next step so it needs to be kept.
The challenge is returned in the response but its value is encrypted.
The other information are in case of error, 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

POST https://AAAS_PLATFORM/idp/YOUR_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@gmail.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 2 parameters supported for the "context" parameter; it is formatted as follows:

context=PARAM1:VALUE1:isForAUDIT PARAM2:VALUE2:isForAudit (where isForAudit has value true or false : if false, the authentication will not appear in the audit)

where the parameters supported:
correlationId: only required if it is passed when do 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 Authentication service). Useful if your application just needs to validate the password without generating a session.

Response with noToken=1 (no session created):

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

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}