Search Results :

×
Sign Up Contact Us

Contents

Drupal SCIM Server API Endpoints

This document describes the SCIM endpoints necessary to enable SCIM user provisioning and deprovisioning. SCIM is an industry standard protocol that lets you automate the user CRUD user operations. Using the module, the Drupal site will be able to act as the SCIM Server. That means any changes done on the Identity Provider (i.e. the SCIM Client) will be synced with the Drupal site.

  • Protocol Version: SCIM 2.0
  • Base Path: base_url/scim
  • Supported Resources: Users, Groups
  • Data Format: JSON
  • Authorization: Bearer token
  • Content-Type: application/json
  • Accept: application/json

The following API operations are supported

User Endpoints

Group Endpoints

    To deactivate or delete a user in Drupal, you must enable the necessary settings in the module. These options are available on the module’s configuration page.

    PATCH  /Users/{user-id}
  • Errors:
    • Error Condition HTTP Status Code
    ValidationException Either the module is not activated, or the wrong licensed key is used 400
    UnauthorizedException The authorization header is invalid or missing. 401
    ResourceNotFoundException The specified user does not exist. 404
  • Example request: 
    • PATCH /Users/{user-id} HTTP/1.1
Content-Type: application/json
Authorization: Bearer <token>

{
  "Operations": [
    {
      "op": "Replace",
      "path": "active",
      "value": false
    }
  ]
}
  • Example response - 204 No Content.
    •     {
            "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
            "id": "4",
            "userName": "username",
            "active": ,
            "emails": [{
                "primary": true,
                "value": "example@example.com",
                "type": "work",
                "display": "example@example.com"
            }],
            "meta": {
                "resourceType": "User"
            }
        }

    To fetch an existing user, make a GET request to /Users using their user ID.

    GET /Users/{user-id}
  • Errors:
    • Error Condition HTTP Status Code
    ValidationException Either the module is not activated, or the wrong licensed key is used 400
    UnauthorizedException The authorization header is invalid or missing. 401
    ResourceNotFoundException The specified user does not exist. 404
  • Example request:
    •     GET /Users/{user-id} HTTP/1.1
    Authorization: Bearer <token>
  • Example response:
    • 404 Not found.
      •     {
      "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:Error"
        ],
      "detail": "User not found",
      "status": 404
    }
    • 200 Ok found.
      • {
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "id": "4",
    "userName": "username",
    "active": 1,
    "emails": [
        {
            "primary": true,
            "value": "example@example.com",
            "type": "work",
            "display": "example@example.com"
        }
    ],
    "meta": {
        "resourceType": "User"
    }
}

    This endpoint allows you to filter and retrieve specific users from the existing user list. By making a GET request to the /Users endpoint and adding filter parameters, you can narrow down the results based on attributes such as username and email. The endpoint supports filtered searches but can return a maximum of 50 user records per request.

  • Errors:
    • Error Condition HTTP Status Code
    ValidationException Either the module is not activated, or the wrong licensed key is used 400
    UnauthorizedException The authorization header is invalid or missing. 401
    ResourceNotFoundException The specified user does not exist. 404 
    GET /Users
  • Query parameters:

    • 3.1 StartIndex and count

      It allows startIndex and count as query parameters. Where startIndex will be the starting ID, and count is the maximum number of results that the query can return.

    • Example request:
      • GET /Users?startIndex=1&count=50
Authorization: Bearer
    • Example response:
      • {
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 2,
    "startIndex": 1,
    "itemsPerPage": 2,
    "Resources": [
        {
            "id": "1",
            "externalId": "1",
            "meta": {
                "resourceType": "User"
            },
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:User"
            ],
            "userName": "example1@example.com",
            "displayName": "example1@example.com",
            "emails": {
                "value": "example1@example.com",
                "type": "work",
                "primary": true
            },
            "active": true,
            "name": {
                "familyName": "",
                "givenName": ""
            },
            "groups": [
                "authenticated,administrator"
            ],
            "department": ""
        },
        {
            "id": "13",
            "externalId": "13",
            "meta": {
                "resourceType": "User"
            },
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:User"
            ],
            "userName": "example2",
            "displayName": "example2",
            "emails": {
                "value": "example2@example.com",
                "type": "work",
                "primary": true
            },
            "active": true,
            "name": {
                "familyName": "",
                "givenName": ""
            },
            "groups": [
                "authenticated,administrator"
            ],
            "department": ""
        },           
    ]
}

    3.2 Search for a user by their username

    • Example request:
      •  GET /Users?filter=userName eq "admin"
    • Example response:
      • If the user is not found with the UserName, we send an empty schema indicating that no user was found.

        • User not found - 200 Ok.

        {
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 0,
    "startIndex": 1,
    "itemsPerPage": 0,
    "Resources": []
}

        User found - 200 Ok.

        {
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 1,
    "startIndex": 1,
    "itemsPerPage": 10,
    "Resources": [
        {
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:User"
            ],
            "id": "uid of user",
            "username": "admin",
            "emails": [
                {
                    "value": "email@gmail.com",
                    "primary": true,
                    "type": "work"
                }
            ]
        }
    ]
}

    3.3 Search the user by their email address

    • Example request:
      • GET /Users?filter=emails[type eq "work"].value eq "email@gmail.com"
