SCIM (System for Cross-Domain Identity Management) Protocol Support¶

Introduction¶

The SCIM (System for Cross-domain Identity Management) protocol is a standard designed to facilitate the synchronization and provisioning of users between different domains, in particular between an identity provider and external solutions that need this information to create their user profiles.

Zeenea implements certain services of the SCIM v2.0 protocol to enable user provisioning.

This documentation presents the specificities and limitations of the implementation of the SCIM protocol by the Zeenea platform. As this implementation is still incomplete, if you require other services or would like to share your feedback, please let us know and contact your Customer Success Manager.

In order to implement SCIM in your company, contact an administrator of your identity management platform in order to carry out the necessary configuration operations. Zeenea does not offer support for this configuration, as each platform has its own specific features, but the information provided below should make it easy to configure SCIM.

Related Resources: SCIM specifications

Permissions¶

The recommended permission scope for the SCIM API is Admin.

Authentication and Headers¶

To connect with Zeenea SCIM API, you need to generate an API key from the Zeenea Administration interface. See the following article which describes how to do this: Managing API Keys.

Each SCIM request must provide authentication information to access the service.

The authentication mode currently implemented is Bearer authentication (aka token authentication) and uses the HTTP Header "Authorization".

The token corresponds to the API key secret generated from your Zeenea instance.

Here is how to proceed:

Generate a new API key.
Use the generated secret to configure your Identity Management Platform and select the correct authentication mode: Bearer authentication (also called Token authentication).

In addition, the Content-Type parameter must be specified in request headers as follows: Content-Type: application/scim+json.

Model¶

SCIM 2.0 is built on an object model where a resource is the common denominator and all SCIM objects are derived from this resource.

SCIM defines two main types of objects: "Users" and "Groups".

Users¶

Users can be defined in SCIM using a list of attributes. The table below shows the attributes supported by Zeenea for objects of type "User":

SCIM attribute	Mapping in Zeenea
`id`	User identifier in Zeenea (UUID)
`userName`	User email
`emails`	User email
`phones`	User phone number
`familyName`	Last name of the user
`givenName`	First name of the user

Groups¶

In addition to users, SCIM includes the definition of groups. Groups are used to model the organizational structure of the resources made available. Groups can contain users or groups.

In Zeenea, SCIM groups correspond to user groups as defined in the Zeenea administration interface. Furthermore, in the current implementation, groups cannot contain other groups.

The table below shows the attributes supported by Zeenea for objects of type "Group":

SCIM attribute	Mapping in Zeenea
`id`	Identifier of the group in Zeenea (UUID)
`displayName`	Name of the group
`externalId`	Code of the group Note: You need to perform a mapping upstream of Zeenea between the group identifiers defined in your identity management tool and the codes of the Zeenea groups to fill in the `externalId` attribute.

Supported Operations¶

SCIM provides a REST API with a set of operations that allow resource manipulation.

The SCIM API URL for your tenant is

https://[instance-name].zeenea.app/api/scim/v2

where [instance_name] is to be replaced by the name of your instance.

Zeenea only supports the operations described below.

Users¶

Operations relating to users are carried out from the /Users endpoint:

https://[instance-name].zeenea.app/api/scim/v2/Users

where [instance_name] is to be replaced by the name of your instance.

Create User¶

You can create new users from a POST request using the /Users endpoint.

Constraints¶

In the Zeenea implementation of SCIM, the userName attribute is mandatory and must correspond to a valid email address.

When a user is created, no group is assigned to him, which means that he is given read access to the Explorer. Users can then be assigned to a group (as a member) via a modification request to the group (see Groups below).

Example request:¶

curl --request POST \
--location 'https://[instance_name].zeenea.app/api/scim/v2/Users'; \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/scim+json' \
--data-raw '{
"schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "userName": "testGivenName@domain.com",
    "name": {
        "givenName": "testGivenName",
        "familyName": "testFamilyName"
    }
}'

Patch User¶

You can modify a user's attributes from a PATCH request using the /Users endpoint with a user ID.

