Introduction

User Custom Attributes via REST APIs in IBM Cloud Identity

IBM Cloud Identity’s suite of products includes robust REST APIs to be used within your applications. You can use the API framework to authenticate users, add applications, view multi-factor transactions, and a lot more. The following article is an overview of managing custom attributes for Users via REST APIs available in Cloud Identity with some samples. Should you have any questions, feel free to comment below or reach out directly to our support team via www.ibm.com/mysupport. There is also another good place to ask questions located here.

Pre-requisites

To make any API call you need an access token. The APIs are secured with OAuth and you should use the API Access panel to manage access/permissions.  The “Getting started with IBM Cloud Identity REST APIs” article helps you through the requisite steps in setting up an API Client and obtaining an access token: Getting started with IBM Cloud Identity Rest APIs

Note: The API client used to obtain the access token must have the “Manage Users and Standard Groups” access enabled, at a minimum for this particular exercise. 

API Documentation

The API documentation for your tenant is located here:

https://mytenant.ice.ibmcloud.com/developer/explorer/#/Users_Management_Version_2.0

Note: Make sure you replace mytenant.ice.ibmcloud.com with your tenant and in the rest of the examples below.

The Users REST API adheres to the SCIM specification found here: http://www.simplecloud.info/  
Every call requires these two headers:

In the header of your API calls remember to replace the access token received from your authorization response.

Authorization: Bearer myAccessTokentzkhVdRO8FE6f08CTKny4AbUl18

Why Custom Attributes?

The IBM Cloud Identity SCIM user has a rich set of default attributes. However, as client needs vary, you find the need to save client specific custom information within the user record itself. IBM Cloud Identity allows you to extend the user schema to add custom attributes. This can be done in two easy steps:

1. Extend the existing user schema and define/create all the necessary custom attributes.
2. Use the new custom attributes (in the payload) as you create and modify users.

Two Types of Custom Attributes

There are two types of custom attribute, single-valued and multi-valued. The single-valued attribute holds one value, while the multi-valued attribute holds more than one value in an array.

To put all of this together let’s look at some REST calls.

Call 1 / List all schema attributes

Let’s get a list of all the schema attributes available for a User record for your tenant.

Endpoint: GET /v2.0/Schema/attributes

Make the call:

A 200 Response (example):

{
   "totalResults”: 43,
   "Resources”: [
      {
         "multiValue”: false,
         "type”: "string",
         "schemas”: [
            "urn:ietf:params:scim:schemas:ibm:core:2.0:SchemaAttribute"
         ],
         "attributeName”: "id",
         "customAttribute”: false,
         "scimName”: "id",
         "description”: "The unique identifier for the user.",
         "name": "uid"
      },
      {
         "multiValue": false,
         "type": "string",
         "schemas": [
            "urn:ietf:params:scim:schemas:ibm:core:2.0:SchemaAttribute"
         ],
         "scimName": "userName",
         "customAttribute": false,
         "name": "cn",
         "description": "The unique identifier for the user, that is used by the user to directly authenticate to the service provider.",
         "attributeName": "preferred_username"
      },
    
  
 . . . truncated . . . 
    

   ],
   "schemas" : [
      "urn:ietf:params:scim:schemas:ibm:core:2.0:SchemaAttributeListResponse"
   ]
}

The response above (truncated) lists a total of 43 attributes. And each attribute has its own definition. Here’s what they mean:

• "customAttribute”: false
  • false, for a “default” attribute.
  • true, for a “custom” attribute.
• "multiValue”: false
  • The attribute is single value. (as opposed to true, where you can save an array of strings).
• "type”: "string"
  • Is of type string
• "schemas”: ["urn:ietf:params:scim:schemas:ibm:core:2.0:SchemaAttribute"]
  • The schema this attribute belongs to.
• "scimName”: "id",
  • The scim name by which this attribute is referenced in the User SCIM API.
• "description”: "The unique identifier for the user.",
  • A field for a short description of the attribute.
• "name": "uid"
  • These are predefined and cannot be changed.
  • For custom attributes, names range from customAttribute1 to customAttribute25.

Call 2 / Filter schema attributes

You can add a filter to the attribute’s API. Here are some examples. The call is very similar to the one above, so for brevity’s sake I’ll omit the call and the corresponding response for the first 3 examples.

Show default schema attributes only

Endpoint: GET /v2.0/Schema/attributes?filter=default

Show custom schema attributes only

Endpoint: GET /v2.0/Schema/attributes?filter=custom

Show custom schema attributes “names” that are available for use

Endpoint: GET /v2.0/Schema/attributes?filter=customAvailable

If you have no custom attributes set up yet, this should return a list of 25 attributes.

Searches all the attribute schema values for “departmentNumber”

Endpoint: GET /v2.0/Schema/attributes?fullText=departmentNumber

Make the call:

A 200 Response (example):

