SCIM
Overview:
(SCIM) - The System for Cross-domain Identity Management, is common standard protocol- allows for the automation of user provisioning.
Its intent is to reduce the cost and complexity of user management operations by providing a common user schema
Easy to move users in to, out of, and around the cloud.
SCIM can be used to manage users, groups
SCIM can help ensure that users can only access authorized resources.
SCIM can be used to deactivate accounts immediately
Key Highlights of the SCIM:
SCIM API Integration: Full compliance with SCIM 2.0 specification (RFC 7644) for seamless user and group provisioning.
User Lifecycle Management: Ability to create, modify, retrieve, and delete users via SCIM API.
Group Management: Full support for group creation, modification, and group and member management.
Bulk Upload Operation: Added support for bulk user and group operations, allowing administrators to provision or update large sets of users and groups in a single API call.
PATCH Operation Support: Implemented PATCH operations for partial updates to both users and groups. Efficiently update specific attributes without needing to send the entire resource payload, improving performance and flexibility in user management.
SCIM Discovery: Skillmine Auth implements SCIM discovery endpoints, allowing client applications to retrieve metadata about supported resources.
Enhanced Security: SCIM endpoints are secured with OAuth 2.0 tokens, ensuring safe and secure communication between Skillmine Auth and identity providers.
Operations
For manipulation of resources, SCIM provides a REST API with a rich but simple set of operations, which support everything from patching a specific attribute on a specific user to doing massive bulk updates:
Create: POST https://api-base-url.com/scim/v2/{resource}
Read: GET https://api-base-url.com/scim/v2/{resource}/{id}
Replace: PUT https://api-base-url.com/scim/v2/{resource}/{id}
Delete: DELETE https://api-base-url.com/scim/v2/{resource}/{id}
Update: PATCH https://api-base-url.com/scim/v2/{resource}/{id}
Search: GET https://api-base-url.com/scim/v2/{resource}?filter={attribute}{op}{value}&sortBy={attributeName}&sortOrder={ascending|descending}
Bulk: POST https://api-base-url.com/scim/v2/Bulk
Discovery
To simplify interoperability, SCIM provides three end points to discover supported features and specific attribute details:
GET https://api-base-url.com/scim/v2/ServiceProviderConfig
Specification compliance, authentication schemes, data models.
GET https://api-base-url.com/scim/v2/ResourceTypes
An endpoint used to discover the types of resources available.
GET https://api-base-url.com/scim/v2/Schemas
Introspect resources and attribute extensions.
To create the SCIM related schema in the Skillmine Auth, refer to the link https://authdocs.skill-mine.com/licentio-documentation/settings/schemas
SCIM Flow Mapping
Navigate to Admin Side Menu > Settings > SCIM Settings.
In this section, you will map the SCIM flow for user onboarding. Select the appropriate flow that suits your requirements for user creation.
Attribute Mapping
Next, map the SCIM attributes to the corresponding Skillmine Auth attributes.
There are two resource types: User and Enterprise User.
Depending on the type of user you are creating, choose the appropriate resource type.
Ensure the correct mapping of attributes between SCIM and Skillmine Auth for proper functionality.
SCIM User Schema
The following SCIM User schema defines the structure for all user operation requests and responses.
```typescript
export interface ISCIMSchemaEntity {
schemas: string[]; // List of schemas this entity adheres to
id: string; // Unique ID of the resource
externalId: string; // External ID of the resource (optional)
userName: string; // Username for the user
name: Name; // Full name object
displayName: string; // Display name of the user
nickName?: string; // Optional nickname
profileUrl?: string; // Optional URL to the user's profile
emails: Email[]; // List of email addresses
addresses: Address[]; // List of addresses
phoneNumbers?: PhoneNumber[]; // Optional list of phone numbers
ims?: IMS[]; // Optional list of instant messaging services
photos?: Photo[]; // Optional list of photos
userType?: string; // Optional user type (e.g., regular, admin)
title?: string; // Optional job title
preferredLanguage?: string; // Optional preferred language
locale?: string; // Optional locale
timezone?: string; // Optional timezone
active: boolean; // Whether the user is active
password?: string; // Optional password field (only relevant for certain operations)
groups?: Group[]; // Optional list of groups the user is a member of
x509Certificates?: X509Certificate[]; // Optional list of certificates associated with the user
enterpriseUser?: EnterpriseUser; // Optional enterprise-specific information
meta?: Meta; // Metadata related to the resource
}
export interface Name {
formatted: string;
familyName: string;
givenName: string;
middleName?: string; // Optional field for middle name
honorificPrefix?: string; // Optional field for honorific prefix (e.g., Mr., Dr.)
honorificSuffix?: string; // Optional field for honorific suffix (e.g., Jr., Sr.)
}
export interface Email {
value: string;
type: string; // Type of email (e.g., work, personal)
primary?: boolean; // Optional field indicating if this is the primary email
}
export interface Address {
streetAddress: string;
locality: string; // Locality (city, town)
region: string; // Region (state, province)
postalCode: string;
country: string;
formatted: string; // Full address in a formatted string
type: string; // Type of address (e.g., home, work)
primary?: boolean; // Optional field indicating if this is the primary address
}
export interface PhoneNumber {
value: string;
type: string; // Type of phone number (e.g., mobile, work)
}
export interface IMS {
value: string;
type: string; // Type of Instant Messaging service (e.g., Skype, WhatsApp)
}
export interface Photo {
value: string; // URL or base64-encoded image string for the photo
type: string; // Type of photo (e.g., profile picture)
}
export interface Group {
value: string; // Group ID
$ref?: string; // Optional reference to a group
display: string; // Display name of the group
}
export interface X509Certificate {
value: string; // Base64-encoded certificate value
}
export interface Manager {
value: string; // Manager ID or reference
$ref?: string; // Optional reference to the manager
displayName: string; // Display name of the manager
}
export interface EnterpriseUser {
employeeNumber: string;
costCenter: string;
organization: string;
division: string;
department: string;
manager: Manager; // Manager details
}
export interface Meta {
resourceType: string; // Type of the resource (e.g., User, Group)
created: string; // Timestamp when the resource was created
lastModified: string; // Timestamp when the resource was last modified
version: string; // Version of the resource
location: string; // URL for the resource
}
```For all SCIM API requests, you need to include the Skillmine Auth token in the request header. For example, the header key should be 'Authorization' with the value 'Bearer <access_token>'.
Create User
curl --location --globoff '{{baseurl}}/scim/v2/Users' \
--header 'Content-Type: application/scim+json' \
--header 'Authorization: Bearer {{token}}' \
--data-raw '{
"externalId": "9890",
"emails": [
{
"type": "work",
"value": "[email protected]",
"primary": true
}
],
"name": {
"givenName": "John",
"familyName": "Doe"
},
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"userName": "[email protected]",
"password":"Giveyourpassword"
}'Read User
curl --location --globoff '{{baseurl}}/scim/v2/Users/27ddc6e5-2c3a-4711-9bb0-c0d8114ead6f' \
--header 'Authorization: Bearer {{token}}' \Update User
curl --location --globoff --request PUT '{{baseurl}}/scim/v2/Users/b494b31c-d83f-4799-92e0-b1c58b114be0' \
--header 'Content-Type: application/scim+json' \
--header 'Authorization: Bearer {{token}}' \
--data-raw '{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"externalId": "9890",
"userName": "[email protected]",
"name": {
"formatted": "Mr.K. John Doe",
"givenName": "John",
"familyName": "Doe"
"middleName": "K",
"honorificPrefix": "Mr."
},
"displayName": "John",
"nickName": "Doe",
"profileUrl": "https://login.example.com/bjensen"
}'Delete User
curl --location --globoff --request DELETE '{{baseurl}}/scim/v2/Users/b494b31c-d83f-4799-92e0-b1c58b114be0' \
--header 'Authorization: Bearer {{token}}' \Sample SCIM Error Response
{
"schemas":[
"urn:ietf:params:scim:api:messages:2.0:Error"
],
"status":"409",
"scimType":"invalidValue",
"detail":"user with given email is already exists"
}Here are the common HTTP status codes used in SCIM responses for user-related operations, along with descriptions:
1. 200 OK
Description: The request was successful, and the response body contains the representation of the requested resource (e.g., user details). This status code is typically returned for GET requests or successful PATCH/PUT updates.
Example: A successful user retrieval (GET) or update (PUT/PATCH).
2. 201 Created
Description: The resource (e.g., user) has been successfully created. This status code is typically returned for POST requests that create a new user.
Example: A new user was successfully created via a POST request.
3. 204 No Content
Description: The request was successful, but there is no content to return in the response body. This is commonly returned for DELETE requests or for operations that do not require a body in the response.
Example: A user was successfully deleted via a DELETE request.
4. 400 Bad Request
Description: The request is malformed or missing required parameters, and the server is unable to process it. This status code is returned when the request does not adhere to SCIM standards.
Example: Missing required attributes in the user creation request (e.g., missing
userNameor invalidemailformat).
5. 401 Unauthorized
Description: The request lacks valid authentication credentials. The client must authenticate itself to get the requested response.
Example: Missing or invalid
Authorizationheader (Bearer token).
6. 403 Forbidden
Description: The server understands the request, but the client does not have permission to access the resource. This is returned when the client is authenticated but does not have the necessary authorization.
Example: A user without proper admin permissions attempting to modify another user's data.
7. 404 Not Found
Description: The requested resource could not be found. This is returned when trying to retrieve or operate on a user that does not exist.
Example: Trying to retrieve a non-existing user by ID.
8. 409 Conflict
Description: The request could not be completed due to a conflict with the current state of the resource. This is typically used when trying to create a user that already exists or when there are conflicts in the data.
Example: Trying to create a user with an existing
userName.
9. 422 Unprocessable Entity
Description: The server understands the request but is unable to process it due to semantic errors. This is typically returned for validation issues, such as an invalid email format or missing required fields.
Example: A user creation request with invalid email format or missing mandatory attributes like
userName.
10. 500 Internal Server Error
Description: The server encountered an unexpected condition that prevented it from fulfilling the request. This is a generic error indicating an issue on the server side.
Example: Server error during user creation or retrieval.
11. 503 Service Unavailable
Description: The server is currently unable to handle the request due to temporary overloading or maintenance. This indicates that the service is temporarily unavailable.
Example: Temporary server issues or maintenance window for SCIM services.
Last updated