Example request:¶

    curl --request PATCH \
    --location 'https://[instance_name].zeenea.app/api/scim/v2/Users/[user_id]'; \
    --header 'Authorization: Bearer ' \
    --header 'Content-Type: application/scim+json' \
    --data-raw '{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:PatchOp"
        ],
        "Operations": [{
        "op": "replace",
        "value": {
            "name": {
                "familyName": "Doe",
                "givenName": "John"
            }
        }
        }]
    }

where [instance_name] is to be replaced by the name of your instance and [user_id] is to be replaced by the user's internal Zeenea ID.

Delete User¶

You can delete a user from a DELETE request using the /Users endpoint with a user ID.

Example request:¶

curl --request DELETE \
--location 'https://[instance_name].zeenea.app/api/scim/v2/Users/[user_id]'; \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/scim+json'

where [instance_name] is to be replaced by the name of your instance and [user_id] is to be replaced by the user's internal Zeenea ID.

Get User¶

Existing users can be retrieved by making a GET request to the /Users endpoint with a user ID.

Example request:¶

curl —-request GET \
--location 'https://[instance_name].zeenea.app/api/scim/v2/Users/[user_id]’ \
--header 'Authorization: Bearer ’ \
--header 'Content-Type: application/scim+json'

where [instance_name] is to be replaced by the name of your instance and [user_id] is to be replaced by the user's internal Zeenea ID.

List Users¶

This access point can also be used to carry out filtering requests on an existing list of users via a GET request to /Users by inserting additional filters.

Constraints¶

This request does not support pagination. In particular, the startIndex parameter is not supported. By default, 100 results are returned. A maximum of 1000 results can be returned.
The list of users can be filtered by userName, email, externalId (resolved as email in Zeenea), or displayName (resolved as firstname lastname in Zeenea).
The following comparison operators are supported: eq, co, sw, ew, and pr, as well as the expression and.
The filter query parameter must be URL encoded. Its syntax is as follows (it is expressed here before encoding)

userName co "domain.com"

Example request:¶

curl —-request GET \
--location 'https://[instance_name].zeenea.app/api/scim/v2/Users/?filter=userName%20co%20%22domain.com%22&sortBy=userName&sortOrder=ascending’ \
--header 'Authorization: Bearer ’ \
--header 'Content-Type: application/scim+json'

Groups¶

Operations relating to groups are carried out from the /Groups endpoint:

https://[instance_name].zeenea.app/api/scim/v2/Groups

where [instance_name] is to be replaced by the name of your instance.

Creating and deleting groups is not supported by the API. Use the Zeenea Administration interface to configure your groups.

Patch Group¶

Existing groups can be updated using the PATCH operation to replace specific attribute values at the /Groups endpoint.

You can use this service in particular to add or remove users from a group.

Constraints¶

The "Super Admin" group can not be modified by API.

Example request:¶

curl --request PATCH \
--location 'https://[instance_name].zeenea.app/api/scim/v2/Groups/[group_id]'; \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/scim+json' \
--data-raw '{
"schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ],
    "Operations": [{
       "op": "add",
       "path": "members",
       "value": [{
          "value": "[user_id]"
       }]
    }]
}'

where [instance_name] is to be replaced by the name of your instance, [group_id] is to be replaced by the group identifier, and [user_id] to be replaced by the user's internal Zeenea ID.

List Groups¶

This access point can also be used to carry out filtering requests on an existing list of groups by means of a GET request to /Groups, inserting additional filters.

Constraints¶

Groups can only be filtered by displayName.
Group filtering supports all comparison operators (eq, ne, co, sw, ew, ge, le, gt, lt, pr), as well as and, or, not expressions.

Example request:¶

curl —-request GET \
--location 'https://[instance_name].zeenea.app/api/scim/v2/Groups/?filter=displayName%20co%20%22[group_name]%22&sortBy=displayName&sortOrder=ascending’ \
--header 'Authorization: Bearer ’ \
--header 'Content-Type: application/scim+json'

where [instance_name] is to be replaced by the name of your instance and [group_name] is to be replaced by the name of the group.