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}?ﬁlter={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": "example@domain.com",
            "primary": true
        }
    ],
    "name": {
        "givenName": "John",
        "familyName": "Doe"
    },
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "userName": "example@domain.com",
    "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": "example@domain.com",
    "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 userName or invalid email format).

5. 401 Unauthorized

Description: The request lacks valid authentication credentials. The client must authenticate itself to get the requested response.
Example: Missing or invalid Authorization header (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.

PreviousScopes NextYou don't need a user table

Last updated 8 days ago