Skip to main content

SCIM Overview

SCIM (System for Cross-Domain Identity Management), is an industry standard specification designed to bring consistency to the management of user identities in cloud-based applications and services.

APIs Referenced
Fenergo SCIM API

What does the Fen-X SCIM offer?​

A publicly exposed new RESTful API (compliant with the SCIM 2.0 specification) which will allow clients to manage the users in their Fen-X tenants. Clients can do this in two main ways:

  • Calling the SCIM RESTful API directly
  • Provisioning a SCIM connector/application in their Active Directory

The CRUD operations supported​

  • Create: POST: https://identity.fenergox.com/scim/users
  • Read: GET: https://identity.fenergox.com/scim/users/{id}
  • Replace: PUT: https://identity.fenergox.com/scim/users/{id}
  • Delete: DELETE : https://identity.fenergox.com/scim/users/{id}
  • Update: PATCH: https://identity.fenergox.com/scim/users/{id}
  • Search: GET: https://identity.fenergox.com/scim/users?filter={attribute}{op}{value}&sortBy={attributeName}&sortOrder={ascending|descending}
  • Bulk: POST: https://identity.fenergox.com/scim/Bulk

Separation between Authorization and Authentication​

Authentication and authorization remain two separated domains. This means that there are two steps in getting a new user working on their Fen-X tenant:

  • Create the user : (e.g. POST https://identity.fenergox.com/scim/users)
  • Assign this new user to the relevant team(s) : (e.g. PUT https://api.fenergox.com/authorizationcommand/api/team/{id}/user/{userId})

Implementation & Usage Details​

Mandatory Attributes All Operations​

A primary email address is required for all Fen-X SCIM operations

API Scopes​

The below is the list of API scopes used by the SCIM API:

  • scimapi.resource.query: needed for GET:** operations
  • scimapi.resource.add: needed for POST:** operations
  • scimapi.resource.delete: needed for DELETE:** operations
  • scimapi.resource.update: needed for PUT: and PATCH: operations
  • scimapi.resource.bulk: needed for BULK: requests*
Bulk Requests

Bulk Requests do not include the add, update or delete scopes which means that if a bulk request contains creations and deletions at the same time, those scopes should be also included in the token for the request to succeed tenant needed for handling Authentication correctly. When this scope is requested by a client-credentials client and the client contains a tenant claim and it's configured with Always Send Client Claims to active, the token will contain a tenant claim indicating the tenant intended for the operation. It's important to configure only one tenant per client to make authentication pass as we are not able to distinguish the tenant for the operation if that's not the case.

API Limits​

Groups (/groups)​

  • 500 user-members PATCH updates per request.
  • 9000 users per group.
  • 5 teams and 10 access layers.

Note: Anything outside these limits is expected to experience delays.

How to Enable SCIM​

Send a SaaS Request to get a SCIM identity client credential created for your Fen-X tenant. This client credential will contain the appropriate scopes so SCIM operations can be performed.

What do consumers need to do on their side?​

Use case 1: Calling the SCIM RESTful API directly​

  • Navigate to the swagger link
  • Request an access token using their client credentials client ID and secret
  • Make a call to the required SCIM endpoint using the token provided

Use case 2: Provisioning a SCIM connector/application in their Active Directory​

  • Fenergo have tested SCIM on a number of common identity providers including Okta and AAD.
  • Clients should refer to their Security Admin Documentation for adding a SCIM connector to their providers.
  • The Operations offered are Industry Standard.

Frequently Asked Questions (FAQ)​

If I already have a group in SCIM with users assigned to it, but no TeamIds or AccessLayerIds configured yet, will the users be added to the corresponding teams and access layers if I update the group definition to include the fenxgroup extension schema?​

Yes. Once the fenxgroup extension schema is added to the group definition, all users who belong to the group will be added to the corresponding teams and access layers.

Is there any problem if a SCIM group has only teams or only access layers, but not both?​

No. That is not a problem. In those cases, only the configured teams or access layers will be synchronized.

Can a TeamId or AccessLayerId be associated with more than one SCIM group?​

No. The relationship is one-to-one. A TeamId or AccessLayerId can be associated with only one SCIM group at a time to prevent synchronization issues.

I have set up a group in SCIM with some members, teams, and access layers, but the changes are taking a long time to synchronize in Fen-X. Is this expected?​

Yes. The process that synchronizes members in SCIM groups with the corresponding teams and access layers in Fenergo is asynchronous. As a result, the synchronization time depends on the current system load and the volume of changes being processed. For significant group updates, synchronization may take longer to complete.

I have set up a group in SCIM with some members, teams, and access layers, but after synchronization has completed, the members in the group do not match the members assigned to some teams and/or access layers​

First, make sure that the teams and access layers assigned to the SCIM group are valid and belong to the correct tenant.

If everything is configured correctly, an error may have occurred during the synchronization process that could not be recovered automatically. To rule out a transient issue, try re-synchronizing the affected members by removing and re-adding them through the SCIM API. For example, if a user is assigned to the SCIM group but not to the corresponding team in Fenergo, remove the user from the SCIM group and then add them back. This will trigger another synchronization attempt.