Managing Users, Groups and Roles

About the User and Group Structure

The HID Authentication Service has a pre-defined structure of user groups as follows:

  • UG_ROOT - the 'root' group for all your end users

  • UG_CLIENTID - all your Client IDs

  • UG_ORGADMIN - the administrators of your tenant on the HID Authentication Service

The HID Authentication Service uses this structure to perform permission checks (for example, Organization Administrators have permissions on the other groups, but end users do not).

It also allows you to filter 'end users' from Client IDs and Administrators.

A Client ID is a User... and more

When you create a Client ID in the HID Authentication Service with the OpenID register endpoint, a user is created under the UG_CLIENTID group, and a role must be assigned to it (RL_OPENIDCLIENT or RL_CLIENTIDM2M).

In the background, the HID Authentication Service registers a 'configuration' so that this user is considered to be a Client ID. This configuration contains all the parameters you specified when calling the register endpoint.

About Custom Groups

The HID Authentication Service has been designed to have a flat structure under UG_ROOT, and it is recommended segregating your users using Roles instead of Groups.

While the HID Authentication Service APIs offer the possibility to manage groups under UG_ROOT, it is not recommended segregating users this way.

Available Roles in the HID Authentication Service

Your tenant in the HID Authentication Service includes a set of pre-defined roles allowing to start using and managing your tenant immediately.

These roles are used by the HID Authentication Service to enforce permission checks on your tenant and are therefore immutable.

Organization Administrators (RL_ORGADMIN)

The Organization Administrator role is a privileged role on your tenant. Therefore, it a role for which it is recommended configuring users with strong multi-factor authentication such as push-based authentication with HID Approve.

An Organization Administrator is allowed to fully manage your tenant, including other administrators and Client IDs.

Permission Target

Full permissions on Users and Devices

UG_ROOT

Full permissions on Groups

UG_ROOT

Full permissions on Client IDs

UG_CLIENTID

Full permissions on Organization Administrators and their devices

UG_ORGADMIN

Client IDs (RL_CLIENTID)

The Client ID role is provided only with read permissions, allowing to authenticate users with OpenID. To be compliant with the least permission principle, the Client ID has no privileges at all.

Permission Target

Read and Authentication permissions on Users

UG_ROOT

Read and Authentication permissions on Organization Administrators

UG_ORGADMIN

OpenID Client (RL_OPENIDCLIENT)

The OpenID Client role is provided only to authenticate users with OpenID. To be compliant with the least permission principle, the OpenID client has no privileges at all.

It supports only user authentication, push notification and OpenID consent.

M2M Client IDs (RL_CLIENTIDM2M)

The Client ID for M2M (Machine To Machine) role is one of most powerful roles on your tenant. Therefore, it is a role for which we recommend to have Client IDs configured with strong PKI (certificate-based) authentication.

A Client ID for M2M is allowed to fully manage your tenant, including other administrators and Client IDs.

Note: While there are drivers for implementing M2M (Machine To Machine) architectures, this comes with security concerns. Providing a machine / application (instead of a human being) with a powerful role can be a security backdoor if that machine is ever compromised. Client IDs for M2M integrations should only be used where no other solution is reasonably possible. In such situations, the principle of least privilege should be respected.
Permission Target

Full permissions on Users and Devices

UG_ROOT

Full permissions on Groups

UG_ROOT

Full permissions on Client IDs

UG_CLIENTID

Full permissions on Organization Administrators and their devices

UG_ORGADMIN

Using the APIs to Manage Users, Groups and Roles

Prerequisites: To manage users, groups and roles with the APIs, 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 an privileged user to have sufficient permissions to perform the actions in the following sections.

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

Register a Client ID (or a Client ID for M2M)

The register endpoint is used to create Client IDs as follows:

  • Register the Client ID in the UG_CLIENTID group

  • Fetch the internal ID of the Client ID

  • Use the internal ID to assign the role RL_OPENIDCLIENT to the newly created Client ID

Important: About Client ID Registration

Each Client ID needs to be registered under the UG_CLIENTID group and assigned the RL_OPENIDCLIENT role.

The group allows the HID Authentication Service to filter Client IDs and the role is the only way for the Client ID to have sufficient permissions to perform end user authentication. Failing to assign the role to a Client ID will result in HTTP 401 or 403 errors upon end user authentication.

Client IDs with Passwords

To create a Client ID with a password, you need to call the register endpoint with the token_endpoint_auth_method set to client_secret_basic.

The HID Authentication Service will then register the Client ID and generate a password for you.

The following table provides an overview of the supported parameters:

Parameter Description

hid_client_group

Instructs the HID Authentication Service to create the Client ID under the UG_CLIENTID group

client_name

A free field in which you can name your Client ID

The name must be unique. and will NOT be the identifier of the Client ID, which will be generated by the HID Authentication Service

hid_client_channel

Indicates through which default channel the Client ID needs to authenticate

This parameter can be overwritten upon authentication

If you do not know what to indicate here, keep CH_EXTRAPP

hid_client_pwd_policy and hid_client_pki_policy

The default authentication policies for Client IDs

They can be set to AT_SYSLOG and AT_JWT

hid_client_pki_policy

The authentication policy for Client IDs with mTLS-based authentication

It can be set to AT_EMPPKI

hid_user_channel

Indicates through which default channel the Client ID needs to authenticate end users

This parameter can be overwritten upon authentication

If you do not know what to indicate here, keep CH_EXTRAPP

hid_user_authn_policy

The default authentication policy code to be used for end user (indirect user) authentication

For the list of available policies you can use, see Authentication Policies in the HID Authentication Service.

For example, if you want to use a simple password policy, set AT_STDPWD

hid_ciba_callback_format_plain

Defines the format for the CIBA callback response (if required) and the value can be set to either True or False

To sign the id_token, set the value to False

For further information about the CIBA callback response for signed and plain id_tokens, see Send the Push Notification

id_token_encrypted_response_alg

Defines the encryption algorithm for the CIBA callback response (if required)

The jwks (JSON Web Key Set) attribute must also be provided with the certificate as a key object to encrypt the signed id_tokens

The currently supported algorithm is RSA-OAEP-256

Note:

  • You can specify the value for client_id attribute if you do not want the HID Authentication Service to generate it. However, the value you define must be unique.

  • It is not possible to define a password as an attribute for the Client ID as it is generated by the HID Authentication Service.

    However, you can change the password afterward using the client_secret parameter.

  • You can optionally encrypt the signed id_token but you cannot encrypt the plain id_token.

The first step is to register the Client ID:

Copy

Sample request to register a client ID with a signed and encrypted id_token

POST https://[base-server-url]/{tenant}/authn/register HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: "application/json"

