Managing User or Client ID Authenticators

As introduced in Basic Concepts for Integration, an authenticator allows a user to be authenticated by the HID Authentication Service.

When an authentication policy is attached to a user, an authenticator with the corresponding type is created for the user.

A user can have as many authenticators as there are authentication policies in the HID Authentication Service. However, a user can only have one authenticator per authentication policy.

All of the non-password authenticators (that is, the device-based authenticators) store the secrets and configuration for the authentication secrets in a credential. For further information, see Managing Devices and Credentials.

A single authenticator can contain multiple credentials.

 

 

For example, if we want a user to authenticate via SMS, we will assign the authentication policy with code 'AT_OOBSMS and the device type 'DT_OOBSMS'.

The user will then have an authenticator of type 'AT_OOBSMS'.

About the Authenticator Object

An authenticator is described by a set of properties and information: 

Copy 
{
    "schemas":[
        "urn:hid:scim:api:idp:2.0:Authenticator"
    ],
    "id":"230.AT_PASA",
    "externalId":"sample-admin",
    "meta":{
        "resourceType":"Authenticator",
        "created":"2019-04-23T07:38:51Z",
        "location":"https://[base-server-url]/scim/{tenant}/v2/Authenticator/230.AT_PASA",
        "version":"1"
    },
    "status":{
        "status":"ENABLED",
        "active":true,
        "expiryDate":"2024-04-21T07:38:51Z",
        "startDate":"2019-04-23T07:38:51Z"
    },
    "owner":{
        "type":"User",
        "display":"sample-admin",
        "value":"230",
        "$ref":"https://[base-server-url]/scim/{tenant}/v2/Users/230"
    },
    "statistics":{
        "consecutiveFailed":"0",
        "consecutiveSuccess":"23192",
        "lastSuccessfulChannel":"CH_EXTRAPP",
        "lastSuccessfulDate":"2020-01-29T16:30:27Z",
        "lastUnsuccessfulChannel":"CH_EXTRAPP",
        "lastUnsuccessfulDate":"2019-12-11T13:36:09Z",
        "maximumNumberOfUsages":"23638",
        "totalFailed":"446",
        "totalSuccess":"23192"
    },
    "policy":{
        "display":"AT_PASA",
        "value":"AT_PASA",
        "$ref":"https://[base-server-url]/configuration/{tenant}/v2/Policy/Authenticator/AT_PASA"
    }
}

  • The ID of the authenticator has the format <internal ID>.<Authentication policy>
    In our example, we see the authenticator id is 230.AT_PASA and we can therefore get the internal ID of the user (the owner) to which it is assigned (230).

  • The externalId present in the authenticator refers to the external ID of the user to who it is assigned.

  • The meta attribute provides information about the creation date, the name of the resource, the direct URL of the resource and the version of the resource.

  • The status attribute describes the:

    • Status of the authenticator - possible values are 'ENABLED' or 'DISABLED'

    • Status is as described by the Boolean parameter 'active'

    • Start date and time (valid from) of the authenticator

    • Expiry date and time (valid to) of the authenticator

  • Information about the owner of the authenticator

  • Statistics about the authenticator: 

    • consecutiveFailed - the number of continuous failures of the authenticator

    • consecutiveSuccess - the number of continuous success attempts

    • maximumNumberOfUsages - the total number of usage

    • totalFailed - the total number of failed attempts

    • totalSuccess - the total number of success attempts

    • Information about last failed and last success authentication

  • Authentication policy from which the authenticator was created

When using a password authenticator, a password attribute is attached to the authenticator, more information about this attribute will be presented in the actions that can be performed on the authenticator.

Using SCIM to Manipulate Authenticators

What you need:

  • The URL of the HID Authentication Service platform (see HID Authentication service platforms around the world)

  • Your tenant ID (the identifier of your tenant, starting with the letter "t", for example, t987198273d986w9869) 

  • 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 in order to have enough permissions to perform the actions listed below.

    Using a bearer token from an non-privileged user / Client ID will result in 401 / 403 HTTP responses from the service APIs. For further information on getting a token, see Enabling User Authentication.

  • The internal ID of the user to who you want to assign the authenticator.

To get the internal ID of the user, you can user a search request with the externalId (see Internal IDs vs External IDs).

For example:

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" 
 (...) 
 }
 ]
}

Create an Authenticator for a Client ID

The creation of authentication method for a Client ID is using a specific flow and endpoint.

As described in Register a Client ID (Or a Client ID for M2M), the password or JWT authenticator for the client ID is created during the registration process.

Create a Password Authenticator for a User