Authorization: Bearer <token>
    • Example response:
      • If the user presents with the email.

        • User found - 200 Ok.

        {
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 1,
    "startIndex": 1,
    "itemsPerPage": 10,
    "Resources": [
        {
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:User"
            ],
            "id": "uid of user",
            "username": "Username",
            "emails": [
                {
                    "value": "email@gmail.com",
                    "primary": true,
                    "type": "work"
                }
            ]
        }
    ]
}
      • If the user is not found by the email, the module sends an empty schema indicating that the user was not found.

        • User not found - 200 Ok.

        {
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 0,
    "startIndex": 1,
    "itemsPerPage": 0,
    "Resources": []
}

If the user is found in the GET request, a PATCH or PUT request will be made to update the user; otherwise, a POST request will be made to create the user. You can update specific fields of a user using a PATCH request to the /Users endpoint. In the request body, include the attribute you want to change and its updated value. 

PATCH  /Users/{user-id}
  • Errors:
    • Error Condition HTTP Status Code
    ValidationException Either the module is not activated, or the wrong licensed key is used 400
    UnauthorizedException The authorization header is invalid or missing. 401
    ResourceNotFoundException The specified user does not exist. 404
  • Example request:
    • PATCH/Users/{{user-id}} HTTP/1.1
Content-Type: application/json
Authorization: Bearer <token>

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
            {
            "op": "Replace",
            "path": "emails[type eq \"work\"].value",
            "value": "email@gmail.com"
            },
            {
            "op": "Replace",
            "path": "name.familyName",
            "value": "familyname"
            }
    ]
}
  • Example response: 200 OK.
    • {
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "id": "uid of user",
    "userName": "Username",
    "active": 1,
    "emails": [
        {
            "primary": true,
            "value": "email@gmail.com",
            "type": "work",
            "display": "email@gmail.com"
        }
    ],
    "meta": {
        "resourceType": "User"
    }
}

You can update a user using a PUT request to the /Users endpoint. This request replaces the entire user object, so all required user attributes must be provided in the body.

PUT  /Users/{{user-id}}
  • Errors:
    • Error Condition HTTP Status Code
    ValidationException Either the module is not activated, or the wrong licensed key is used 400
    UnauthorizedException The authorization header is invalid or missing. 401
    ResourceNotFoundException The specified user does not exist. 404
  • Example request:
    • PUT/Users/{{user-id}} HTTP/1.1
Content-Type: application/json
Authorization: Bearer <token>

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "id": "97",
    "userName": "exmple",
    "active": 1,
    "emails": [
        {
            "primary": true,
            "value": "exmple@example.com",
            "type": "work",
            "display": "exmple@example.com"
        }
    ],
    "meta": {
        "resourceType": "User"
    },
    "name": {
        "givenName": "givenName",
        "familyName": "familyName",
        "middleName": "sdf",
        "honorificPrefix": "sdf"
    },
    "displayName": "givenName familyName",
    "nickName": "df",
    "addresses": [
        {
            "primary": true,
            "locality": "fdd"
        }
    ],
    "locale": "en-US",
    "externalId": "9rqltOOLI95d7",
    "groups": []
}
  • Example response: 200 ok.
    • {
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "id": "97",
    "userName": "example",
    "active": 1,
    "emails": [
        {
            "primary": true,
            "value": "example@example.com",
            "type": "work",
            "display": "example@example.com"
        }
    ],
    "meta": {
        "resourceType": "User"
    }
}

6. Create User (POST)

Use a POST request on the /Users endpoint to create a new user. Make sure to include all necessary fields in the request body. A successful request returns 201 Created and the user details.

POST  /Users
  • Errors:
    • Error Condition HTTP Status Code
    ValidationException Either the module is not activated, or the wrong licensed key is used 400
    UnauthorizedException The authorization header is invalid or missing. 401
    ConflictException User already exists. 409
  • Example request:
    • POST /Users HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <token>

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],
    "externalId": "abc",
    "userName": "example",
    "active": true,
    "emails": [{
        "primary": true,
        "type": "work",
        "value": "example@example.com"
    }],
    "meta": {
        "resourceType": "User"
    },
    "name": {
        "formatted": "first name last name",
        "familyName": "last name",
        "givenName": "first name"
    }
}
  • Example response: 201 created.
    • {
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
    ],
    "externalId": "abc",
    "userName": "example",
    "active": true,
    "emails": [
        {
            "primary": true,
            "type": "work",
            "value": "example@example.com"
        }
    ],
    "meta": {
        "resourceType": "User"
    },
    "name": {
        "formatted": "first name last name",
        "familyName": "last name",
        "givenName": "first name"
    },
    "id": "98"
}