{
    "redirect_uris":[
        "https://client.example.org",
        "https://client2.example.org" ],
    "client_name":"newclientid",
    "token_endpoint_auth_method":"client_secret_basic",
    "hid_client_channel":"CH_EXTRAPP",
    "hid_client_pwd_policy":"AT_SYSLOG",
    "hid_client_pki_policy":"AT_JWT",
    "hid_user_channel":"CH_EXTRAPP",
    "hid_user_authn_policy":"AT_STDPWD",
    "hid_client_group":"UG_CLIENTID",
    "hid_ciba_callback_format_plain": "false",
    "id_token_encrypted_response_alg": "RSA-OAEP-256",
    "jwks": {
        "keys": [{
            "use": "enc",
            "kty": "RSA",
            "x5t#S256": "",
            "e": "AQAB",
            "kid": "MyClientId",
            "x5c": "MIIGNTDDBQ2gAwIUdGU11QTTUtTMzQ4LUNBMB(…......)7dlizqis0Fq0pLoWcEbLfiItWGw6AN8cA17HVpE1w"
        }]
    "hid_client_scopes":"{\"scopes\":[\"openid\",\"profile\"]}"
}
Note: The certificate is passed to the HID Authentication Service with the following attributes that need to be computed from your certificate:

  • use - encryption (enc)

  • kid - Key Id (CN)

  • kty - key type

  • e - public key exponent

  • x5c - full certificate chain, PEM format without the first and last line (BEGIN CERTIFICATE and END CERTIFICATE)

  • x5t#S256 - base64url-encoded SHA-256 thumbprint of the certificate

An example result:

"jwks": { "keys": [ { "use": "enc", "kty": "RSA", "x5t#S256": "ZFgddljlwertdjKzsDRla2chRcshc4NrWkYFrvoio", "e": "AQAB", "kid": "MyClientId", "x5c": "MIIGNTDDBQ2gAwIUdGU11QTTUtTMzQ4LUNBMB(…......)7dlizqis0Fq0pLoWcEbLfiItWGw6AN8cA17HVpE1w" }

The response mainly confirms the parameters that were indicated in the registration request, specifically:

  • client_id is the generated user ID (or externalId) for your Client ID and the most important attribute

    It is used when authenticating your application with the HID Authentication Service

  • client_secret is the generated password for your Client ID

  • grant_types indicates the OpenID grant types that can be used with the Client ID

    For further information about OpenID grant types and flows, see OpenID Authentication Flows

Copy 
{
    "grant_types":[
        "client_credentials",
        "password",
        "authorization_code"
    ],
    "hid_client_group":"UG_CLIENTID",
    "registration_client_uri":"https:\/\/[base-server-url]\/tenant\/authn\/register\/655817402088574941876708488070484658763453311419",
    "redirect_uris":[ 
        "https:\/\/client.example.org",
        "https:\/\/client2.example.org",
        "http:\/\/localhost:8080\/samplesAuthorizationCode.html"
    ],
    "hid_client_channel":"CH_EXTRAPP",
    "token_endpoint_auth_method":"client_secret_basic",
    "client_id":"655817402088574941876708488070484658763453311419",
    "hid_client_pwd_policy":"AT_SYSLOG",
    "hid_client_consentprompt":"false",
    "hid_client_pki_policy":"AT_JWT",
    "hid_client_scopes":"{\"scopes\":[\"openid\",\"profile\"]}",
    "hid_user_channel":"CH_EXTRAPP",
    "client_secret_expires_at":1725363585,
    "hid_user_authn_policy":"AT_STDPWD",
    "client_id_issued_at":1567683586,
    "client_secret":"OpenID1567683585093",
    "tls_client_certificate_bound_access_tokens":false,
    "hid_ciba_callback_format_plain": "false", 
    "id_token_encrypted_response_alg": "RSA-OAEP-256", 
    "jwks": {
        "keys": [ { 
            "use": "enc",
            "kty": "RSA",
            "x5t#S256": "ZFgddljljlaldjKzsHk1rja2chRcshc4NrWkYFrvoio",
            "e": "AQAB",
            "kid": "MyClientId",
            "x5c": "MIIGNTCCBR2gAwIUdGU01QUUtTMzQ4LUNBMB(…......)7dlizqis0Fq0kLoWbEbLfiItUGw6AN8cA17HVpE1w"
        }]
    }
    "client_name":"newclientid"
}

The second step is to assign the RL_OPENIDCLIENT role to the Client ID. To do so, get the internal ID of the Client ID allowing to call the SCIM API endpoint to assign a role.

Copy

Sample request to search for a user using the externalId from the above response in the filter parameter:

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 \"655817402088574941876708488070484658763453311419\"",
    "sortBy":"id",
    "sortOrder":"descending",
    "startIndex":0,
    "count":100
}

The response is a multi-resource array where the externalId as the filter guarantees that only one result is returned.

For further information, see Internal IDs vs External IDs.

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":"11053",
            "externalId":"655817402088574941876708488070484658763453311419"         (...) 
        }
    ]
}

The most important attribute returned is:

  • id which is the internal ID of the Client ID (in this example, 11053)

Finally, assign the role where the Client ID's internal ID is present as a path parameter in the URL.

Copy 
POST https://[base-server-url]/scim/tenant/v2/Users/11053 HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: "application/scim+json"

{
    "schemas":[
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:hid:scim:api:idp:2.0:Attribute",
        "urn:hid:scim:api:idp:2.0:UserDevice" ],
    "externalId":"655817402088574941876708488070484658763453311419",
    "roles":[
         { "value":"RL_OPENIDCLIENT" }
     ],
     "groups":[
         { "value":"UG_CLIENTID" }
    ]
}
Note: About groups, roles and the Users endpoint

  • The roles and groups parameters always need to be passed to the Users endpoint

    If you do not pass them, an error will be returned by the HID Authentication Service

  • More importantly, if you pass an empty list of roles, the HID Authentication Service will unassign the roles which might already be assigned to the user

Client IDs with PKI Certificates

For PKI authentication, you need a public CA-signed certificate of any format (CER, DER, CRT or PEM).

This public certificate is sent to the HID Authentication Service that will store it. You can also send the JWKS encryption certificate along with this public certificate to create an encrypted id_token.

Each time the client ID needs to authenticate, the HID Authentication Service uses this certificate (public key) to verify a challenge.

Note: The current recommendation is to generate a certificate from a minimum of a 2048-bit long RSA private key.
Copy

To generate such a certificate:

openssl genrsa -out myClientID.private.key 2048
openssl req -new -key myClientID.private.key -out myClientID.csr

Then send the CSR to your CA for them to provide you with a signed certificate (CRT, DER, PEM or CER file).

The method to create a Client ID with PKI is similar to Client IDs with passwords, but the token_endpoint_auth_method attribute must be set to private_key_jwt.

In addition, the jwks attribute must be provided with the certificate as a key object. This key object must be computed out of your certificate.

Important: As with creating a Client ID with a password, do not forget to assign the RL_OPENIDCLIENT role to your newly created Client ID.
Note: The certificate is passed to the HID Authentication Service with the following attributes that need to be computed out of your certificate:

  • kid - the Key Id (CN)

  • kty - the key type

  • n - the public key modulo

  • e - the public key exponent

  • x5c - the full certificate chain, PEM format without the first and last line (BEGIN CERTIFICATE and END CERTIFICATE)

  • x5t#S256 - the base64url-encoded SHA-256 thumbprint of the certificate.

The following is sample code to illustrate how to compute the values out of a certificate. The following operations should be performed in a secure environment (for example, server-side), and avoid relying on client browsers:

  • Convert the certificate file to the PEM format:

    var certificatePEM = convertToPEM( certificate );

  • Convert the certificate to a DER binary X509 format:

    var certificateBinaryDER = convertToDERBinary( certificate );

  • Modify the PEM to compute the x5c:

    certificatePEM.removeNewLines();

    certificatePEM.remove( "-----BEGIN CERTIFICATE-----" );

    certificatePEM.remove( "-----END CERTIFICATE-----" );

  • Read the following from the certificate:

    kid = certificate.CN; kty = certificate.keyType; n = certificate.key.modulo; e = certificate.key.exponent;

  • Read the x5c and thumbprint:

    x5c = certificatePEM;

    The SHA256 thumbprint is computed out of the DER binary data:

    x5t#256 = base64URLEncode( hashSHA256( certificateBinaryDER ) );