Password is the basic authenticator, and there are multiple authentication policies that can be assigned to a user. For the list of the existing policies, see Authentication Policies in the HID Authentication Service.

You can also create your own password authentication policies.

For creating an authenticator from a password policy, the mandatory properties are described in the request example:

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_STDPWD" },
 "status":{
 "status":"ENABLED",
 "expiryDate":"2020-05-15T18:15:21+00:00",
 "startDate":"2015-05-15T18:15:21+00:00" },
 "owner":{
 "value":"52276" },
 "urn:hid:scim:api:idp:2.0:Password":{
 "username":"jsmith@company.com",
 "password":"Test123456?" }
}
Note:  

  • This is the moment where the HID Authentication Service checks and enforces the constraints on the password.

    If you provide a password that fails to verify the constraints of the selected Authentication policy, the service APIs will respond with a HTTP 400 bad request.

  • If you try to create an Authenticator for a user who already has an Authenticator of the same policy, the service APIs will respond with a HTTP 409 conflict error.

  • The password and username do not need to be UR- encoded here (indeed, it is contained in a JSON body), but JSON-escaped.

The response contains new attributes: 

  • The id attribute, generated by concatenating the user internal ID and the Authentication policy code

    In this example, 52276.AT_STDPWD

  • The statistics object

Copy 
{
    "schemas":[
        "urn:hid:scim:api:idp:2.0:Authenticator",
        "urn:hid:scim:api:idp:2.0:Password" ],
    "id":"52276.AT_STDPWD",
    "externalId":"jsmith@company.com",
    "meta":{
        "resourceType":"Authenticator",
        "created":"2015-05-15T18:15:21Z",
        "location":"https://[base-server-url]/scim/{tenant}/v2/Authenticator/52276.AT_STDPWD",
        "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_STDPWD",
        "value":"AT_STDPWD",
        "$ref":"https://[base-server-url]/configuration/{tenant}/v2/Policy/Authenticator/AT_STDPWD" },
    "urn:hid:scim:api:idp:2.0:Password":{
        "username":"jsmith@company.com" }
}

Create an Out-Of-Band Authenticator

To enable users to authenticate with an OTP / secure code sent out-of-band via SMS or email, the request to create the out-of-band authenticator is similar to the request for a password authenticator: 

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"
 }
 ]}
}

  • Define the policy attribute with the required out-of-band SMS or email policy

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

  • The activationCode  attribute is mandatory when using AT_OOBSMS or AT_OOBEML 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  policy (DT_OOBSMS for the authentication policy AT_OOBSMS, DT_OOBSMST for AT_OOBSMST, DT_OOBEML for AT_OOBEML and DT_OOBEMLT for AT_OOBEMLT) and the key word for registering the out-of-band authenticator. 

    When registering the authentication policy 'AT_TXOOB', an extra element needs to be 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"
     }
]}

Create a Device OTP Authenticator

The request is similar to the request used for creating the other authenticators.

The authentication policy to use for device OTP is AT_OTP.

The creation request is:

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_OTP" },
 "status":{
 "status":"ENABLED",
 "expiryDate":"2020-05-15T18:15:21+00:00",
 "startDate":"2015-05-15T18:15:21+00:00" },
 "owner":{
 "value":"52276" }
}

Create an HID Approve Authenticator

The authenticators related to HID Approve are automatically created by the HID Authentication Service when the user registers the app.

The following list of authenticator is created for the user after they successfully register the device type (DT_TDSV4): 

  • AT_PASA - authentication for Mobile push-based Logon Validation

  • AT_TDS - authentication for Mobile push-based Action Validation

  • AT_SMK - mobile application update

  • AT_EMPOTP - offline one-time password login for Mobile Logon Validation

Get All Authenticators for a User

We can get the list of authenticators for the user with internal ID 230 using:

Copy 
POST https://[base-server-url]/scim/{tenant}/v2/Authenticator/.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":"owner.value eq \"230\"",        
}

The response is a list of the authenticators for a user with all the details described in About the Authenticator Object.

An alternative method when the user's internal ID is unknown is to submit a user search request using externalId for example. This search request will return the user with a set of properties, including the list of authenticators assigned to the user, along with their internal ID.

You can send use the GET request for each authenticator assigned to the user (see Get Details About an Authenticator).

Get Details About an Authenticator

There are two ways to get details about a single authenticator.

Both methods require you to know the authenticator ID. The format of the ID is <user internal ID>.<authentication policy>. In this example, we will search for the details of the authenticator 230.AT_OTP.

First method is to use the search endpoint with the filter: 

Copy 
POST https://[base-server-url]/scim/{tenant}/v2/Authenticator/.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":"id eq \"230.AT_OTP\"",        
}

