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 you want a user to authenticate via SMS, assign the AT_OOBSMS authentication policy and the DT_OOBSMS device type.

The user will then have an AT_OOBSMS authenticator.

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 is in the <internal ID>.<Authentication policy> format
    In the above example, the authenticator id is 230.AT_PASA which allows getting the internal ID of the user (the owner) to who 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 (valid from) and Expiry (valid to) date and time of the authenticator

  • Information about the owner of the authenticator

  • Statistics about the authenticator: 

    • consecutiveFailed - the number of consecutive failures of the authenticator

    • consecutiveSuccess - the number of consecutive success attempts

    • maximumNumberOfUsages - the total number of uses

    • totalFailed - the total number of failed attempts

    • totalSuccess - the total number of success attempts

    • Information about last failed and last successful authentication

  • Authentication policy from which the authenticator was created

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

Using the SCIM API to Manage Authenticators

Prerequisites:  

  • 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 with sufficient 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, perform a search request with the externalId (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 (in this example, 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" 
            <truncated output> 
        }
    ]
}

Topics in this section:

See also:

Managing Users, Groups and Roles

Enabling User Authentication

Searching with the SCIM API