Assigning 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.

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

To elevate a 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"   ],
   "roles":[
      {
         "value":"RL_CLIENTIDM2M"      }
   ],
   "groups":[
      {
         "value":"UG_CLIENTID"      }
   ]
}