The second method is to use the GET endpoint:

Copy 
GET https://[base-server-url]/scim/{tenant}/v2/Authenticator/230.AT_OTP HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: "application/scim+json"

Actions on Authenticators

All of the authenticators support the update of their status (enabled or disabled).

Depending on the authentication type, some specific actions can be performed (for example, changing password is only possible on password-based authenticators).

To perform these actions, you need to know the ID of the authenticator.

Status Update

Can be performed on all authenticators.

Only the parameter status (enable or disabled) can be updated.

To disable the authenticator AT_STDPWD for the user 230, the request is:

Copy 
PUT https://[base-server-url]/scim/{tenant}/v2/Authenticator/230.AT_STDPWD HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: "application/scim+json"
{
    "schemas":[
        "urn:hid:scim:api:idp:2.0:Authenticator"
    ],
    "id":"230.AT_STDPWD",
    "status":{
        "status":"DISABLED",}
}

Password Update

Can only be performed on password-based authenticators.

For example, to update the password of the user with internal ID 230 and authenticator AT_STDPWD:

Copy 
PUT https://[base-server-url]/scim/{tenant}/v2/Authenticator/230.AT_STDPWD HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: "application/scim+json"
{
    "schemas":[
        "urn:hid:scim:api:idp:2.0:Authenticator",
        "urn:hid:scim:api:idp:2.0:Password"
    ],
    "id":"230.AT_STDPWD",
    "urn:hid:scim:api:idp:2.0:Password":{
        "username":"test21@test.com",
        "password":"MynewSecretPassword"
    }
}

The mandatory parameters that needs to be included in the request are: 

  • The username of the user (external ID)

  • The new password

  • The id of the authenticator

Get Challenge by User Code

Used for the authentication policy, AT_EMPOTP associated with HID Approve.

This action is the first step of the challenge-response flow:

Copy 
POST https://[base-server-url]/scim/{tenant}/v2/Authenticator/230.AT_OTP 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":"USER-CHALLENGE",
 "attributes":[
 {
 "name":"USER.EXTERNALID",
 "value":"test21@test.com" },
 ]
 }
}

The USER.EXTERNALID attribute is not mandatory but recommended to have extra verification of the owner of the authenticator.

The response from the HID Authentication Service contains the challenge that can be then used to authenticate the user. This flow is described in Authenticate user with challenge-response with OTP device.

Get Challenge by Device

Used for the authentication policy AT_EMPOTP associated with HID Approve.

This action is the first step of the challenge-response flow:

Copy 
POST https://[base-server-url]/scim/{tenant}/v2/Authenticator/230.AT_OTP 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":"DEVICE-CHALLENGE",
 "attributes":[
 {
 "name":"DEVICETYPE",
 "value":"DT_POCK_OA" },
    {
 "name":"DEVICE.EXTERNALID",
 "value":"165242134125142513451562"},
    {
 "name":"DEVICE.ID",
 "value":"1654462" }, 
 ]
 }
}

Not all attributes are mandatory. You can choose only 1 from the list: 

  • DEVICETYPE - the code of the device type

  • DEVICE.EXTERNALID - serial number of the device

  • DEVICE.ID - ID of the device

The response from the HID Authentication Service contains the challenge that can be then used to authenticate the user/device. This flow is described in Authenticate user with challenge-response with OTP device.

Reset Failure Count

After multiple failed authentication attempts, the authenticator becomes disabled.

Copy 
POST https://[base-server-url]/scim/{tenant}/v2/Authenticator/230.AT_OTP 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": "RESET"
    }
}

Send Challenge

This action is only used for transaction validation with an OOB SMS authentication using the authentication type AT_TXOOB.

Copy 
POST https://[base-server-url]/scim/{tenant}/Authenticator 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 purchase of 50 euros from the shop OnlineShopExample, please enter the code : {$secret}"
 },
 { 
 "name":"correlationid",
 "value":"1123"
 },
 { 
 "name":"DEVICETYPE",
 "value":"DT_TXOOB"
 },
 { 
 "name":"USER.EXTERNALID",
 "value":"jsmith@company.com"
 }]
 }
}

For more information about this flow, see Sending SMS to the user with the secret code.

Delete an Authenticator

Like the other resources, the deletion request is very similar.

To delete the authenticator with the ID 230.AT_OTP:

Copy 
DELETE https://[base-server-url]/scim/{tenant}/v2/Authenticator/230.AT_OTP HTTP/1.1 
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: "application/scim+json" 

See also:

Managing Users, Groups and Roles

Enabling User Authentication

Searching with the SCIM API