Previously, if an administrator needed to add extra attributes into the SCIM user payload, they were generally out of luck. New LDAP, session, or fixed attributes could only be mapped to attributes that were defined in the SCIM user resource schema (defined in RFC 7643). This greatly restricted the attribute names and data types that were available for mapping.

From Verify Access 10.0.3 onwards, attribute mappings can be completely customised via Custom Schema Extensions. This blog will take you step by step how to create and populate a schema extension.

But what’s SCIM?

SCIM is a powerful standard for managing user identity information and is defined by two specifications, RFC 7643 and RFC 7644. Verify Access has supported parts of the SCIM protocol ever since ISAM 9.0.2. The schemas returned by the SCIM API implementation fall into two different categories:

• RFC schemas (User, Enterprise User, Groups, etc.)
• Verify Access schemas (MMFA, FIDO, etc.)

How do Custom Schema Extensions fit in?

The schema extension attributes won’t be added to the main body of the API payload, as those attributes are tightly defined by the schema specifications. Instead, you define your own schema, with customisable structure, types, and attribute names!

For attributes sourced from LDAP, the existing User Profile connection configuration is used to perform the LDAP operations. This includes Server Connection, Suffixes, DN and ID attributes, and Object Classes.

Prerequisite Configuration

This blog assumes that Reverse Proxy and SCIM User Profile configuration has already been completed. We will also make use of several LDAP attributes which have been added to the organizationalPerson objectclass. Feel free to use your own!

Scenario

In this scenario, there are a few attributes we’d like to add to the user payload:

A Boolean called accountLocked, mapped from LDAP attribute locked

A String called pronoun, mapped from LDAP attribute pronoun

An Object lastMFA with child attributes type and value, mapped from LDAP attributes mfaType and mfaValue

Configuration Steps

1. Navigate to the SCIM Configuration page (AAC > Manage > SCIM Configuration).
   
   
   
   
2. The configuration page has a new tab, Custom Schema Extensions. Click Custom Schema Extensions to navigate to this tab.
   
   
   
   
3. Click Add.
   
   
   
   
4. Enter details into the ID, Name, and optionally Description.
   ID: urn:extra:attributes
   Name: Extra Attributes
   Description: A schema containing extra attributes for the user object
   
   
   
   
5. Under the Attributes heading, click Add.
   
   
   
   
6. Enter Name, optionally Description, Type, Source Type, Source Attribute, Mutability, Returned, optionally Canonical Values, and check Multi-valued and Required as needed. Click OK.
   Name: accountLocked
   Description: Whether this user account is locked
   Type: Boolean
   Source Type: LDAP
   Source Attribute: locked
   Multi-valued: false
   Required: true
   Mutability: ReadWrite
   Returned: Default
   
   
   
   
7. Click Add again to add more attributes as detailed below. Fill out the attribute fields, then click OK.
   Name: pronoun
   Description: The user's preferred pronouns
   Type: String
   Source Type: LDAP
   Source Attribute: pronoun
   Multi-valued: false
   Required: false
   Mutability: ReadWrite
   Returned: Default
   
   
   
   
8. Click Add again. Fill out the attribute fields, then click OK.
   Name: lastMFA
   Description: The last MFA method used by the user.
   Type: Complex (Object)
   Source Type:
   Source Attribute:
   Multi-valued: false
   Required: false
   Mutability: ReadWrite
   Returned: Default
   
   
   
9. To add sub-attributes to a complex attribute (object), click the complex attribute in the grid.
   
   
   
   
10. Click Add.
    
    
    
    
11. Fill out the attribute fields, then click OK.
    Name: type
    Description: The type of MFA
    Type: String
    Source Type: LDAP
    Source Attribute: mfaType
    Multi-valued: false
    Required: false
    Mutability: ReadWrite
    Returned: Default
    
    
    
    
12. With the complex attribute still selected, click Add again. Fill out the attribute fields, then click OK.
    Name: value
    Description: The MFA specific value. Could be date last used or other data.
    Type: String
    Source Type: LDAP
    Source Attribute: mfaValue
    Multi-valued: false
    Required: false
    Mutability: ReadWrite
    Returned: Default
    
    
    
    
13. Click Review Pending Changes, then Deploy.
    
    

Now we can see it in action! To add or modify attributes in the new schema extension, the attributes belong in an object with the JSON key matching the schema URN. The schema URN must also be added to the schemas array.

Using your preferred API request tool, create or modify a user. Here we’ll use curl:

curl -ki --request POST 'https://www.mmfa.ibm.com/scim/Users/' \
--header 'Authorization: Basic <token>' \
--header 'Content-Type: application/json' \
--data '{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:extra:attributes"
    ],
    "userName": "jdoe",
    "name": {
        "familyName": "Doe",
        "givenName": "Jamie"
    },
    "urn:extra:attributes": {
        "accountLocked": false,
        "pronoun": "they/them",
        "lastMFA": {
            "type": "emailotp",
            "value": "2023-05-16T23:35:11Z"
        }
    }
}'

The new schema extension can be seen in the response:

HTTP/2 201
{
  "meta": {
    "location": "https://localhost/scim/Users/amRvZQ",
    "resourceType": "User"
  },
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:extra:attributes"
  ],
  "id": "amRvZQ",
  "userName": "jdoe",
  "urn:extra:attributes": {
    "accountLocked": false,
    "lastMFA": {
      "type": "emailotp",
      "value": "2023-05-16T23:35:11Z"
    },
    "pronoun": "they/them"
  },
  "name": {
    "familyName": "Doe",
    "givenName": "Jamie"
  },
  "displayName": null,
  "title": null,
  "preferredLanguage": null,
  "emails": [
    {
      "type": "work",
      "value": null,
      "primary": true
    }
  ],
  "addresses": [
    {
      "streetAddress": null,
      "formatted": null,
      "postalCode": null,
      "locality": null,
      "type": "work",
      "region": null
    },
    {
      "formatted": null,
      "type": "home"
    }
  ],
  "phoneNumbers": [
    {
      "type": "work",
      "value": null,
      "primary": true
    },
    {
      "type": "pager",
      "value": null,
      "primary": false
    },
    {
      "type": "home",
      "value": null,
      "primary": false
    },
    {
      "type": "mobile",
      "value": null,
      "primary": false
    }
  ]
}

It's as simple as that! Hopefully this new feature helps you enhance the SCIM API payloads to fit your scenarios.