Copy

Sample result

"jwks":{
    "keys":[
        {
        "kid":"myClientID",
        "kty":"RSA",
        "n":"tUKZxLQO720MBomWtfLvsn_b7k1-1e65ftd9sGqw5y_D_fu8IPtYrdJ2VJZOyDr4ObavKhT473Dq4UM5zPMRFgz5hTrwOkX9rVTSBDNhwMG9sywIFDMPo95qiQBYjjDHPq5s-mg3PveZduRAlm709PnzN_ybVmE8Nwfpf8Rbuv8eatb5BiBb5vOJWVheYtka_gvgvRj0Uq5b5uStI3cSthApziMHCBgzZKPeX6xZgwja3u4hp3SXGJ6MSvxFczC07ySY0yJ87-mC1VKGsG7hx9XcC01K4Ak9X47NAAUla8ZSIRsz-NnYApqQxj2A1SoZ9Q_Wq0gwtc5BKgTCRZoniw",
        "e":"AQAB",
        "x5c":[
            "MIIDQTCCAikCCQDBaGyjlba/8TANBgkqhkiG9w0BAQsFADBeMQswCQYDVQQGEwJQTDEPMA0GA1UECAwGUE9MQU5EMQ8wDQYDVQQHDAZLUkFLT1cxDDAKBgNVBAoMA0hJRDENMAsGA1UECwwEQUFBUzEQMA4GA1UEAwwHUk9PVCBDQTAeFw0xOTA5MTMxMTI1MjBaFw0yMTAxMjUxMTI1MjBaMGcxCzAJBgNVBAYTAlVTMQ4wDAYDVQQIDAVUZXhhczEPMA0GA1UEBwwGQXVzdGluMRMwEQYDVQQKDApISUQgR2xvYmFsMQ0wCwYDVQQLDARBYWFTMRMwEQYDVQQDDApteUNsaWVudElEMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAtUKZxLQO720MBomWtfLvsn/b7k1+1e65ftd9sGqw5y/D/fu8IPtYrdJ2VJZOyDr4ObavKhT473Dq4UM5zPMRFgz5hTrwOkX9rVTSBDNhwMG9sywIFDMPo95qiQBYjjDHPq5s+mg3PveZduRAlm709PnzN/ybVmE8Nwfpf8Rbuv8eatb5BiBb5vOJWVheYtka/gvgvRj0Uq5b5uStI3cSthApziMHCBgzZKPeX6xZgwja3u4hp3SXGJ6MSvxFczC07ySY0yJ87+mC1VKGsG7hx9XcC01K4Ak9X47NAAUla8ZSIRsz+NnYApqQxj2A1SoZ9Q/Wq0gwtc5BKgTCRZoniwIDAQABMA0GCSqGSIb3DQEBCwUAA4IBAQBQ/k13HX8QOXly0B6wTlzlaWNv6fRqNK4FTTIUSjnq/t2tYhcrkru55buY1ICAZIvOUVkUMooKVclrmxV3brpxzKxfoYxqRQqDJI+AxDEUzGBaDS1HFRFdww9yVBvUYbJYpFKyklqv6YHPjwc3/suwtc18VcbZ80LiilNNXYKX7UTgfzwR6FWOFpzW44awYBI0PeDldob8KOst1sASTKIi9wCV+VrY1TchI0ZqTheHY6SbNjGxLOgOZYTO8k69zk0yR4LYsWpwYb8XWS0hIKT92vnn8NVQMVdYGYrJOHn/ckDi5TQaOx5oiXFFbaGeozOleWDLN8XTeq/vd4oM6Q+T" ],
        "x5t#S256":"SgK6Nb36iJo_qSVaY3-mHnNXumYTTAYG1iJeVU0tCDY" }
    ]
}
Note: If the hid_ciba_callback_format_plain value is set to False, you can get the signed id_token, which can be optionally encrypted using the JWKS certificate as illustrated below.
Copy

Sample request for Client IDs with PKI certificate and signed and encrypted id_token

POST https://[base-server-url]/{tenant}/authn/register HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: "application/json"{
   "redirect_uris":[
      "https://client.example.org",
      "https://client2.example.org"   ],
   "client_name":"myClientId",
   "token_endpoint_auth_method":"private_key_jwt",
   "hid_client_channel":"CH_EXTRAPP",
   "hid_client_pwd_policy":"AT_SYSLOG",
   "hid_client_pki_policy":"AT_JWT",
   "hid_user_channel":"CH_EXTRAPP",
   "hid_user_authn_policy":"AT_STDPWD",
   "hid_sessiontransfer_type":"NUM001",
   "hid_client_group":"UG_CLIENTID",
   "hid_ciba_callback_format_plain": "false",
   "id_token_encrypted_response_alg": "RSA-OAEP-256",
   "jwks":{
      "keys":[
         {
            "kid":"myClientID",
            "kty":"RSA",
            "n":"tUKZxLQO720MBomWtfLvsn_b7k1-1e65ftd9sGqw5y_D_fu8IPtYrdJ2VJZOyDr4ObavKhT473Dq4UM5zPMRFgz5hTrwOkX9rVTSBDNhwMG9sywIFDMPo95qiQBYjjDHPq5s-mg3PveZduRAlm709PnzN_ybVmE8Nwfpf8Rbuv8eatb5BiBb5vOJWVheYtka_gvgvRj0Uq5b5uStI3cSthApziMHCBgzZKPeX6xZgwja3u4hp3SXGJ6MSvxFczC07ySY0yJ87-mC1VKGsG7hx9XcC01K4Ak9X47NAAUla8ZSIRsz-NnYApqQxj2A1SoZ9Q_Wq0gwtc5BKgTCRZoniw",
            "e":"AQAB",
            "x5c":[
          "MIIDQTCCAikCCQDBaGyjlba/8TANBgkqhkiG9w0BAQsFADBeMQswCQYDVQQGEwJQTDEPMA0GA1UECAwGUE9MQU5EMQ8wDQYDVQQHDAZLUkFLT1cxDDAKBgNVBAoMA0hJRDENMAsGA1UECwwEQUFBUzEQMA4GA1UEAwwHUk9PVCBDQTAeFw0xOTA5MTMxMTI1MjBaFw0yMTAxMjUxMTI1MjBaMGcxCzAJBgNVBAYTAlVTMQ4wDAYDVQQIDAVUZXhhczEPMA0GA1UEBwwGQXVzdGluMRMwEQYDVQQKDApISUQgR2xvYmFsMQ0wCwYDVQQLDARBYWFTMRMwEQYDVQQDDApteUNsaWVudElEMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAtUKZxLQO720MBomWtfLvsn/b7k1+1e65ftd9sGqw5y/D/fu8IPtYrdJ2VJZOyDr4ObavKhT473Dq4UM5zPMRFgz5hTrwOkX9rVTSBDNhwMG9sywIFDMPo95qiQBYjjDHPq5s+mg3PveZduRAlm709PnzN/ybVmE8Nwfpf8Rbuv8eatb5BiBb5vOJWVheYtka/gvgvRj0Uq5b5uStI3cSthApziMHCBgzZKPeX6xZgwja3u4hp3SXGJ6MSvxFczC07ySY0yJ87+mC1VKGsG7hx9XcC01K4Ak9X47NAAUla8ZSIRsz+NnYApqQxj2A1SoZ9Q/Wq0gwtc5BKgTCRZoniwIDAQABMA0GCSqGSIb3DQEBCwUAA4IBAQBQ/k13HX8QOXly0B6wTlzlaWNv6fRqNK4FTTIUSjnq/t2tYhcrkru55buY1ICAZIvOUVkUMooKVclrmxV3brpxzKxfoYxqRQqDJI+AxDEUzGBaDS1HFRFdww9yVBvUYbJYpFKyklqv6YHPjwc3/suwtc18VcbZ80LiilNNXYKX7UTgfzwR6FWOFpzW44awYBI0PeDldob8KOst1sASTKIi9wCV+VrY1TchI0ZqTheHY6SbNjGxLOgOZYTO8k69zk0yR4LYsWpwYb8XWS0hIKT92vnn8NVQMVdYGYrJOHn/ckDi5TQaOx5oiXFFbaGeozOleWDLN8XTeq/vd4oM6Q+T"            ],
            "x5t#S256":"SgK6Nb36iJo_qSVaY3-mHnNXumYTTAYG1iJeVU0tCDY"         }
        {
          "use": "enc",
          "kty": "RSA",
          "x5t#S256": "",
          "e": "AQAB",
          "kid": "MyClientId",
          "x5c": "MIIGNTDDBQ2gAwIUdGU11QTTUtTMzQ4LUNBMB(…......)7dlizqis0Fq0pLoWcEbLfiItWGw6AN8cA17HVpE1w"
        }
       ]
   }
}

