Web service


From version 4.1, Identify includes an Identify*SCIM Service for provisioning users on Identify based on the specification suite developed under IETF.
Safewhere*SCIM promises to reduce the cost and complexity of user provisioning operations by providing a common users and groups schema and a REST API for all the necessary CRUD operations.

SCIM SCHEMA

The first version of Identify*SCIM supports user resource only. It follows most of the definitions on the specification, but there are some notices. The following section points out which ones do not correspond to Identify concepts and how the others map to Identify users’ attributes:

Attribute type SCIM User Attribute Identify User Attribute
Common Schema Attributes Id Id
ExternalId Primary identified name (*)
Meta created: <created date>

lastModified: <modified date>

location: "<tenantURL>/admin/scim/v1/Users/<Id>"

version: null

attributes: null

Schemas
Singular Locale,Name, NickName,PreferredLanguage, Title, TimeZone, ProfileUrl No corresponding concept
Active Enabled
Username Primary identified name (*)
DisplayName UserName
Password Empty (**)
Multi-valued attributes Entitlements, PhoneNumbers, Ims, Photos, Addresses, Roles No corresponding concept
Emails Value of email claim, which is specified on system setup
Scim enterprise user schema extension EmployeeNumber, CostCenter, Division, Department, Manager No corresponding concept
Organization Organization
Schema extensions urn:scim:schemas:extension:mapping:hint:1.0 Claim type, which is specified as a hint to extract username
urn:scim:schemas:extension:safewhere:identify:1.0.forceResetPasswordAfterFirstTimeLogin ForceResetPasswordAfterFirstTimeLogin
urn:scim:schemas:extension:safewhere:identify:1.0.ActivationCode Value of claim ActivationCode, which is defined as "DeviceActivationCodeClaimDefinitionId" on system setup
urn:scim:schemas:extension:safewhere:identify:1.0.Claims All claims of user

(*)Primary identified name: The value of the primary claim, which is used for specifying a user.

  • • There are three steps to map the SCIM user to the Identify user:
    • Map by hint: If the attribute"urn:scim:schemas:extension:mapping:hint:1.0" is not null, the system will try to use it as the primary claim type.
    • Map by combination: The SCIM user's username is a combination of its claim type and its value. The separator is defined by "ScimUserNameCombinationSeparator" on system setup.
    • Map by default: It will try to get the default username claim type, which is specified as "ScimDefaultNameClaimType" on system setup
  • There are three steps to map the Identify user to the SCIM user:
    • Try to get the claim that is primary.
    • Try to get the claim whose claim type is defined on "ScimDefaultNameClaimType".
    • Try to get the first claim whose value is not null.

(**) Password mapping: From Identify user to SCIM user, it will be empty. In contrast, it will use the SCIM user's password to update to the Identify user object.

SCIM Authentication and Authorization

Identify*Scim service uses the OAuth 2.0 token for authentication and authorization with a scope of "identify*scim".

OAuth Protocol Connection settings for SCIM:

Set the audience field of tokens that are issued for the application: fill in the token issuer URI which is set as the Entity ID at the system setup page

SCIM APIs

Web service URL: <TenantUrl>/admin/api/scim/v1/Users
Content-type: application/json
Content: Scim user json object

Commands Description Returns Exceptions Comment
GET Retrieving a known user resource by id or all users Code (200) and json object 404: Resource not found
500: Internal server error
To retrieve a specific user, append the Web service URL with "/<id>"
POST Creates a completely new resource Code (200) and the reflex scim user json object 500: Internal server error
PUT Performs a full update Code (200) and the reflex scim user json object 404: Resource not found
500: Internal server error
PATCH Performs a partial update Code (200) and the reflex scim user json object 500: Internal server error It supports deleting attributes as defined on specification. Therefore, it can be used for adding/updating or deleting claims normally.
DELETE Deletes a user or performs a partial update Code (200) 404: Resource not found
500: Internal server error
To delete a specific user, append the Web service URL with
"/<id>"
QUERY Retrieves users with specified attributes Code (200) and the reflex scim user json objects 500: Internal server error * Attributes: It can be empty or a list of scim users’ attributes separated by commas. If empty, a completed SCIM user json objects. ** Filter & paginate are not supported on Identify*Scim 1.1 yet.