The /Groups endpoint supports GET requests to retrieve a list of groups available on the SCIM server. This operation returns only the basic group information, such as the group ID and display name. The member list is always returned as empty, as the endpoint does not include group membership details in the response.

  • Example request:
    • GET /Groups HTTP/1.1
Authorization: Bearer <token>
  • Example response - 200 ok
    • {
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 4,
    "Resources": [
        {
            "id": "anonymous",
            "meta": {
                "resourceType": "Group"
            },
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:Group"
            ],
            "displayName": "anonymous"
        },
        {
            "id": "authenticated",
            "meta": {
                "resourceType": "Group"
            },
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:Group"
            ],
            "displayName": "authenticated"
        },
        {
            "id": "administrator",
            "meta": {
                "resourceType": "Group"
            },
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:Group"
            ],
            "displayName": "administrator"
        },
        {
            "id": "editor_admin",
            "meta": {
                "resourceType": "Group"
            },
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:Group"
            ],
            "displayName": "editor_admin"
        }
    ],
    "startIndex": 1,
    "itemsPerPage": 4 
}
  • Supported filter:
    • GET /Groups?filter=displayName eq "administrator"
  • Example request:
    • GET /scim/Groups?filter=displayName eq "administrator"  HTTP/1.1
Authorization: Bearer <token>
  • Example response: 200 ok.

    • If a group is found with the display name.

    {
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 0,
    "Resources": [],
    "startIndex": 1,
    "itemsPerPage": 20
}

/Groups/{id} retrieves the group resource associated with the provided group ID. Only the group's metadata is returned in the response. Membership details are not included.

  • Example request:
    • GET /Groups/administrator HTTP/1.1
Authorization: Bearer <token>
  • Example response:

      • Found - 200 OK.

      {
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
    ],
    "id": "administrator",
    "meta": {
        "resourceType": "Group"
    },
    "displayName": "Administrator"
}

      Not found - 404.

      {
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:Error"
    ],
    "detail": "Group administrator not found",
    "status": 404
}

Use a POST request to /Groups to create a new group. You need to provide a group name (displayName). Although you can include members in the request body, the response will always return an empty list of members.

  • Errors:
    • Error Condition HTTP Status Code
    ValidationException Either the module is not activated, or the wrong licensed key is used 400
    UnauthorizedException The authorization header is invalid or missing. 401
    OperationNotSupportedException Group modification is not allowed 501
  • Example request:
    • Request without a member list included.
      • POST /Groups HTTP/1.1
Authorization: Bearer <token>

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
    "externalId": "enternal-id",
    "displayName": "group2",
    "meta": {
        "resourceType": "Group"
    }
}
    • Request with member list.
      • POST /Groups HTTP/1.1
Content-Type: application/json
Authorization: Bearer <token>
{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
    ],
    "displayName": "group1",
    "members": [
        {
            "value": "3",
            "display": "admin@gmail.com"
        },
        {
            "value": "2",
            "display": "admin2@gmail.com"
        }
    ]
}
  • Response: 201 Created.
    • {
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
    ],
    "externalId": "enternal-id",
    "displayName": "group2",
    "meta": {
        "resourceType": "Group"
    },
    "members": [],
    "id": "group2"
}

You can update a group’s basic details, like the display name, using a PATCH request to /Groups/{group-id}. This request updates only the attributes you provide and does not change the group’s members. A successful update returns 204 No Content.

  • Example request:
    • PATCH /Groups/group1 HTTP/1.1
Authorization: Bearer 

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [{
        "op": "Replace",
        "path": "displayName",
        "value": "updated group1"
    }]
}
  • Example response - 204 No Content.

The /Groups/{id} endpoint supports add and remove members through a PATCH request. The request body must include the list of user IDs you want to add. This action only updates the group’s members and returns 204 No Content when successful.

  • Example request:
    • Add a member to the group.
      • PATCH /Groups/updated group1 HTTP/1.1
Content-Type: application/json
Authorization: Bearer <token>

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [{
        "op": "Add",
        "path": "members",
        "value": [{
            "$ref": null,
            "value": "97"
        }]
    }]
}
    • Remove the member from the group.
      • PATCH /Groups/updated group1 HTTP/1.1
Authorization: Bearer <token>

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [{
        "op": "Remove",
        "path": "members",
        "value": [{
            "$ref": null,
            "value": "97"
        }]
    }]
}
  • Example response- 204 No Content.

The /Groups/{id} endpoint supports deleting a group using a DELETE request. This operation removes the group from the SCIM server. A successful deletion returns a 204 No Content response, indicating that the group was deleted, and no response body is provided.

  • Example request:
    • DELETE /Groups/updated group1 HTTP/1.1
Authorization: Bearer <token>
  • Example response - 204 No Content.

If the configuration was not successful, please contact us at drupalsupport@xecurify.com. Please send the screenshot of the error window, and we will assist you in resolving the issue and guiding you through the setup.

ADFS_sso ×
Hello there!

Need Help? We are right here!

support