Client IDs for M2M

To create a Client ID for M2M, follow the same procedure as creating a Client ID, but assign the RL_CLIENTIDM2M role instead of RL_OPENIDCLIENT.

Create an Organization Administrator

An Organization Administrator is a special type of user and must be created in the UG_ORGADMIN group and assigned the RL_ORGADMIN role.

In this example, the Organization Administrator is created with only a few attributes (email and Name/Surname). For the full list of possible attributes, see create an end user.

Once the Organization Administrator is created, you need to assign them an authenticator allowing to authenticate with the HID Authentication Service (see Enabling User Authentication).

Copy 
POST  https://[base-server-url]/scim/{tenant}/v2/Users HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: "application/scim+json"{
    "schemas":[
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:hid:scim:api:idp:2.0:Attribute",
        "urn:hid:scim:api:idp:2.0:UserDevice"   ],
    "externalId":"jsmith@company.com",
    "name":{
        "familyName":"Smith",
        "givenName":"John"   },
    "emails":[
        {
            "value":"jsmith@company.com",
            "type":"work"      }
     ],
     "roles":[
        {
            "value":"RL_ORGADMIN"      }
    ],
    "groups":[
        {
            "value":"UG_ORGADMIN"      }
    ]
}

The response contains the internal ID of the newly created Organization Administrator:

Copy 
{
    "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":"49976",
    "externalId":"jsmith@company.com",
    (truncated output)
}

Create an End User

End users should be created in the UG_ROOT group and they do not have any specific role.

An end user can be created in the following ways:

Note: About External ID and End-User Logins

By default, we use the email as an externalId for an end user. The externalId will be what the end user enters into the login field when connecting to your application. An email address is an easy, commonly used way to identify an end user.

However, you are free to use a different piece of data as an externalId, such as your own user identifiers or pseudonyms.

The only constraint is that the HID Authentication Service will enforce the externalId to be unique within your tenant.

For further information, see Internal IDs vs External IDs.

A user can be set up with the following standard attributes:

  • externalId - external ID of the user, it is used to identify the user externally for authentication

  • groups (array of objects)

    • value, the group code (UG_ROOT ...)

  • roles (array of objects)

    • value, the role code (RL_ORGADMIN...)

  • urn:hid:scim:api:idp:2.0:UserAuthenticator (array of objects)

    The user's available authenticators

    To know more about authenticators and how to enable authentication on users and Client IDs, see Enabling User Authentication.

  • urn:hid:scim:api:idp:2.0:UserDevice (array of Objects)

    The user's available devices

    To know more about devices and how to set up device based authentication factors, see Managing Devices and Credentials and Enabling User Authentication.

Note:
  • It is not possible to set the internal ID (id). The HID Authentication Service will generate it.

  • Note that even though the groups attribute is an array, only one group is supported per user.

Apart from standard attributes, each user can be assigned extra attributes with the parameter urn:hid:scim:api:idp:2.0:UserAttribute. Here is a full list of attributes that can be used:

Attribute Name Description

DOB

Date of Birth

ATR_EMAIL

E-Mail Address

ADDRESS1

Address Line 1

ATR_MOBILE

Mobile Phone Number

ADDRESS2

Address Line 2

LANGUAGE

language

ADDRESS3

Address Line 3

ATT_CNY_ID

Country ID

ADDRESS4

Address Line 4

COUNTY

county

CITY

City

STATE

state

POSTCODE

Post code

PHONE

phone

FIRSTNAME

First Name

CMPNY_NAME

Company Name

LASTNAME

Last Name

TITLE

Title

MIDDLENAME

Middle Name

You can also add your desired attributes using the Custom Attribute Type endpoints.

The below request shows the Custom Attribute Type:

Copy 
POST  https://[base-server-url]/configuration/{tenant}/v2/Users/AttributeType HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: "application/scim+json"{
  "id": "TEST10",
  "name": "test 10 name",
  "notes": "test 10 notes"
}

The response contains the newly created Attribute Type:

Copy 
{
  "schemas": [
    "urn:urn:hid:scim:api:idp:2.0:userattribute:Type"
  ],
  "id": "TEST10",
  "meta": {
    "resourceType": "UserAttributeType",
    "location": "https://[base-server-url]/configuration/tenant/v2/User/AttributeType/TEST10",
    "version": 1
  },
  "name": "test 10 name",
  "notes": "test 10 notes"
}

The Custom Attribute Type also supports the following endpoints, see SCIM API Reference:

  • Create User Attribute
  • Retrieve all User Attribute
  • Retrieve a User Attribute
  • Update User Attribute
  • Delete a Known User Attribute
Note:

Upon User creation, the extra attributes FIRSTNAME, LASTNAME, TITLE, ATR_EMAIL and PHONE are copied into the following immutable fields. Those fields are present in the User Detail response when searching or getting the detail of a user.

  • name (object):

    familyName and givenName

  • title (M., Ms., Dr. ...)

  • emails (array of objects):

    value and type (work, personal ...)

  • phoneNumbers (array of objects):

    value

Encrypt User Attribute Type

You can encrypt a UserAttributeType (for example, TITLE or FIRSTNAME) to minimize the exposure of Personally Identifiable Information (PII).

The value of the encrypted parameter must be in Boolean - true or false.

Copy

Sample request to update a user attribute type

PUT /User/AttributeType/CITY
{
    "encrypted": true
}
Copy

Response

