Provision users and groups using SCIM

Overview

Starting with NGINX Instance Manager 2.3, you can use SCIM 2.0 (System for Cross-domain Identity Management) to provision, update, or deprovision users and user groups through an open API for managing identities.

Access SCIM APIs

NGINX Instance Manager enforces RBAC for the SCIM APIs through the USER-MANAGEMENT feature. To have full access, users must be assigned to a role with Create, Read, Update, and Delete permissions.

SCIM Endpoints

The SCIM endpoints listed below follow the specifications outlined in the SCIM Endpoints and HTTP Methods.

Available Endpoints

• /api/scim/v2/Users (POST): Adds a new IDP user.
• /api/scim/v2/Users (GET): Retrieves all IDP users. Pagination parameters are supported according to the SCIM standard, and you can filter by userName.
• /api/scim/v2/Users/{userID} (PUT): Updates an existing IDP user.
• /api/scim/v2/Users/{userID} (DELETE): Deletes an existing IDP user.
• /api/scim/v2/Groups (POST): Adds a new user group.
• /api/scim/v2/Groups (GET): Retrieves all IDP groups. Pagination parameters are supported according to the SCIM standard.
• /api/scim/v2/Groups/{groupID} (PUT): Updates an existing user group.
• /api/scim/v2/Groups/{groupID} (DELETE): Deletes an existing user group.

Request and response schemas

Requests and responses follow the schema format defined in Resource Schema Representation.

Create user

To create a user, send a POST request similar to the following example to the /api/scim/v2/Users endpoint:

Request

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "externalId": "idpuser@mydomain.ctrl",
  "userName": "idpuser@mydomain.ctrl",
  "name": {
    "formatted": "Example IDP User",
    "familyName": "Example",
    "givenName": "SSO"
  }
}

Response

{
  "emails": [
    {
      "value": "idpuser@mydomain.ctrl"
    }
  ],
  "externalId": "idpuser@mydomain.ctrl",
  "id": "dc898740-4e9c-41a4-912c-1f3a20edf66e",
  "meta": {
    "created": "2022-06-17T21:03:37.138Z",
    "lastModified": "2022-06-17T21:03:37.138Z",
    "location": "/api/scim/v2/Users/dc898740-4e9c-41a4-912c-1f3a20edf66e",
    "resourceType": "User"
  },
  "name": {
    "familyName": "Example",
    "givenName": "SSO"
  },
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "userName": "idpuser@mydomain.ctrl"
}

Create group

To create a group, send a POST request similar to the following example to the /api/scim/v2/Groups endpoint:

Request

In this request, User is assigned as a member.

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "displayName": "Example Group",
  "externalId": "7fcb12f4-af71-4f7d-a987-6c1a91cb838a",
  "members": [
    {
      "type": "User",
      "value": "dc898740-4e9c-41a4-912c-1f3a20edf66e"
    }
  ]
}

Response

{
  "displayName": "Example Group",
  "externalId": "7fcb12f4-af71-4f7d-a987-6c1a91cb838a",
  "id": "e023964d-8a63-44f8-aa85-51ffa6aaa8f1",
  "members": [
    {
      "type": "User",
      "value": "dc898740-4e9c-41a4-912c-1f3a20edf66e"
    }
  ],
  "meta": {
    "created": "2022-06-17T21:06:46.774Z",
    "lastModified": "2022-06-17T21:06:46.774Z",
    "location": "/api/scim/v2/Groups/e023964d-8a63-44f8-aa85-51ffa6aaa8f1",
    "resourceType": "Group"
  },
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ]
}

Important

After creating a group with SCIM, you need to assign roles to the group in NGINX Instance Manager so the group has permissions associated with it.

Update users created with SCIM

To update users created with SCIM, you need to use the SCIM API or update the users directly in your identity provider (IdP). You can’t use the NGINX Instance Manager web interface to edit user details from an identity provider.