IBM Security Verify

Introduction

Managing Users via API 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 the User REST APIs available in Cloud Identity with some samples. Should you have any questions, feel free to reach out to our support team via www.ibm.com/mysupport or comment below. 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:

Content-Type: application/scim+json
Accept: application/scim+json

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

Authorization: Bearer myAccessTokentzkhVdRO8FE6f08CTKny4AbUl18

Call 1 / Get all users

Note: This API limits the number of users returned to the first 500 users. If you have more than 500 users, you should see "totalResults": 500 in the response, then you know you've hit the limit. Use filtering to get more specific with your search. (See Call 2 below).

Endpoint: GET /v2.0/Users

Make the call:

A 200 Response (example):

{
    "totalResults": 2, 
    "Resources": [
        {
            "userName": "admin@us.ibm.com", 
            "name": {
                "givenName": "Scott", 
                "familyName": "Damon", 
                "formatted": "Scott Damon"
            }, 
            "urn:ietf:params:scim:schemas:extension:ibm:2.0:User": {
                "userCategory": "regular", 
                "realm": "cloudIdentityRealm", 
                "twoFactorAuthentication": false, 
                "pwdChangedTime": "2018-06-05T21:12:06Z"
            }, 
            "emails": [
                {
                    "type": "work", 
                    "value": "admin@us.ibm.com"
                }
            ], 
            "meta": {
                "lastModified": "2018-06-05T21:12:06Z", 
                "created": "2018-06-05T21:11:19Z"
            }, 
            "active": true, 
            "id": "50TT16RH5T"
        },
        {
            "userName": "employee@us.ibm.com", 
            "phoneNumbers": [
                {
                    "type": "mobile", 
                    "value": "1-111-222-3333"
                }
            ], 
            "name": {
                "givenName": "Employee", 
                "familyName": "User", 
                "formatted": "Employee User"
            }, 
            "urn:ietf:params:scim:schemas:extension:ibm:2.0:User": {
                "userCategory": "regular", 
                "realm": "cloudIdentityRealm", 
                "twoFactorAuthentication": false, 
                "pwdChangedTime": "2018-08-29T19:17:13Z", 
                "pwdReset": true
            }, 
            "emails": [
                {
                    "type": "work", 
                    "value": "employee@us.ibm.com"
                }
            ], 
            "meta": {
                "lastModified": "2018-08-29T19:17:13Z", 
                "created": "2018-08-29T19:17:13Z"
            }, 
            "active": true, 
            "id": "50Q0X1SFJK"
        }
    ], 
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ]
}

Note:

(1) A ListResponse is returned on simple GET call and on GET users with filtering. See Call 2. Due to performance implications, the user records returned do not contain the groups that the user belongs to. 
(2) Each user contains a unique attribute id.  Use this to get the full record of the user. See Call 4. This includes the groups that the user belongs to. 

Call 2 / Get users with filtering

As you can see the response above has the potential to be quite large and exclude some as the response is limited to 500 users. The User API allows SCIM compliant search filtering based on the attributes of the user. You can retrieve a list of users that belong to a specified tenant and match the search filter criteria.

(A) A simple filter 

Endpoint: GET /v2.0/Users?filter=attribute operator value

The call below filters for username equal “employee@us.ibm.com”

Make the call:

A 200 Response (example):

{
    "totalResults": 1, 
    "Resources": [
        {
            "userName": "employee@us.ibm.com", 
            "phoneNumbers": [
                {
                    "type": "mobile", 
                    "value": "1-111-222-3333"
                }
            ], 
            "name": {
                "givenName": "Employee", 
                "familyName": "User", 
                "formatted": "Employee User"
            }, 
            "urn:ietf:params:scim:schemas:extension:ibm:2.0:User": {
                "userCategory": "regular", 
                "realm": "cloudIdentityRealm", 
                "twoFactorAuthentication": false, 
                "pwdChangedTime": "2018-08-29T19:17:13Z", 
                "pwdReset": true
            }, 
            "emails": [
                {
                    "type": "work", 
                    "value": "employee@us.ibm.com"
                }
            ], 
            "meta": {
                "lastModified": "2018-08-29T19:17:13Z", 
                "created": "2018-08-29T19:17:13Z"
            }, 
            "active": true, 
            "id": "50Q0X1SFJK"
        }
    ], 
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ]
}

(B) You can also filter Users by attributes that are part of a schema.

Endpoint: GET /v2.0/Users?filter=schema:attribute operator value

The call below filters for userCategory equal “regular” under schema "urn:ietf:params:scim:schemas:extension:ibm:2.0:User"

Make the call:

curl -X GET \
https://mytenant.ice.ibmcloud.com/v2.0/Users?filter=urn:ietf:params:scim:schemas:extension:ibm:2.0:User:userCategory eq "regular" \
-H 'Content-Type: application/scim+json' \
-H 'Accept: application/scim+json' \
-H 'Authorization: Bearer myAccessTokentzkhVdRO8FE6f08CTKny4AbUl18'