{
   "schemas": ["urn:hid:scim:api:idp:2.0:userattribute:Type"],
   "id": "CITY",
   "meta":    {
      "resourceType": "UserAttributeType",
      "location": "https://[base-server-url]/configuration/{tenant}/v2/User/AttributeType/CITY",
      "version": "1"
   },
   "name": "City",
   "encrypted": true
}
Switch Encryption of User Attribute Type

If necessary, you can change the non-encrypted user attribute type to encrypted and vice versa. Use value "true" for encrypting and "false" for non-encrypting.

Important: You cannot use an encrypted user attribute as a criterion for search user (for example, if attribute type FIRSTNAME is encrypted, a search user with criteria name.givenName = foo will return 0 result even if a user has this givenName).

Once the end user is created, you need to assign an authenticator to them in order to allow them to authenticate with the HID Authentication Service. To know how to assign an authenticator, see Enabling User Authentication.

Create a Single User

To create a single user, you can use Create User endpoint.

The request to create a single user is shown below:

Copy 
POST  https://[base-server-url]/scim/{tenant}/v2/Users HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: "application/scim+json"{
   "schemas":[
      "urn:ietf:params:scim:schemas:core:2.0:User",
      "urn:hid:scim:api:idp:2.0:Attribute",
      "urn:hid:scim:api:idp:2.0:UserDevice"   ],
   "externalId":"rdavis@company.com",
   "name":{
      "familyName":"Davis",
      "givenName":"Richard"   },
   "emails":[
      {
         "value":"rdavis@company.com",
         "type":"work"      }
   ],
   "groups":[
      {
         "value":"UG_ROOT"      }
   ],
   "urn:hid:scim:api:idp:2.0:UserAttribute":{
      "attributes":[
         {
            "name":"TITLE",
            "type":"string",
            "value":"M."         },
         {
            "name":"ATR_MOBILE",
            "type":"string",
            "value":"0044 567 456 387"         }
      ]
   },
   "meta":{
      "resourceType":"User"   }
}
Copy

The response contains the internal ID of the newly created end user:

{
   "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":"49976",
   "externalId":"rdavis@company.com",
   
    (...)
}

Create Multiple Users

To create multiple users, you can use the Bulk Import endpoint.

Important:
  • Maximum allowable payload size to create multiple user is 40 MB.
  • It is not possible to re-submit an import batch with new or updated information. Make sure you set all the information you want for your users. If you missed out any information, the only solution is to call updateUser on each user you wish to modify.

The request to create multiple users is shown below, user information must be in Json format:

Copy 
POST  https://[base-server-url]/scim/{tenant}/v2/Users/.import HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: "application/scim+json"{
{
    "users": [{
            "emails": [{
                    "value": "email100000@company.com"
                }
            ],
            "name": {
                "familyName": "last100000",
                "givenName": "first100000"
            },
            "externalId": "bb0_100000"
        }, {
            "emails": [{
                    "value": "email100001@company.com"
                }
            ],
            "name": {
                "familyName": "last100001",
                "givenName": "first100001"
            },
            "externalId": "bb0_100001"
        }
    ],
    "group": {
        "value": "USG_FTEMP"
    }
}
Copy

The response contains newly created users and CorrelationId:

{
    "schemas": ["urn:hid:scim:api:idp:2.0:user:ImportResponse"],
    "meta": {
        "resourceType": "UserImportResponse",
        "location": "https://[base-server-url]/scim/{tenant}/v2/Users/.import/1P5FOESDK44J6Q0QAHK2",
        "version": "1"
    },
    "correlationId": "1P5FOESDK44J6Q0QAHK2"
}
Important:
  • A correlationId is returned for each successful batch submission. It can be used in the Get Import Status endpoint or to look for events in the auditlog.
  • If an authenticator policy of type login is specified in authenticatorPolicy.value, it will create an authenticator with a random password for all users in the bulk import. This random password must be changed during first login. To change password, see SCIM API Reference.

Get Import Status

To know the status of an import, you can use the Get Import Status endpoint along with the CorrelationId ({uid}) (see Managing the Correlation ID).

The request to retrieve the status of import is shown below:

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

The response may contains the below information:

  • importSize - the number of users in the import request

  • status - "importing" or "done"

  • nbProcessed - the number of users that has been processed so far

  • nbFailed - the number of users that have not been imported because of a failure

  • nbAlreadyExisted - the number of users that have not been imported because they already exist

  • nbImported - the number of users that were successfully imported

Copy 
{
   "schemas": ["urn:hid:scim:api:idp:2.0:user:ImportResponse"],
   "correlationId": "1P5FOESDK44J6Q0QAHK2",
   "status": "done",
   "importSize": 500,
   "nbFailed": 0,
   "nbAlreadyExisted": 20,
   "nbImported": 480
}
Note: In case, if you are encountering any of the below scenario, note the following:
  • If status is importing and nbProcessed is 0:
    • If you submitted only one request, just wait a few seconds for the request to be processed.
    • If you submitted multiple import requests, they have been put in aqueue. Import requests are processed one after the other So just wait for your request to start.
  • If status is importing and nbProcessed is stuck at a number (0 or other):
    • The server may have rebooted and the request has been lost. Submit your import request again.

Get the Details of a Client ID (or a Client ID for M2M), an Organization Administrator or an End User

1st Method - Using the Users Endpoint

If you already know the internal ID of a Client ID, an End User or an Organization Administrator, you can directly fetch their details using the Users endpoint. This is the most detailed view available.

For further information, see Internal IDs vs External IDs.

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

The response is the most detailed view of a Client ID, end user or Organization Administrator (here, we are browsing an end user):

{
   "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": "49996",
   "externalId": "rdavis@company.com",
   "meta":    {
      "resourceType": "User",
      "created": "2019-09-09T00:00:00Z",
      "location": "https://[base-server-url]/scim/{tenant}/v2/Users/49996",
      "version": "1"   },
   "userName": "rdavis@company.com",
   "name":    {
      "familyName": "Davis",
      "givenName": "Richard"   },
   "displayName": "Richard Davis",
   "title": "M.",
   "userType": "FTRESS",
   "active": true,
   "emails": [{"value": "rdavis2@company.com"}],
   "phoneNumbers": [{"value": "567 456 387"}],
   "groups": [   {
      "type": "Group",
      "display": "ROOT",
      "value": "UG_ROOT",
      "$ref": "https://[base-server-url]/scim/{tenant}/v2/Groups/UG_ROOT"   }],
   "roles": [],
   "urn:hid:scim:api:idp:2.0:UserAttribute": {"attributes":    [
            {
         "name": "ATR_EMAIL",
         "type": "string",
         "value": "rdavis2@company.com",
         "readOnly": false
      },
            {
         "name": "LASTNAME",
         "type": "string",
         "value": "Davis",
         "readOnly": false
      },
            {
         "name": "FIRSTNAME",
         "type": "string",
         "value": "Richard",
         "readOnly": false
      },
            {
         "name": "TITLE",
         "type": "string",
         "value": "M.",
         "readOnly": false
      },
            {
         "name": "ATR_MOBILE",
         "type": "string",
         "value": "567 456 387",
         "readOnly": false
      }
   ]},
   "urn:hid:scim:api:idp:2.0:UserAuthenticator": {"authenticators": []},
   "urn:hid:scim:api:idp:2.0:UserDevice": {"devices": []}
}

