Working with custom attributes

Introduction

The IBM Security Verify Cloud Directory defines a SCIM schema of user attributes that can be extended with custom attributes that are specific for your tenant. In this guide you will learn how to create a custom attribute to extend the SCIM schema, as well as create, update, and search for users with that custom attribute. The Attribute Management API and the Cloud Directory API will be shown using cURL examples to teach you how to call the REST APIs for IBM Security Verify.

Pre-requisites

You will need an API client that has the following entitlements in IBM Verify:

• Manage attributes (to create custom attributes)
• Read users and groups (to read user records)
• Manage users and standard groups (to read and manage user records)

See create an API client for information on creating an API client that can be used with the OAuth Client Credentials grant type flow to obtain an access token.

Variables

The following variables are needed to run the flow described in this guide:

Steps to guide you with examples

1. Create a custom SCIM attribute called hobbies.
2. Create a user with values set for hobbies.
3. Update the user record with different values for hobbies.
4. Search for the user using different filters for hobbies.

1. Create a custom attribute

It is recommended that you use the UI to create a custom attribute which provides a wizard to guide you through all the options. You can create up to 160 custom attributes to extend the SCIM user schema. There are 150 predefined custom schema attributes called customAttribute1 through customAttribute150, and 10 predefined hashed custom attributes called hashedCustomAttribute1 through hashedCustomAttribute10, that can be mapped to a SCIM schema name. In the Attribute Management REST API we are creating a custom attribute by mapping an available custom schema attribute to a SCIM schema attribute name, then it can be managed via the Cloud Directory Users SCIM REST API.

In this example, we are using customAttribute1 and mapping that to the SCIM name *hobbies that will support multiple values.

Calling the Attribute Management REST API to create a custom attribute using cURL:

curl -X POST "https://${tenant_url}/v1.0/attributes" -H "Authorization: Bearer ${access_token}" -H "Content-Type: application/json" --data-raw '{ "datatype":"string[]", "description":"The user'\''s hobbies.",  "name":"hobbies",  "schemaAttribute":{ "name":"customAttribute1", "scimName":"hobbies" },"scope":"tenant","sourceType":"schema"}'

If successful, you will see a 201 HTTP status code along with a response body containing the ID of the attribute that can be used to retrieve / modify / delete the attribute.

{"id":"f6067c0a-a88d-4b69-8e4e-0893c7663ff6"}

See API reference for create an attribute for more information on creating a custom attribute using the REST API.

Get the attribute by its ID

Using the "id" returned in the REST API response from creating the attribute, we can get the attribute by its ID.

Using cURL:

curl -X GET "https://${tenant_url}/v1.0/attributes/f6067c0a-a88d-4b69-8e4e-0893c7663ff6" -H "Authorization: Bearer ${access_token}"

If successful, you will see a 200 HTTP status code and a response body in JSON containing the attribute information.

{
    "id": "f6067c0a-a88d-4b69-8e4e-0893c7663ff6",
    "name": "hobbies",
    "description": "The user's hobbies.",
    "scope": "tenant",
    "sourceType": "schema",
    "datatype": "string[]",
    "schemaAttribute": {
        "name": "customAttribute1",
        "scimName": "hobbies",
        "customAttribute": true,
        "scimFilter": "urn:ietf:params:scim:schemas:extension:ibm:2.0:User:customAttributes.hobbies"
    }
}

See API reference for get an attribute for more information on getting an attribute using the REST API.

2. Create a user with some hobbies

Now that the custom attribute is created, you can set values for it using the Cloud Directory Users SCIM REST API. Let's create a user with
some hobbies that include painting and photography. In the SCIM schema the custom attribute is added to the
urn:ietf:params:scim:schemas:extension:ibm:2.0:User:customAttributes:[] array.

Using cURL:

curl -X POST "https://${tenant_url}/v2.0/Users" -H "Authorization: Bearer ${access_token}" -H "Content-Type: application/scim+json; charset=utf-8" -H "Accept: application/scim+json; charset=utf-8" --data-raw '{ "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User", "urn:ietf:params:scim:schemas:extension:ibm:2.0:User" ], "userName": "${email_address}", "name": { "familyName": "${family_name}", "givenName": "${given_name}" }, "emails":[ {"type":"work", "value":"${email_address}"} ], "urn:ietf:params:scim:schemas:extension:ibm:2.0:User": { "customAttributes":[ { "name":"hobbies", "values":["painting", "photography"] } ] }}'

If successful, you will see a 201 HTTP status code and the response body in JSON containing the user created.

{
    "emails": [
        {
            "type": "work",
            "value": "[email protected]"
        }
    ],
    "meta": {
        "created": "2021-11-03T13:38:19Z",
        "location": "https://gtatenantadmin.ite1.idng.ibmcloudsecurity.com/v2.0/Users/608000CXT7",
        "lastModified": "2021-11-03T13:38:19Z",
        "resourceType": "User"
    },
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:ibm:2.0:User"
    ],
    "urn:ietf:params:scim:schemas:extension:ibm:2.0:User": {
        "pwdReset": true,
        "userCategory": "regular",
        "twoFactorAuthentication": false,
        "realm": "cloudIdentityRealm",
        "pwdChangedTime": "2021-11-03T13:38:19Z",
        "customAttributes": [
            {
                "values": [
                    "painting",
                    "photography"
                ],
                "name": "hobbies"
            }
        ]
    },
    "name": {
        "formatted": "Jane Smith",
        "givenName": "Jane",
        "familyName": "Smith"
    },
    "active": true,
    "id": "608000CXT7",
    "userName": "[email protected]"
}

