This article provides a short guide for integrating an existing identity management system or Identity Provider (IdP), with Peakon’s SCIM 2.0 API for the purpose of automatic provisioning and updating of employee records. It does not intend to duplicate the information available in the SCIM 2.0 specification, but rather outline specific characteristics of Peakon’s SCIM 2.0 implementation. In this guide, Peakon will be referred to as the Service Provider (SP).
Enabling the Employee Provisioning integration
IT administrators can configure this by going into Administration > Integrations > Employee provisioning. Click the Connect button and you will see the options in the screenshot below.
If you use an existing IdP that supports the SCIM 2.0 protocol, such as Microsoft Azure Active Directory or Okta, no custom integration is needed and you can go ahead and simply configure the IdP for automatic provisioning to Peakon as a standard SCIM 2.0 Service Provider.
If your existing systems require a custom integration, use the SCIM URL and OAuth Bearer Token in the following sections.
The basics
The base URL for all SCIM operations is https://api.peakon.com. The API relies on Bearer Token authentication, and as such the authentication token from above should be provided in the Authorization header in the of any request to the API that requires authentication, with the value "Bearer {token}".
Supported operations
Get all users
Method: GET /Users
Requires authentication: Yes
Returns all already provisioned users in the system. This operation supports pagination as described in the SCIM specification. It also supports filtering by:
- userName
- emails
- externalId
- id (internal Peakon ID)
For additional fields, see the schema extension section below.
Get user
Method: GET /Users/{id}
Requires authentication: Yes
Returns a provisioned user by their unique identifier. The identifier in this case is the internal Peakon ID of the user returned in the response of the Create user operation.
If you wish to retrieve the user by externalId instead, consider using the Get all users operation and filter by externalId, which would have been provided when the user was first created/provisioned.
Create user
Method: POST /Users
Requires authentication: Yes
Provision a new user. Peakon requires the following fields to be provided for each new user:
- userName: The primary email of the user (max 256 characters)
- givenName: The first name of the user (max 128 characters)
- familyName: The last name of the user (max 128 characters)
The following fields are optional:
- externalId: String ID used in the external system (max 128 characters)
- active: A boolean indicating whether the user is active or disabled. Can be used for de-provisioning if a full deletion is not desired.
For additional fields, see the schema extension section below.
Update user
Method: PUT /Users/{id}
Requires authentication: Yes
Updates an existing user. Supports the same fields as the Create user operation.
Patch user
Method: PATCH /Users/{id}
Requires authentication: Yes
Makes partial updates to a user. As defined by the the SCIM 2.0 specification, the patch operation supports updating one or more specific fields of a user, through a set of of "add", "remove" or "replace" operations.
Delete user
Method: DELETE /Users/{id}
Requires authentication: Yes
Deletes the user.
Get schemas
Method: GET /Schemas
Requires authentication: Yes
Returns all schemas and fields available for a given company, including custom attributes (e.g. Manager, Date of Birth, Department etc.) set up by the company’s Peakon administrator.
Get Service Provider config
Method: GET /ServiceProviderConfig
Requires authentication: No
Returns the Service Provider configuration of the SCIM API including it's capabilities and supported features.
Enteprise schema extension
Peakon supports the enterprise user schema extension as defined in the SCIM 2.0 specification.
Peakon schema extension
In addition to the basic fields covered under “Operations” section, Peakon provides a custom schema extension to allow field data for custom attributes (e.g. Manager, Date of Birth, Department etc.). The format of this extension follows the format specified in the SCIM 2.0 specification.
The value type of the custom attributes depend of the type of attribute:
- Option type attributes (e.g. Department): A string value (max 256 characters)
- Date type attribute (e.g. Date of birth): A DateTime string (ISO 8601 format)
- Number type attribute (e.g. Salary): An Integer value
- Employee type attribute (e.g. Manager): A string value containing the email of the referenced employee. Since employee type attributes reference other employees in the system, the referenced employee needs to exist in the system beforehand. This could be achieved by a two-step provisioning, including only basic fields in the first step and extended fields in the second.
Custom attributes are provided as a sub-object of the main resource fields, e.g.
{
"name" : {
"firstName": "Jane",
"lastName": "Smith"
},
“urn:ietf:params:scim:schemas:extension:peakon:2.0:User”: {
“Business Unit”: “Engineering",
“Department”: “IT"
}
}
To retrieve the schemas that are supported for your company, including available fields, call the Get schemas endpoint described above.
Rate limiting
The Peakon SCIM API is rate limited at 25000 requests/hour. Any integration should throttle its API calls to make sure this limit is not exceeded.
External documentation
The following sections of the SCIM 2.0 specification are relevant to the above operations for anyone looking to create a custom integration with the Peakon SCIM API.
Comments
0 comments
Article is closed for comments.