2nd Method - Using the Search Endpoint

If you do not know the internal ID of an end user, Client ID or an Organization Administrator, but you know its externalId, you can then use the Search endpoint to find it and browse the details.

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 \"rdavis@company.com\""}
Copy

The answer is equivalent to the one received with the 1st method, however, it is "search result formatted" (i.e. an array): 

{
   "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": "49976",
      "externalId": "rdavis@company.com",
      "meta":       {
         "resourceType": "User",
         "created": "2019-09-09T00:00:00Z",
         "location": "https://[base-server-url]/scim/{tenant}/v2/Users/49976",
         "version": "1"      },
      "userName": "rdavis@company.com",
      "name":       {
         "familyName": "Davis",
         "givenName": "Richard"      },
      "displayName": "Richard Davis",
      "title": "M.",
      "active": true,
      "emails": [{"value": "rdavis@company.com"}],
      "phoneNumbers": [{"value": "567 456 387"}],
      "groups": [      {
         "type": "Group",
         "display": "ROOT",
         "value": "UG_ROOT",
         "$ref": "https://[base-server-url]/scim/{tenant}/v2/Groups/UG_ROOT"      }],
      "roles": [],
      "urn:hid:scim:api:idp:2.0:UserAttribute": {"attributes":       [
                  {
            "name": "ATR_EMAIL",
            "type": "string",
            "value": "rdavis@company.com",
            "readOnly": false
         },
                  {
            "name": "LASTNAME",
            "type": "string",
            "value": "Davis",
            "readOnly": false
         },
                  {
            "name": "FIRSTNAME",
            "type": "string",
            "value": "Richard",
            "readOnly": false
         },
                  {
            "name": "TITLE",
            "type": "string",
            "value": "M.",
            "readOnly": false
         },
                  {
            "name": "ATR_MOBILE",
            "type": "string",
            "value": "567 456 387",
            "readOnly": false
         }
      ]},
      "urn:hid:scim:api:idp:2.0:UserAuthenticator": {"authenticators": []},
      "urn:hid:scim:api:idp:2.0:UserDevice": {"devices": []}
   }]
}

3rd Method - Using the UserInfo Endpoint

The UserInfo endpoint allows you to fetch basic information about the owner of the bearer token. If the bearer token is obtained with client_credentials, the UserInfo endpoint will return information about the Client ID that was used to get it, otherwise information about the indirect end user is returned.

For more information on direct and indirect users, see End Users.

For more information on the client_credentials authentication flow and other OpenID authentication flows, see OpenID Authentication Flows.

Simply call the UserInfo endpoint with your bearer token:

Copy 
GET https://[base-server-url]/{tenant}/authn/userinfo HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Copy

The response is an actual ID Token, Base 64 encoded:

eyJraWQiOiIxNTM2ODU0OTk4MTA3IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJqb2huLnNtaXRoQGdtYWlsLmNvbSIsImVtYWlsX3ZlcmlmaWV
kIjpmYWxzZSwiZ3JvdXBpZHMiOlsiVUdfUk9PVCJdLCJyb2xlcyI6W10sInBob25lX251bWJlcl92ZXJpZmllZCI6ZmFsc2UsInBob25lX251bWJlciI6I
jg3NiA1NjcgNDU2IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiam9obi5zbWl0aEBnbWFpbC5jb20iLCJlbWFpbCI6ImpvaG4uc21pdGhAZ21haWwuY29tIn0. KZ24TGBszK-Cx3jpseuNKO6TZN0x-uIUwxNYRVb5Rba5pMmSV4cVNXsx6SKDIlTUnVwJpF1pZKTkEqHhtCIjCFPB2djE0ytMdeU5PBRPIbYYp1YL78A1cVRTDM7uNpbnULSZifCQv8ha7bRNLfiwQGinh8oAJCzFMJRSnbR2r
JSw48PubpJvIs4dVtfDY1cF1aGBHQlEr2k60pYtBref7mUkTHbOX9c4k9KDMgV02gEJbhzVVEP33BD_OWsJdw_aaouC6Zko5qYYtBr1m6om93gMlt4MB_MLPMccmRjJAyUeFuesCvge9NWfdopU2RmYcn2bRaKoS6Iy4USzFUXiJg. 

In order to read the data, you need to split the token by matching the dots (.) and base64 decode the second part. For a full guide on how to handle ID Tokens, see Making the most of Tokens.

Copy 
String token = "..."; 
Array[String] splitToken = [];
splitToken = token.split( '.' ); // 0 based result array => [0 => header, 1 => body, 2 => signature]
String data = splitToken[1]; // Fetch the body to have the data

The base64 decoded header, body and signature. Note that the content of the body depends on the OpenID scopes defined on the Client ID used to get the bearer token. To know more about OpenID scopes and the way they impact the User info endpoint, see Using OpenID Scopes.

Copy

Header

{
  "kid": "1536854998107",
  "alg": "RS256"}
Copy

Body

{
  "sub": "john.smith@company.com",
  "email_verified": false,
  "groupids": [
    "UG_ROOT"  ],
  "roles": ["RL_ORGADMIN"],
  "phone_number_verified": false,
  "phone_number": "876 567 456",
  "preferred_username": "john.smith@company.com",
  "email": "john.smith@company.com"}
Copy

Signature

KZ24TGBszK-Cx3jpseuNKO6TZN0x-uIUwxNYRVb5Rba5pMmSV4cVNXsx6SKDIlTUnVwJpF1pZKTkEqHhtCIjCFPB2djE0ytMdeU5PBRPIbYYp1YL
78A1cVRTDM7uNpbnULSZifCQv8ha7bRNLfiwQGinh8oAJCzFMJRSnbR2rJSw48PubpJvIs4dVtfDY1cF1aGBHQlEr2k60pYtBre
f7mUkTHbOX9c4k9KDMgV02gEJbhzVVEP33BD_OWsJdw_aaouC6Zko5qYYtBr1m6om93gMlt4MB_MLPMccmRjJAyUeFuesCvge9NWfdopU2RmYcn2bRaKoS6Iy4USzFUXiJg 


Retrieve a Client ID Configuration

While the Search and Users endpoints provide us with the basic data (externalId, internal ID, names, authenticators, devices ...), they do not provide configuration details for Client IDs.

To fetch these details, you need to use the Register endpoint.

Here, we look for the configuration for the Client ID with the "23037978973074996612022322309357694048700176080" externalId.

Copy 
GET https://[base-server-url]/{tenant}/authn/register/23037978973074996612022322309357694048700176080 HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Copy

The response contains all the Client ID configuration attributes:

{
   "hid_sessiontransfer_type": "NUM001",
   "grant_types":    [
      "client_credentials",
      "password",
      "authorization_code"   ],
   "hid_refresh_token_validity": "3600",
   "registration_client_uri": "https://[base-server-url]/{tenant}/authn/register/23037978973074996612022322309357694048700176080",
   "redirect_uris":    [
      "https://client2.example.org",
      "https://client.example.org"   ],
   "hid_client_channel": "CH_EXTRAPP",
   "token_endpoint_auth_method": "client_secret_post",
   "client_id": "23037978973074996612022322309357694048700176080",
   "hid_client_pwd_policy": "AT_SYSLOG",
   "hid_client_consentprompt": "false",
   "hid_client_pki_policy": "AT_JWT",
   "hid_client_scopes": "{\"scopes\":[\"openid\",\"profile\"]}",
   "hid_user_channel": "CH_EXTRAPP",
   "hid_user_authn_policy": "AT_STDPWD",
   "client_id_issued_at": 1568193712,
   "tls_client_certificate_bound_access_tokens": false,
   "client_name": "mynewclient2"}