A 200 Response (example):

{
    "totalResults": 1, 
    "Resources": [
        {
            "userName": "employee@us.ibm.com", 
            "phoneNumbers": [
                {
                    "type": "mobile", 
                    "value": "1-111-222-3333"
                }
            ], 
            "name": {
                "givenName": "Employee", 
                "familyName": "User", 
                "formatted": "Employee User"
            }, 
            "urn:ietf:params:scim:schemas:extension:ibm:2.0:User": {
                "userCategory": "regular", 
                "realm": "cloudIdentityRealm", 
                "twoFactorAuthentication": false, 
                "pwdChangedTime": "2018-08-29T19:17:13Z", 
                "pwdReset": true
            }, 
            "emails": [
                {
                    "type": "work", 
                    "value": "employee@us.ibm.com"
                }
            ], 
            "meta": {
                "lastModified": "2018-08-29T19:17:13Z", 
                "created": "2018-08-29T19:17:13Z"
            }, 
            "active": true, 
            "id": "50Q0X1SFJK"
        }
    ], 
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ]
}

Call 3 / Get users and limit returned attributes

Many a time you don’t need all the attributes returned on every user. The User API allows you to specify the attributes you are interested in.

Endpoint: GET /v2.0/Users?attributes=<list of comma separated attributes>

The call below limits attributes returned to id and userName.

Make the call:

A 200 Response (example):

{
    "totalResults": 2, 
    "Resources": [
        {
            "userName": "admin@us.ibm.com", 
            "id": "50TT16RH5T"
        },
        {
            "userName": "employee@us.ibm.com", 
            "id": "50Q0X1SFJK"
        }
    ], 
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ]
}

Call 4 / Get user by ID

You can get a single user if you know the “id” of the user. You specify that as a part of the URL. This also returns the groups that the user belongs to.

Note: The response is not a ListResponse as we are specifically requesting a single user.

Endpoint: GET /v2.0/Users/{ID}

Make the call:

A 200 Response (example):

{
      "userName": "employee@us.ibm.com", 
      "phoneNumbers": [
          {
              "type": "mobile", 
              "value": "1-111-222-3333"
          }
      ], 
      "name": {
          "givenName": "Employee", 
          "familyName": "User", 
          "formatted": "Employee User"
      }, 
      "urn:ietf:params:scim:schemas:extension:ibm:2.0:User": {
          "userCategory": "regular", 
          "realm": "cloudIdentityRealm", 
          "twoFactorAuthentication": false, 
          "pwdChangedTime": "2018-08-29T19:17:13Z", 
          "pwdReset": true
      }, 
      "emails": [
          {
              "type": "work", 
              "value": "employee@us.ibm.com"
          }
      ], 
      "meta": {
          "resourceType": "User", 
          "lastModified": "2018-08-29T19:17:13Z", 
          "created": "2018-08-29T19:17:13Z", 
          "location": "https://mytenant.ice.ibmcloud.com/v2.0/Users/50Q0X1SFJK" 
      },
      "groups": [
        {
            "displayName": "developers", 
            "id": "50J342PXYZ", 
            "$ref": "https://mytenant.ice.ibmcloud.com/v2.0/Groups/50J342PXYZ"
        }
      ], 
      "active": true, 
      "id": "50Q0X1SFJK",
      "schemas": [
          "urn:ietf:params:scim:schemas:core:2.0:User", 
          "urn:ietf:params:scim:schemas:extension:ibm:2.0:User"
      ]
}

Call 5 / Create, modify, delete a user

Create a user

We’ll use a simple payload to demonstrate create user. 

Note: You can set a password for the user in the payload. If omitted, a password will be generated and by default emailed to the user. The password is not returned in the response. The user will be asked to change the password at first login. 

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", 
  "password": "myPassw0rd",
  "name": 
   {
      "familyName": "Bratten", 
      "givenName": "Jessica" 
   }, 
  "emails": [ 
     {
       "type": "work", 
       "value": "jessica@us.ibm.com" 
     } 
   ] 
}

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

Modify user

Modifying a user is very similar to the create call above. You need the id of the user you are modifying. You specify that as a part of the URL. Also, the method changes to PUT. This replaces the user's attributes in Cloud Identity. On Success (200 response), the return response contains the details of the user and includes any groups to which the user belongs

Endpoint: PUT /v2.0/Users/{ID}

The call:

Response: A successful call is indicated by a status code of 200 and the response is the same as the create call above.

Delete user

Deletes a user from a specified tenant in Cloud Directory. The user is also removed from any groups to which the user belongs. You need the id of the user that you are deleting and you specify that as a part of the URL.

Endpoint: DELETE /v2.0/Users/{ID}

The call:

A 204 Response (example):

<no text returned>

Summary

Using the IBM Cloud Identity REST API, you are able to fully manage your Cloud Identity Users.

#CloudIdentity
​