{
   "Resources”: [
      {
         "description”: "Identifies the name of the department.",
         "attributeName”: "department",
         "scimName": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department",
         "name": "departmentNumber",
         "type": "string",
         "customAttribute": false,
         "schemas": [
            "urn:ietf:params:scim:schemas:ibm:core:2.0:SchemaAttribute"
         ],
         "multiValue": false
      }
   ],
   "totalResults": 1,
   "schemas": [
      "urn:ietf:params:scim:schemas:ibm:core:2.0:SchemaAttributeListResponse"
   ]
}

Show details of schema attribute by name

Endpoint: GET /v2.0/Schema/attributes/departmentNumber

The call:

A 200 Response (example):

{
   "scimName": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department",
   "customAttribute": false,
   "name": "departmentNumber",
   "schemas": [
      "urn:ietf:params:scim:schemas:ibm:core:2.0:SchemaAttribute"
   ],
   "description": "Identifies the name of the department.",
   "multiValue": false,
   "type": "string",
   "attributeName": "department"
}

Call 3 / Create custom schema attributes

The payload below creates a "single-valued" custom schema attribute.
To change this to a “multi-valued” attribute, set “multiValue” to true. Example, ("multiValue": true)

You can create up to 25 custom attributes.

Create a custom schema attribute

Endpoint: POST /v2.0/Schema/attributes

The payload data: (save in a file eg: customattribute-payload.json)

{ 
     "schemas”: ["urn:ietf:params:scim:schemas:ibm:core:2.0:SchemaAttribute"],
     "name": "customAttribute1",
     "description": "The users car",
     "displayName": "Car",
     "type": "string",
     "scimName": "car",
     "multiValue": false,
     "customAttribute": true
}

The call:

A 201 Response (example):

{
    "displayName": "Car", 
    "description": "The users car", 
    "attributeName": "car", 
    "scimName": "car", 
    "customAttribute": true, 
    "multiValue": false, 
    "schemas": [
        "urn:ietf:params:scim:schemas:ibm:core:2.0:SchemaAttribute"
    ], 
    "type": "string", 
    "name": "customAttribute1"
}

Call 4 / Use custom schema attributes

Now you can use the newly created custom schema attribute when you create or update any user for that tenant. The example below shows a user create and sets a single-value custom attribute.

If the custom attribute “car” was a multi-valued attribute, you would change the value to an array.

For example change this, "values": “My Car 1” to this "values": [“My Car 1”] or "values": [“My Car 1”, “My Car 2”, “My Car 3”].

Note: Custom attributes always are a part of this schema in the User record under the schema urn:ietf:params:scim:schemas:extension:ibm:2.0:User.

Endpoint: POST /v2.0/Users

The payload data: (save in a file eg: user-payload.json)

{    
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User",
              "urn:ietf:params:scim:schemas:extension:ibm:2.0:User"], 
  "userName": "jessica@us.ibm.com", 
  "name": 
   {
      "familyName": "Bratten", 
      "givenName": "Jessica" 
   }, 
  "emails": [ 
     {
       "type": "work", 
       "value": "jessica@us.ibm.com" 
     } 
   ] 
  "urn:ietf:params:scim:schemas:extension:ibm:2.0:User":
     {
       "customAttributes": [
          { 
            "name": "car",
            "values": “My Car 1”
          }
       ]
   }
}

The call:

A 201 Response (example):

{
    "userName": "jessica@us.ibm.com", 
    "name": {
        "givenName": "Jessica", 
        "familyName": "Bratten"
    }, 
    "urn:ietf:params:scim:schemas:extension:ibm:2.0:User": {
        "userCategory": "regular", 
        "realm": "cloudIdentityRealm", 
        "twoFactorAuthentication": false, 
        "pwdChangedTime": "2019-03-28T05:34:19Z", 
        "pwdReset": true,
        "customAttributes": [
            {
                "values": “My Car 1”, 
                "name": "car"
            }
        ]
    }, 
    "id": "6000006NQQ", 
    "meta": {
        "resourceType": "User", 
        "lastModified": "2019-03-28T05:34:19Z", 
        "location": "https://mytenant.ice.ibmcloud.com/v2.0/Users/6000006NQQ", 
        "created": "2019-03-28T05:34:19Z"
    }, 
    "active": true, 
    "emails": [
        {
            "type": "work", 
            "value": "jessica@us.ibm.com"
        }
    ], 
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User", 
        "urn:ietf:params:scim:schemas:extension:ibm:2.0:User"
    ]
}

Updating a user is no different with respect to the json payload when it comes to custom attributes. Remember to use the ID in the URL and change the method to PUT.

Call 5 / Delete custom schema attributes

A custom schema attribute can be deleted when there are no user records that contain values for this attribute. You’ll find more information in the documentation on how to find users that are still using a certain custom attribute.

Endpoint: DELETE /v2.0/Schema/attributes/customAttribute1

The call:

A 204 Response (example): <no text returned>

Summary

Using the IBM Cloud Identity REST API, you are able to extend your user record by adding custom attributes.

#CloudIdentity