Users and Groups SCIM 2.0 endpoints

To enable the possibility of storing users and their groups in the Application repository DirX Access implements the SCIM 2.0 API with its Groups and Users endpoints. This topic is also described in: User Data Management via SCIM 2.0 and the Application Repository Service. The endpoints implementation follows RFC 7643: System for Cross-domain Identity Management: Core Schema. The groups and users created through the SCIM API will be only stored in the DXA Application Repository and will not affect the Groups or Users in the User Repository.

In this text we use user_login_name which value is defined by the Name Resolution document.

Users endpoint

The users endpoint can be found at {scim_rest_web_application_location}/Users . Sending a GET request to this location will return list of all existing users in the Application Repository, also with their urn:net:atos:dirx:access:scim:schemas:core:2.0:Entity extension. The supported standard user attributes are {id, roles, groups}, where groups are a read only attribute and membership must be edited with the group entry. Other attributes will not be imprinted to the Application Repository.

To be able to list large number of user records, some additional configuration of the LDAP directory might be needed., as by default there is a size limit for LDAP searches. This is described in LDAP - Large search results limitations.

Groups endpoint

The groups endpoint can be found at {scim_rest_web_application_location}/Groups . Sending a GET request to this location will return list of all existing groups. The supported standard group attributes are {id,members}. Members of the group can also be other groups to support nested groups. DirX Access also supports role assignment for groups. This is done by using SCIM extension urn:net:atos:dirx:access:scim:schemas:extension:2.0:GroupRoles. The only attribute this extension supports is the roles attribute. The definition of the extension can be found at {scim_rest_web_application_location}/Schemas/urn:net:atos:dirx:access:scim:schemas:extension:2.0:GroupRoles .

Examples

Below are examples of interactions trough the SCIM 2.0 API with the Groups and Users endpoints.

Create a group with an user member, sub group and a role

POST {scim_rest_web_application_location}/Groups
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group",
    "urn:net:atos:dirx:access:scim:schemas:extension:2.0:GroupRoles"
  ],
  "members": [
    {
      "value": "{user_login_name}",
      "$ref": "{scim_rest_web_application_location}/Users/{user_login_name}"
    },
    {
         "value":"{sub_group_name}",
         "$ref":"{scim_rest_web_application_location}/Groups/{sub_group_name}"
    }
  ],
  "id": "ScimTestGroup",
  "urn:net:atos:dirx:access:scim:schemas:extension:2.0:GroupRoles": {
    "roles": [
      {
        "value": "TestRole"
      }
    ]
  }
}

Note that the member is passed with the $ref (reference URI of the target resource), this is so the server can tell what member is a user and what is a group. (The {user_login_name} will be replaced by the actual login name without the brackets.)

Add user {user_login_name} to an existing group

Modifying an entry can be done by JSON Patch, this way it is not needed to send the whole group each time.

PATCH {scim_rest_web_application_location}/Groups/ScimTestGroup
{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "add",
      "path": "members",
      "value": [
        {
          "value": "{user_login_name}",
          "$ref": "{scim_rest_web_application_location}/Users/{user_login_name}"
        }
      ]
    }
  ]
}

Remove member {user_login_name} for a group

To remove just one member without the need to pass the whole new array of members we can use Patch method like this.

PATCH {scim_rest_web_application_location}/Groups/ScimTestGroup
{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "remove",
      "path": "members[value eq \"{user_login_name}\"]"
    }
  ]
}

Create user with login name {user_login_name}

POST {scim_rest_web_application_location}/Users
{
  "schemas":[
      "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id":"{user_login_name}",
  "roles":[]
}

Replace the user {user_login_name} with PUT

PUT {scim_rest_web_application_location}/Users
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "{user_login_name}",
  "roles": [
    {
      "value": "A Role"
    }
  ]
}

Remove the user {user_login_name}

DELETE {scim_rest_web_application_location}/Users/{user_login_name}