NOTE: a temporary password will be mailed to the user's email address.

See API reference for create a user for more information on creating a user using the REST API.

3. Update the user record with different values for hobbies.

Using Cloud Directory's PATCH /v2.0/Users/{id} API, you can update the record with different values for hobbies. Depending on what you want to do there are different ways to update the values for hobbies. Lets look at it in more detail.

The following PATCH request body uses the path urn:ietf:params:scim:schemas:extension:ibm:2.0:User:customAttributes with the add operation.

Take the payload below as an example. The value contains an array because the path is to the customAttributes[] array. The add operation will add hobbies to the customAttributes[] array if it does not exist. If it does exist, it will replace the values with the painting, photography, and decorating values.

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "add",
      "path": "urn:ietf:params:scim:schemas:extension:ibm:2.0:User:customAttributes",
      "value":[
        {
            "name":"hobbies",
            "values":["painting", "photography", "decorating"]
        }
      ]
    }
  ]
}

When using this path, the operations "add", "replace", and "remove" perform operations on the customAttributes[] array.

Here is table to summarize what each operation does when using path urn:ietf:params:scim:schemas:extension:ibm:2.0:User:customAttributes

Calling Cloud Directory PATCH API with the add operation using cURL:

curl -X PATCH "https://${tenant_url}/v2.0/Users/608000CXT7" -H "Authorization: Bearer ${access_token}" -H "Content-Type: application/scim+json; charset=utf-8" -H "Accept: application/scim+json; charset=utf-8" --data-raw '{"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "Operations": [ {"op": "add","path": "urn:ietf:params:scim:schemas:extension:ibm:2.0:User:customAttributes","value":[{"name":"hobbies","values":["painting", "photography", "decorating"]}]}]}'

If successful, you should see an HTTP status of 204 No content.

The user's record now has 3 hobbies that include painting, photography, and decorating.

The next example will show how you can add running and remove decorating from the hobbies custom attribute. Notice that the value in the payload is a string array, this is because the path is specifically updating the values[] array for the hobbies custom attribute.

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "add",
      "path": "urn:ietf:params:scim:schemas:extension:ibm:2.0:User:customAttributes[name eq \"hobbies\"].values",
      "value":["running"]
    },
    {
      "op": "remove",
      "path": "urn:ietf:params:scim:schemas:extension:ibm:2.0:User:customAttributes[name eq \"hobbies\"].values",
      "value": ["decorating"]
    }
   ]
}

Calling PATCH using cURL to add running and remove decorating from the user's hobbies:

curl -X PATCH "https://${tenant_url}/v2.0/Users/608000CXT7" -H "Authorization: Bearer ${access_token}" -H "Content-Type: application/scim+json; charset=utf-8" -H "Accept: application/scim+json; charset=utf-8" --data-raw '{"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],"Operations": [{"op": "add","path": "urn:ietf:params:scim:schemas:extension:ibm:2.0:User:customAttributes[name eq \"hobbies\"].values","value":["running"]},{"op": "remove","path": "urn:ietf:params:scim:schemas:extension:ibm:2.0:User:customAttributes[name eq \"hobbies\"].values","value": ["decorating"]}]}'

If successful, you should see an HTTP status of 204 No content.

Here is table to summarize what each operation does when using path urn:ietf:params:scim:schemas:extension:ibm:2.0:User:customAttributes[name eq "hobbies"].values

See API reference for modify a user for more information on updating one or more attributes for a user using the REST API.

4. Search the user record using custom attribute filters.

The Cloud Directory REST API supports filters for searching for users based on custom attribute values. Here are the most common search filters you can do using the example user record we created.

Returns records that have a value for hobbies.

curl -X GET "https://${tenant_url}/v2.0/Users?filter=urn:ietf:params:scim:schemas:extension:ibm:2.0:User:customAttributes.hobbies+pr&attributes=userName,urn:ietf:params:scim:schemas:extension:ibm:2.0:User:customAttributes" -H "Authorization: Bearer ${access_token}"

Returns records that have running as a value for hobbies.

curl -X GET "https://${tenant_url}/v2.0/Users?filter=urn:ietf:params:scim:schemas:extension:ibm:2.0:User:customAttributes.hobbies+eq+%22running%22&attributes=userName,urn:ietf:params:scim:schemas:extension:ibm:2.0:User:customAttributes" -H "Authorization: Bearer ${access_token}"

If successful, both of the above user searches will return a 200 HTTP status code and a response body in JSON containing the following.

{
  "totalResults" : 1,
  "schemas" : [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "Resources" : [
    {
      "urn:ietf:params:scim:schemas:extension:ibm:2.0:User" : {
        "customAttributes" : [
          {
            "values" : [
              "painting",
              "photography",
              "running"
            ],
            "name" : "hobbies"
          }
        ]
      },
      "id" : "608000CXT7",
      "userName" : "[email protected]"
    }
  ]
}

See API reference for get users for more information on retrieving users using the REST API.

💎

Tim Moore, IBM Security

Brad Fraley, IBM Security