Search for End Users / List End Users

List All End Users

In order to list all End users, simply carry out a search on the UG_ROOT group:

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":"groups eq \"UG_ROOT\""}
Copy

The response is an array of user entries: 

{
   "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
   "totalResults": 28,
   "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": "23864",
         "externalId": "jsmith@company.com",
         
        (...)
      },
      {
         "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": "23884",
         "externalId": "rdavis@company.com",
         
        (...)
      },

    (...)    
    ]}
}

Search for End Users

To search an end users, simply use the same technique as described above, but add filters by using the AND operator. Do not omit the filter on the group, or you may fetch as well client IDs or Organization Administrators.

Examples of filters:

  • Find all end users whose externalId contains "smith":

groups eq \"UG_ROOT\" and externalId co \"smith\"

  • Find all end users whose familyName starts with "dav":

groups eq \"UG_ROOT\" and name.familyName sw \"dav\"

  • Find all end users that have a company email address (that ends with "company.com"):

groups eq \"UG_ROOT\" and emails ew \"company.com\"

  • Find all end users that have at least a phone number defined ("pr" operator stands for "presence"):

groups eq \"UG_ROOT\" and phoneNumbers pr

  • Find the end users defined with a certain mobile phone (the HID Authentication Service does not enforce any unique constraint on the mobile phone attribute).

    We are using the user attributes here. The HID Authentication Service allows only one attribute per filter, as the "or" operator is not supported:

groups eq \"UG_ROOT\" and urn:hid:scim:api:idp:2.0:UserAttribute:attributes.name eq ATR_MOBILE and urn:hid:scim:api:idp:2.0:UserAttribute:attributes.value eq \"2312312321\"

  • Find the end users that are assigned a certain role: 

groups eq \"UG_ROOT\" and role eq \"myCustomRole\"

For a complete guide on the Search features of the HID Authentication Service, sorting and pagination, see Searching with the SCIM API.

Search for Client IDs

List All Client IDs

In order to list all Client IDs, simply carry out a search on the UG_CLIENTIDgroup:

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":"groups eq \"UG_CLIENTID\""}

Search for Client IDs

To search for Client IDs, simply use the same technique as described above, but add filters by using the AND operator. Do not omit the filter on the group, or you may fetch End users or Organization Administrators.

  • Filter only simple Client IDs:

groups eq \"UG_CLIENTID\" and role eq \"RL_OPENIDCLIENT\"

  • Filter Only M2M Client IDs:

groups eq \"UG_CLIENTID\" and role eq \"RL_CLIENTIDM2M\"

For a complete guide on the Search features of the HID Authentication Service, sorting and pagination, see Searching with the SCIM API.

Search for Organization Administrators

List All Organization Administrators

In order to list all Organization Administrators, simply carry out a search on the UG_ORGADMIN group:

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":"groups eq \"UG_ORGADMIN\""}

Search Organization Administrators

To search for Organization Administrators, see Search for End User, but replace the group filter with UG_ORGADMIN.

Assign a Role to an End User, a Client ID or an Organization Administrator

The first thing, when assigning a role, is to have the internal ID of the User. If you already have the internal ID of the User, skip the first step.

If you know the externalId of the user, the first step is to look for the internal ID of the user. For further, see Internal IDs vs External IDs.

Here we search for the user with the externalId "bdavis@company.com".

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 \"bdavis@company.com\""}

The response contains the internal ID in the attribute id, here 49796.

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": "49796",
      "externalId": "rdavis@company.com",
      
      (...)
   }]
}

We use now the internal ID with the Users endpoint, carrying our a PUT request. We set the roles attribute to the required role.

Important:

When using the Users endpoint with the PUT method, the HID Authentication Service performs a full update of the user.

Thus, the HID Authentication Service works with a replacement approach, it means that the values will not be added but replaced with the new value you indicate.

For example, if the user is already assigned the roles "OneRole" and "AnotherRole", passing one role "MyCustomRole" in the request will overwrite the roles attribute with the only value "MyCustomRole" (and thus remove the previously assigned roles).

In order to "add" a new role, you need to pass the full list in the roles attribute. To achieve this, reuse the JSON that was provided by the HID Authentication Service as a response of the Search endpoint in order to build your request.

"roles":[
   {
      "value":"OneRole"   }, 
  {
      "value":"AnotherRole"   }, 
   {
      "value":"MyCustomRole"   }
],
Copy 
PUT https://[base-server-url]/scim/{tenant}/v2/Users/49796 HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: "application/scim+json"{
   "schemas":[
      "urn:ietf:params:scim:schemas:core:2.0:User",
      "urn:hid:scim:api:idp:2.0:Attribute",
      "urn:hid:scim:api:idp:2.0:UserDevice"   ],
   "externalId":"bdavis@company.com",
   "roles":[
      {
         "value":"MyCustomRole"      }
   ],
   "groups":[
      {
         "value":"UG_ROOT"      }
   ]
}

Elevate an End User to the Role of Organization Administrator

In order to elevate and end user to the role of Organization Administrator, you need to move the user to the group UG_ORGADMIN and assign the role RL_ORGADMIN to them.

This can be done in a single PUT request to the Users endpoint, assuming you already know the user's internal ID.

Copy 
PUT https://[base-server-url]/scim/{tenant}/v2/Users/49796 HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: "application/scim+json"{
   "schemas":[
      "urn:ietf:params:scim:schemas:core:2.0:User",
      "urn:hid:scim:api:idp:2.0:Attribute",
      "urn:hid:scim:api:idp:2.0:UserDevice"   ],
   "externalId":"bdavis@company.com",
   "roles":[
      {
         "value":"RL_ORGADMIN"      }
   ],
   "groups":[
      {
         "value":"UG_ORGADMIN"      }
   ]
}

Elevate an Client ID to the Role of Client ID for M2M

In order to elevate and Client ID to the role of Client ID for M2M, you need to assign the role RL_CLIENTM2M.

This can be done in a single PUT request to the Users endpoint, assuming you already know the user's internal ID.

Copy 
PUT https://[base-server-url]/scim/{tenant}/v2/Users/49787 HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: "application/scim+json"{
   "schemas":[
      "urn:ietf:params:scim:schemas:core:2.0:User",
      "urn:hid:scim:api:idp:2.0:Attribute",
      "urn:hid:scim:api:idp:2.0:UserDevice"   ],
   "externalId":"87198273918723981723987192873918273981723982765987987",
   "roles":[
      {
         "value":"RL_CLIENTIDM2M"      }
   ],
   "groups":[
      {
         "value":"UG_CLIENTID"      }
   ]
}

Update an End User (or Organization Administrator)

Important:

The HID Authentication Service SCIM API is designed with a replacement approach when it comes to updates.

This means that omitting an attribute that was set on the user on an update request will simply remove/empty this attribute.

The recommended process to update a user, is to first fetch the details of this user, and then modifying the returned JSON.

