Axiad Conductor SCIM Support

What is SCIM?

System for Cross-domain Identity Management (SCIM) is a standardized protocol that defines HTTP methods and endpoints used to create, retrieve, update and delete resources. Axiad's SCIM implementation follows the SCIM standards:

• RFC 7642: System for Cross-domain Identity Management: Definitions, Overview, Concepts, and Requirements

• RFC 7643: System for Cross-domain Identity Management: Core Schema

• RFC 7644: System for Cross-domain Identity Management: Protocol

Why Should I Integrate Axiad Conductor with SCIM?

Integrating Axiad Conductor with SCIM will allow users and groups to be synchronized to Axiad Conductor from an Identity Provider (IdP). Using SCIM allows for a flexible integration to send only the required data to Axiad Conductor from your IdP. 

Attributes for Axiad Conductor SCIM Integration

The sections below describe the minimum attributes required for Axiad Conductor along with optional attributes that may be needed to enable additional features of Axiad Conductor. Please work with the Axiad Customer Success team before sending optional attributes via SCIM.

Axiad Conductor implements the following SCIM endpoints:

• /Users

• /Groups

There are pre-configured SCIM connectors available in the Entra ID marketplace, ForgeRock Backstage, and Okta. By using one of these SCIM connectors, the majority of the configuration is already completed. 

Reference the following guides for more information about using SCIM connectors published by Axiad.

• Configure SCIM in Entra ID

• ForgeRock Backstage Axiad SCIM Connector

• Enable SCIM Provisioning in Okta

Before You Begin

There is a required set of user attributes that are needed for Axiad Conductor to operate. Depending on the features in your Axiad Conductor tenant, additional attributes may be required. Prior to starting SCIM configuration in your IdP, contact your Axiad Customer Success representative or our Customer Success team to discuss your organization's integration and determine appropriate data attributes.

Required Attributes for /Users

The following table describes the required user attributes, at a minimum, when creating a user in UCMS via SCIM. There are other data attributes such as "id" and "meta" that are included in the SCIM create response (but are not described below as they are part of the standard SCIM data definition).

Example: Create a User with Required Attributes

The following is an example data payload for creating a user with the required minimum attributes:

{'active': 'true',
 'emails': [{'type': 'work', 'value': 'myUser@test.zz'}],
 'externalId': '222c2996-3fe9-481f-9127-6be70f8cbb94',
 'name': {'familyName': 'Lopez', 'givenName': 'Nicholas'},
 'schemas': ['urn:ietf:params:scim:schemas:core:2.0:User',
             'urn:ietf:params:scim:schemas:extension:enterprise:2.0:User'],
 'userName': 'myUser@test.zz'}

Create user response:

<Response [201]>
{ 'active': True,
  'emails': [ { 'primary': False,
                'type': 'work',
                'value': 'myUser@test.zz'}],
  'externalId': '222c2996-3fe9-481f-9127-6be70f8cbb94',
  'id': '8b33298a-f3e9-4e89-9c4e-ab069cb35c82',
  'meta': { 'created': '2023-08-21T15:41:27Z',
            'lastModified': '2023-08-21T15:41:27Z',
            'location': 'https://ucms-testing.cloud.axiadids.net/secuera/api/v3/scim/testing/Users/8b33298a-f3e9-4e89-9c4e-ab069cb35c82',
            'resourceType': 'user'},
  'name': {'familyName': 'Lopez', 'givenName': 'Alex'},
  'schemas': [ 'urn:ietf:params:scim:schemas:core:2.0:User',
               'urn:ietf:params:scim:schemas:extension:enterprise:2.0:User'],
  'urn:ietf:params:scim:schemas:extension:enterprise:2.0:User': {},
  'userName': 'myUser@test.zz'}

Optional Attributes for /Users

The following table describes optional attributes that Axiad Conductor may be used when creating or updating a user. These additional attributes may be required depending on the features enabled in your Axiad tenant.

If your organization requires additional attributes not listed below to be mapped, work with Axiad Customer Success to ensure they are mapped appropriately.

Example: User Creation with Optional Attributes

The following is an example data payload for creating a user with the required minimum attributes and optional attributes: 

{'active': 'true',
 'addresses': [{'country': 'US',
                'formatted': '2666 Glen St\n Sometown, AK 49864',
                'type': 'work'}],
 'displayName': 'Nancy Peterson',
 'emails': [{'type': 'work', 'value': 'n.peterson@testcompany.zz'}],
 'externalId': '2a58b480-f3cc-439a-ac7c-85528a89c105',
 'name': {'familyName': 'Peterson', 'givenName': 'Nancy'},
 'phoneNumbers': [{'type': 'work', 'value': '947-175-6522'},
                  {'type': 'mobile', 'value': '271-349-8903'}],
 'schemas': ['urn:ietf:params:scim:schemas:core:2.0:User',
             'urn:ietf:params:scim:schemas:extension:enterprise:2.0:User'],
 'title': 'Health and safety adviser',
 'urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User': {'objectSid': 'S-1-5-21-186985262-1144665072-74031268-1309'},
 'urn:ietf:params:scim:schemas:extension:enterprise:2.0:User': {'costCenter': '34894',
                                                                'department': 'Department1',
                                                                'division': 'Division1',
                                                                'employeeNumber': '98724398',
                                                                'manager': '67273dc5-a217-45a7-ba0e-e1ac23910c18',
                                                                'organization': 'Org1'},
 'userName': 'n.peterson@corp.testcompany.zz'}

