User Authentication with Out-of-Band Email

Creating an Out-of-Band Email Authenticator 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 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 out-of-band authentication with email, we need to create and assign an Authenticator to the user, by selecting a Device-based Authentication policy. 

The available policy is: 

  • AT_OOBEML: Out-of-band email policy designed to be used with SCIM API's only. This policy requires an activation code.

To know more about the details of this policy, 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. 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@company.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@company.com"
  
         (...)    
  
      }
   ]
}

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

  • Fill the policy attribute with the desired out-of-band email policy. 

  • The owner attribute is pointing to the internal ID of the user. 

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

  • The activationCode attribute is mandatory when using AT_OOBEML policy.  It can be an alphanumeric or numeric string.

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_OOBEML"
   },
   "owner":{
      "value":"52276"
   },
   "urn:hid:scim:api:idp:2.0:Action": {
      "action": "REGISTER-OOB",
      "attributes": [
          {
             "name": "OOB_DEVICETYPE_CODE",
             "value": "DT_OOBEML"
          }
   ]},
   "policy": {
   "value": "AT_OOBEML"
   },
      "activationCode":"activationSecretCode",
}

The user's authenticator is then ready. 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_OOBEML.

  • The statistics object.

  • The activation code.

To know more about the detail of 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@company.com",
   "meta":{
      "resourceType":"Authenticator",
      "created":"2015-05-15T18:15:21Z",
      "location":"https://AAAS_PLATFORM/scim/YOUR_TENANT/v2/Authenticator/52276.AT_OOBEML",
      "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://AAAS_PLATFORM/scim/YOUR_TENANT/v2/Users/52276"
   },
   "statistics":{
      "consecutiveFailed":"0",
      "consecutiveSuccess":"0",
      "maximumNumberOfUsages":"0",
      "totalFailed":"0",
      "totalSuccess":"0"
   },
   "policy":{
      "display":"AT_OOBEML",
      "value":"AT_OOBEML",
      "$ref":"https://AAAS_PLATFORM/scim/YOUR_TENANT/v2/Policy/Authenticator/AT_OOBEML"
   },
   "activationCode":"activationSecretCode"
}

Authenticating a User with Out-of-Band Email using AT_OOBEML

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. 

  • An email address registered for the user. 

  • The out-of-band email authenticator AT_OOBEML created for the user, refer to the previous paragraph on this page. 

  • The activation code used for registering the AT_OOBEML authenticator, refer to the previous paragraph on this page.

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

Both steps use the authn/token endpoint, where some of the parameters in the requests are different.

Send en Email 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@company.com&password=activationSecretCode&channel=CH_EXTRAPP&
authType=AT_OOBEML&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 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 user will then receive an email from no-reply.authentication-service@hidglobal.com 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@company.com&password=45895919&channel=CH_EXTRAPP&authType=AT_OOBEML

  • In this request, the password that needs to be provided is the secret code received by email.

  • 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 understand what to do with the response, see Making the most of OPENID Tokens.