Automate User Provisioning via SCIM and OAuth to RAM - Resource Access Management

This tutorial describes how to configure automatic provisioning and management of users from an external identity provider (IdP) to Resource Access Management (RAM) using the System for Cross-domain Identity Management (SCIM) 2.0 protocol. Access to the Alibaba Cloud SCIM API is secured using OAuth 2.0.

Prerequisites

An Alibaba Cloud account with administrator permissions for RAM, specifically for managing OAuth applications.

How it works

The SCIM protocol provides a standardized way to manage user identities across different systems. By using the Alibaba Cloud SCIM endpoint, you can create, query, update, and delete RAM users programmatically. This is ideal for provisioning user identities from a central IdP or HR system to Alibaba Cloud.

To ensure secure communication, all requests to the SCIM API must be authenticated with an OAuth 2.0 access token. This process uses the client credentials grant type, which is designed for machine-to-machine communication.

The configuration process involves two main steps:

Create and authorize an OAuth application: You create a special server-to-server application in RAM, which will be used to obtain an access token. For more information, see Overview of OAuth applications, Create an OAuth application, and Manage OAuth scopes.
Provision user data with the SCIM API: You use the access token to make authenticated calls to the SCIM API to manage RAM users.

Endpoints:

SCIM endpoint: https://scim.aliyun.com
OAuth token endpoint: https://oauth.aliyun.com/v1/token

Step 1: Create and authorize an OAuth application for SCIM

First, you must create a server-to-server application and grant it permission to access the SCIM API.

Log on to the RAM console.
In the left-side navigation pane, choose Integrations > OAuth.
On the Enterprise Application tab, click Create Application. In the Application Type section, select Server Application. Provide a name and click Create Application.
From the application list, click the name of your new application to open its details page.
Select the OAuth Scope tab and click Add OAuth Scope. Select the /acs/scim scope and click OK.
Select the Application Secret tab and click Create Secret. Securely copy the displayed secret value (AppSecretValue). You will need these in the next step.
Important
The application secret value is shown only once upon creation. Store it in a secure location, such as a secrets manager.

Step 2: Provision user data with the SCIM API

With the OAuth application configured, you can now use its credentials to obtain an access token and call the SCIM API.

1. Obtain an access token

Make a POST request to the OAuth token endpoint using the client credentials grant type. The Authorization header must contain the Base64-encoded string of client_id:AppSecretValue.

Example request:

curl --location --request POST --header "Authorization: Basic Y2lkOjEyMzQ1Ng==" https://oauth.aliyun.com/v1/token?grant_type=client_credentials&client_id=463790568674183****

Example response:

{
    "scope": "/acs/scim",
    "request_id": "8dc768e0-d6fe-4f52-a788-05631dd6c584",
    "access_token": "eyJ***hKg",
    "token_type": "Bearer",
    "expires_in": "3599"
}

2. Call SCIM API operations

Use the access_token from the previous step as a bearer token in the Authorization header for all subsequent requests to the SCIM endpoint.

Create a RAM user

To create a user, send a POST request to the /Users endpoint. The userName is the RAM user's logon name, and externalId links the RAM user to the user in your source system.

Example request:

curl --location --request POST 'https://scim.aliyun.com/Users' \
--header 'Authorization: Bearer  eyJ***hKg' \
--header 'Content-Type: application/json' \
--data-raw '{
    "displayName": "j2gg0s_****",
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "externalId": "6e74eec4-ddb5-4e74-bd12-5e7b99b2****",
    "userName": "j2gg0screatedbyscim_exa****"
}'

A successful response returns the newly created user object, including the server-generated RAM user id.

Example response:

{
    "displayName": "j2gg0s_****",
    "meta": {
        "created": "2020-02-14T03:58:59Z",
        "location": "https://scim.aliyun.com/Users/27648498165273****",
        "lastModified": "2020-02-14T03:58:59Z",
        "resourceType": "User"
    },
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "externalId": "6e74eec4-ddb5-4e74-bd12-5e7b99b2****",
    "id": "27648498165273****",
    "userName": "j2gg0screatedbyscim_exa****"
}

Query RAM users

You can query for users with a GET request. Alibaba Cloud supports filtering by id, userName, and externalId using the and and eq operators.

Example request (by userName):

curl --location --request GET 'https://scim.aliyun.com/Users?filter=userName%20eq%20%22j2gg0screatedbyscim****%22' \
--header 'Authorization: Bearer  eyJ***hKg'

Example response:

{
    "startIndex": 1,
    "totalResults": 1,
    "itemsPerPage": 30,
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "Resources": [
        {
            "displayName": "j2gg0screatedbyscim****",
            "meta": {
                "created": "2019-12-11T01:53:19Z",
                "location": "https://scim.aliyun.com/Users/27769827602919****",
                "lastModified": "2019-12-11T02:10:39Z",
                "resourceType": "User"
            },
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:User"
            ],
            "externalId": "6e74eec4-ddb5-4e74-bd12-5e7b99b2****",
            "id": "27769827602919****",
            "userName": "j2gg0screatedbyscim****"
        }
    ]
}

Update a RAM user

To update a user's attributes, send a PUT request to the user's specific resource URL (/Users/{id}).

Example request:

curl --location --request PUT 'https://scim.aliyun.com/Users/27648498165273****' \
--header 'Authorization: Bearer  eyJ***hKg' \
--header 'Content-Type: application/json' \
--data-raw '{
    "displayName": "j2gg0s_new_****",
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "externalId": "6e74eec4-ddb5-4e74-bd12-5e7b99b2****",
    "userName": "j2gg0screatedbyscim_new_exa****"
}'

Example response:

{
    "displayName": "j2gg0s_new_****",
    "meta": {
        "created": "2020-02-14T03:58:59Z",
        "location": "https://scim.aliyun.com/Users/27648498165273****",
        "lastModified": "2020-02-14T04:03:55Z",
        "resourceType": "User"
    },
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "externalId": "6e74eec4-ddb5-4e74-bd12-5e7b99b2****",
    "id": "27648498165273****",
    "userName": "j2gg0screatedbyscim_new_exa****"}

Delete a RAM user

To delete a user, send a DELETE request to the user's specific resource URL (/Users/{id}).

Example request:

curl --location --request DELETE 'https://scim.aliyun.com/Users/27648498165273****' \
--header 'Authorization: Bearer  eyJ***hKg' \
--header 'Content-Type: application/json'

A successful deletion returns an HTTP 204 No Content status.