We first need to fetch the details of the user, either with the internal ID or the externalId.

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 \"bdavis@company.com\""}
Copy

The response is a detailed view of the user: 

{
   "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": "49796",
      "externalId": "bdavis@company.com",
      "meta":       {
         "resourceType": "User",
         "created": "2019-09-06T00:00:00Z",
         "location": "https://[base-server-url]/scim/{tenant}/v2/Users/49796",
         "version": "1"      },
      "userName": "bdavis@company.com",
      "name":       {
         "familyName": "Davis",
         "givenName": "Brian"      },
      "displayName": "Brian Davis",
      "title": "M.",
      "active": true,
      "emails": [{"value": "bdavis@company.com"}],
      "phoneNumbers": [{"value": "567 890 654"}],
      "groups": [      {
         "type": "Group",
         "display": "ROOT",
         "value": "UG_ROOT",
         "$ref": "https://[base-server-url]/scim/{tenant}/v2/Groups/UG_ROOT"      }],
      "roles": [],
      "urn:hid:scim:api:idp:2.0:UserAttribute": {"attributes":       [
                  {
            "name": "ATR_EMAIL",
            "type": "string",
            "value": "bdavis@company.com",
            "readOnly": false
         },
                  {
            "name": "LASTNAME",
            "type": "string",
            "value": "Davis",
            "readOnly": false
         },
                  {
            "name": "FIRSTNAME",
            "type": "string",
            "value": "Brian",
            "readOnly": false
         },
                  {
            "name": "TITLE",
            "type": "string",
            "value": "M.",
            "readOnly": false
         },
                  {
            "name": "ATR_MOBILE",
            "type": "string",
            "value": "567 890 654",
            "readOnly": false
         }
      ]},
      "urn:hid:scim:api:idp:2.0:UserAuthenticator": {"authenticators": []},
      "urn:hid:scim:api:idp:2.0:UserDevice": {"devices": []}
   }]
}

Now that we have the JSON based detail of the user, we can simply reuse it by changing the attributes that need to be updated, along with a PUT request. The internal id 40796 is used as a path parameter of the query.

Note:

  • The externalId cannot be updated. We recommend to avoid changing the emails if you use it as an externalId. It is better to delete the user and create another one with the correct email / external ID.

  • The following fields are immutable, to change their value, update the corresponding extra attributes with urn:hid:scim:api:idp:2.0:UserAttribute:

    • name (object):

      • familyName and givenName

    • title: the title (M., Ms., Dr. ...)

    • emails (array of objects):

      • value and type (work, personal ...)

    • phoneNumbers (array of objects):

      • value

  • Devices and authenticators can also be updated (see Enabling User Authentication)

Here we change the email address, the family and first names, the title, the phone number as well as elevating the user to the role of Organization Administrator (by changing the group and assigning a role).

Copy 
PUT https://[base-server-url]/scim/{tenant}/v2/Users/49796 HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: "application/scim+json"{
   "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":"49796",
   "externalId":"bdavis@company.com",
   "meta":{
      "resourceType":"User",
      "created":"2019-09-06T00:00:00Z",
      "location":"https://[base-server-url]/scim/{tenant}/v2/Users/49796",
      "version":"1"   },
   "userName":"bdavis@company.com",
   "name":{
      "familyName":"Davis",
      "givenName":"Brian"   },
   "displayName":"Brian Davis",
   "title":"M.",
   "active":true,
   "emails":[
      {
         "value":"bdavis@company.com"      }
   ],
   "phoneNumbers":[
      {
         "value":"567 890 654"      }
   ],
   "groups":[
      {
         "value":"UG_ORGADMIN"      }
   ],
   "roles":[
      {
         "value":"RL_ORGADMIN"      }
   ],
   "urn:hid:scim:api:idp:2.0:UserAttribute":{
      "attributes":[
         {
            "name":"ATR_EMAIL",
            "type":"string",
            "value":"bdavis-second@company.com",
            "readOnly":false
         },
         {
            "name":"LASTNAME",
            "type":"string",
            "value":"Davis Stephan",
            "readOnly":false
         },
         {
            "name":"FIRSTNAME",
            "type":"string",
            "value":"Brian John",
            "readOnly":false
         },
         {
            "name":"TITLE",
            "type":"string",
            "value":"Mr",
            "readOnly":false
         },
         {
            "name":"ATR_MOBILE",
            "type":"string",
            "value":"897 678 456",
            "readOnly":false
         }
      ]
   },
   "urn:hid:scim:api:idp:2.0:UserAuthenticator":{
      "authenticators":[
      ]
   },
   "urn:hid:scim:api:idp:2.0:UserDevice":{
      "devices":[
      ]
   }
}

Update a Client ID (or a Client ID for M2M)

In order to update the basic data of a Client ID (groups, roles, extra attributes), see Update an End User and search for a Client ID instead of an End user.

To update the configuration of a Client ID, you need to use the OpenID Register endpoint with a PUT request, indicating the externalId of the Client ID in the client_id attribute. For further information about the attributes, see Register a Client ID.

Note:

  • It is not possible to update the group attribute hid_client_group with this endpoint. To do so, use the Users endpoint instead.

  • The jwks attribute changes the Client ID's PKI credential (certificate based), if the Client ID does not have any PKI credential, it creates a new one with the corresponding authentication policy (set in the attribute hid_client_pki_policy).

  • All the attributes of the request, apart from client_id, are optional. Omitting to provide them is not emptying their value, contrary to the Users endpoint.

Copy 
PUT https://[base-server-url]/{tenant}/authn/register HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: application/json
{
   "redirect_uris":[
      "https://www.myCustomRedirectURL.com"   ],
   "client_name":"My new client ID name ",
   "client_id":"186070539305161126850183514319657725837614882667",
   "hid_client_channel":"CH_EXTRAPP",
   "hid_client_pwd_policy":"AT_SYSLOG",
   "hid_client_pki_policy":"AT_JWT",
   "hid_user_channel":"CH_EXTRAPP",
   "hid_user_authn_policy":"AT_STDPWD",
   "hid_sessiontransfer_type":"NUM001",
   "hid_client_scopes":"{\"scopes\":[\"openid\",\"profile\"]}",
   "hid_federation_audiences":"",
   "hid_federation_roles":"",
   "hid_federation_atttype":""}

Delete an End User or Organization Administrator

Important: Do not use this method to delete Client IDs!

You will delete the user but would leave an orphan Client ID "configuration" in the background. This orphan configuration might prevent you from re-creating a Client ID with the same externalId.

For further information, see Delete a Client ID.

First, we search for the user to fetch their internal ID:

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 \"bdavis@company.com\""}

The response contains the internal ID, (here 49796):

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": "49796",
      "externalId": "bdavis@company.com",
      
      (...)
}

Use this internal ID as a path parameter of a DELETE request.

Copy 
DELETE https://[base-server-url]/scim/{tenant}/v2/Users/49796 HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN

Delete a Client ID

To delete a Client ID, simply use a DELETE request with the OPENID registration endpoint, passing the externalId of the Client ID as a path parameter.

Here we delete the Client ID whose externalId is 23037978973074996612022322309357694048700176080.

Copy 
DELETE https://[base-server-url]/{tenant}/authn/register/23037978973074996612022322309357694048700176080 HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN

 

See also:

Managing User or Client ID Authenticators

Enabling User Authentication