Create user response:

{'active': 'true',
 'addresses': [{'country': 'US',
                'formatted': '2666 Glen St\n Sometown, AK 49864',
                'type': 'work'}],
 'displayName': 'Nancy Peterson',
 'emails': [{'type': 'work', 'value': 'n.peterson@testcompany.zz'}],
 'externalId': '2a58b480-f3cc-439a-ac7c-85528a89c105',
 'name': {'familyName': 'Peterson', 'givenName': 'Nancy'},
 'phoneNumbers': [{'type': 'work', 'value': '947-175-6522'},
                  {'type': 'mobile', 'value': '271-349-8903'}],
 'schemas': ['urn:ietf:params:scim:schemas:core:2.0:User',
             'urn:ietf:params:scim:schemas:extension:enterprise:2.0:User'],
 'title': 'Health and safety adviser',
 'urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User': {'objectSid': 'S-1-5-21-186985262-1144665072-74031268-1309'},
 'urn:ietf:params:scim:schemas:extension:enterprise:2.0:User': {'costCenter': '34894',
                                                                'department': 'Department1',
                                                                'division': 'Division1',
                                                                'employeeNumber': '98724398',
                                                                'manager': '67273dc5-a217-45a7-ba0e-e1ac23910c18',
                                                                'organization': 'Org1'},
 'userName': 'n.peterson@corp.testcompany.zz'}

Required Attributes for /Groups

Synchronizing groups to Axiad Conductor enables the use of security roles, such as the Operator role, in Axiad Conductor.

The following table describes the required group attributes when creating a group in Axiad Conductor via SCIM. There are other data attributes such as id and meta that are included in the create response (but are not described below as they are part of the standard SCIM data definition).

Example: Group Creation

The following is an example data payload for creating a group:

{ 'displayName': 'architect compelling experiences',
  'externalId': '1476d9d6-421f-4d38-96e0-a6055ae5e397',
  'schemas': ['urn:ietf:params:scim:schemas:core:2.0:Group']}

Create group response:

<Response [201]>
{ 'displayName': 'architect compelling experiences',
  'externalId': '1476d9d6-421f-4d38-96e0-a6055ae5e397',
  'id': 'b8250d5f-f4e3-4e68-9b58-a6b57745f007',
  'meta': { 'created': '2023-08-22T16:09:38Z',
            'lastModified': '2023-08-22T16:09:38Z',
            'location': 'https://ucms-testing.cloud.axiadids.net/secuera/api/v3/scim/axiadintegrations/Groups/b8250d5f-f4e3-4e68-9b58-a6b57745f007',
            'resourceType': 'group'},
  'schemas': ['urn:ietf:params:scim:schemas:core:2.0:Group']}

Example: Update a Group by Adding Members

The following is an example data payload for adding members to an existing group:

{ 'Operations': [ { 'op': 'add',
                    'path': 'members',
                    'value': [ { 'value': '49c2c6ab-881f-45ec-a4a0-27abcdef4ddd'},
                               { 'value': 'b321f41a-49d8-4b81-8203-3f302ca90540'}]}],
  'schemas': ['urn:ietf:params:scim:api:messages:2.0:PatchOp']}

Create group response:

<Response [200]>
{ 'displayName': 'strategize cutting-edge schemas',
  'externalId': '1e1ad3bb-2855-4520-8d4a-88603fb36d73',
  'id': '391f78dc-c8dd-4f80-9da0-c8bdb08af348',
  'meta': { 'created': '2023-08-22T16:19:41Z',
            'lastModified': '2023-08-22T16:19:41Z',
            'location': 'https://testing.cloud.axiadids.net/secuera/api/v3/scim/axiadintegrations/Groups/391f78dc-c8dd-4f80-9da0-c8bdb08af348',
            'resourceType': 'group'},
  'schemas': ['urn:ietf:params:scim:schemas:core:2.0:Group']}

Data Mapping

If an attribute is sent by an IdP over SCIM, and the attribute is not mapped in the Axiad Conductor tenant, no errors return from Axiad Conductor to the IdP, and the unmapped information is not stored (per the SCIM standard RFC 7644, “Since the server is free to alter and/or ignore POSTed content“).

Since the data is not mapped, it is not returned to the IdP and fails validation. This may cause the IdP to queue the non-mapped data to be sent again in the next SCIM synchronization. This causes additional SCIM synchronizations until the data is mapped. 

To avoid this, contact the Axiad Customer Success team to ensure the required data fields are synchronized.