Synchronize accounts from the internal system of an enterprise to RAM based on SCIM - Resource Access Management

To reduce maintenance and management costs, enterprises can synchronize existing accounts in their internal systems to the cloud based on a set of rules. Alibaba Cloud can synchronize user information from internal systems of enterprises to Resource Access Management (RAM) based on System for Cross-domain Identity Management (SCIM) and security authorization of Open Authorization (OAuth) applications.

Prerequisites

We recommend that you perform operations in the RAM console by using a RAM user who has administrative rights or has the OAuth management permissions.

Background information

SCIM is a protocol that is used to manage user identities in cloud-based applications and services. SCIM 2.0 is built on top of an object model in which a resource is the common denominator and all SCIM objects are derived from the resource. The resource contains the id, externalId, and meta attributes. RFC 7643 defines User, Group, and EnterpriseUser that are extended common attributes. In this topic, the User attribute is used to synchronize user information. For more information about RFC 7643, see RFC 7643.
OAuth defines a secure, open, and simple standard for authorization of user resources. Third parties can obtain the authorization information about a user without the need to obtain the username and password of the user. OAuth supports the following application types: WebApp, NativeApp, and ServerApp. WebApp and NativeApp use 3-legged OAuth. ServerApp uses 2-legged OAuth. SCIM uses 2-legged OAuth to complete authorization between an application (consumer) and an API (service provider). Then, the application can call the API to synchronize data. For more information about OAuth, see OAuth 2.0 and Overview.
Alibaba Cloud SCIM endpoint: https://scim.aliyun.com.
The endpoint that is used to obtain an access token (access_token) by using OAuth: https://oauth.aliyun.com/v1/token.

Step 1: Create and authorize an OAuth application

Log on to the RAM console with an Alibaba Cloud account.
In the left-side navigation pane, click OAuth Preview.
On the Enterprise Applications tab, click Create Application to create an OAuth application.
In the panel that appears, set Application Type to ServerApp. For more information, see Create an application.
Click the name of the application. On the Application OAuth Scopes tab, click Add OAuth Scopes to add a scope.
In the panel that appears, select /acs/scim in the Select OAuth Scopes section. For more information, see Add OAuth scopes.
Authorize the OAuth application.
1. On the Application OAuth Scopes tab, click Authorize.
2. On the Third-party Application Authorization page, select Accesses Cross-Domain Identity Management and click Authorize.
On the App Secrets tab, click Create Secret to create an application secret.
Important
- An application secret (client_secret) is displayed only during creation. We recommend that you save the secret for subsequent use.
- AppSecretId is the ID of the application secret. AppSecretId is not the application secret (client_secret).

Step 2: Synchronize account data

You can use a client or SCIM API to synchronize account data. For example, you can use One Identity as a client.

You can configure SCIM information in One Identity and then synchronize account data by using One Identity. For more information about how to configure One Identity, see One Identity User Guide.
You can also use SCIM API to map accounts in the internal system of your enterprise to RAM users. Then, you can create, delete, query, or modify the fields of the RAM users. You can create, delete, query, or modify the following fields of a RAM user:
- id: the ID of the RAM user, which is globally unique and generated by the server.
- externalId: the foreign key of the RAM user, which is unique at the user level and is specified by the client. The key is used to associate the RAM user with the user in the internal system of your enterprise.
  Note
  If you create a RAM user in the RAM console, the RAM user does not have the externalId field.
- userName: the username of the RAM user, which is unique at the user level and is specified by the client.
- displayName: the display name of the RAM user, which is specified by the client.

You can perform the following steps to synchronize account data by using SCIM API.

Obtain the ID (client_id) and secret (client_secret) of the authorized server application.
- client_id: the ID of the application. You can obtain the ID from Step 1: Create and authorize an OAuth application.
- client_secret: the secret of the application. You can obtain the secret from Step 1: Create and authorize an OAuth application.
Access https://oauth.aliyun.com/v1/token by using client_id and client_secret to obtain access_token.
When you send an API request, specify the Authorization header in the "Authorization: Basic Base64Encode(client_id:client_secret)" format. For example, if client_id is cid and client_secret is 123456, specify the Authorization header as "Authorization: Basic Y2lkOjEyMzQ1Ng==".
Sample request
```
curl --location --request POST --header "Authorization: Basic Y2lkOjEyMzQ1Ng==" https://oauth.aliyun.com/v1/token?grant_type=client_credentials&client_id=463790568674183****
```
Sample response
```
{
    "scope": "/acs/scim",
    "request_id": "8dc768e0-d6fe-4f52-a788-05631dd6c584",
    "access_token": "eyJ***hKg",
    "token_type": "Bearer",
    "expires_in": "3599"
}
```
Query ResourceType and Schema that are supported by SCIM.
The following sample code is used to query ResourceType:
```
curl --location --request GET 'https://scim.aliyun.com/ResourceTypes'
```
The following sample code is used to query Schema:
```
curl --location --request GET 'https://scim.aliyun.com/Schemas'
```

Create, query, delete, or modify the fields of a RAM user.

Create a RAM user.

Specify a username (userName), display name (displayName), and foreign key (externalId) based on the account data in the internal system of your enterprise. Then, create the RAM user.

Sample 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****"
}'

Sample 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 a RAM user.

Use GET /Users/{id} to query a RAM user by id.
Use GET /Users?filter=externalId eq xxx to query a RAM user by externalId.

Use GET /Users?filter=userName eq xxx to query a RAM user by userName.

Sample request

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

Sample 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****"
        }
    ]
}

Note

SCIM supports only the and and eq filters for querying users by id, userName, and externalId.

Modify the fields of a RAM user.

Sample 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****"
}'

Sample 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.
Sample request
```
curl --location --request DELETE 'https://scim.aliyun.com/Users/27648498165273****' \
--header 'Authorization: Bearer  eyJ***hKg' \
--header 'Content-Type: application/json'
```
If the HTTP status code 204 is returned, the RAM user is deleted.
Note
Alibaba Cloud does not support soft deletion. If the internal system of your enterprise supports soft deletion, we recommend that you map soft deletion to hard deletion before you synchronize accounts to Alibaba Cloud.