CIAM API overview-Identity as a Service(IDaaS)-阿里云帮助中心

This document is for developers integrating CIAM using its RESTful APIs. The APIs are categorized as authentication operations, management operations, and user operations.

1. API endpoint

The API endpoint uses the following format:

https://xxxx.api.aliyunidaas.com

Go to the IDaaS console and navigate to IDaaS > CIAM. On the page that appears, find the instance and get the value of Instance Open API Domain Name.

2. API categories

CIAM provides a rich set of APIs that are categorized as authentication operations, management operations, and user operations.

API type	Caller	Operations	Limitations	Protected by
authentication operations	business system server	account password logon, SMS logon, social media registration, SMS registration, password recovery	The APPLICATION_API scope must be granted.	application access token
management operations	business system server	account lifecycle management, log off, view user details, and more	The MANAGEMENT_APPLICATION_API scope must be granted.	application access token
user operations	business system server	Modify phone number, modify email address, query personal information, link third-party social accounts, and log off	Can be used after the end user logs on.	user access token

3. API flows

In CIAM, we use an fId to identify an entire flow. A complete flow, such as account password logon -> two-factor authentication -> complete profile -> successful logon, is considered fully executed only after an authorization code or token is returned.

The logon or registration flow varies based on your application settings in the CIAM console. For example, you can configure a flow to require MFA after an account password logon, or prompt the user to complete their profile information, such as their name, phone number, and email address, or change their password.

The fId parameter links the entire logon flow. The flowType parameter in the data object indicates whether a subsequent step is required after the current one is complete. For example, if MFA is required after an account password logon, the API returns the following response.

{
    "success": true,
    "code": "Operation.Success",
    "message": "Operation.Success",
    "requestId": "165840546xxxxxxxx$8a183b2c-8b93-834a-4e1e-378db7b925da",
    "data": {
        "fId": "202207212010534049551317948753920_X_BCD",
        "flowType": "NEED_TWO_FACTOR",
        "additional": {
            "phoneNumber": "159xxxx4245"
            "email": "xxxx@mail.com"
        }
    }
}

The additional field is optional and contains data that may be required for the next step. For example, if the MFA page needs to display the phone number, the data is returned in the previous step. You must check the flowType value and call the corresponding API to proceed to the next step.

Every step corresponds to a flow type and a flow identifier. The flow identifier is fId, and the flow type is flowType. When an API involves a step, the API response always contains the corresponding flowType. You must use the flowType to execute the next step, and the flowType reference table is as follows:

FlowType value	Use case	Description
NEED_TWO_FACTOR	Logon authentication	MFA is required.
NEED_UPDATE_PASSWORD		Password update is required.
NEED_BIND_SOCIAL_ACCOUNT		Social account linking is required.
NEED_BIND_PHONE_NUMBER		Phone number linking is required.
NEED_BIND_EMAIL		Email address linking is required.
NEED_SET_USERNAME		Username setup is required.
NEED_LOGIN_OR_REGISTOR		Logon or registration is required.
NEED_COMPLETE_ACCOUNT_ATTR		Account attribute completion is required.
NEED_COMPLETE_EXTENSION_ATTR		Extension attribute completion is required.
USER_TWO_FACTOR_AUTH	user operations	MFA for critical operations is required.
USER_UPDATE_DEVICE		The user must update their device information.
USER_UPDATE_EMAIL		The user must update their email address.
USER_UPDATE_PWD		The user must update their password.
USER_UPDATE_PHONE		The user must update their phone number.
USER_UPDATE_SOCIAL		The user must update their third-party account information.
USER_UNSUBSCRIBE		The user must unsubscribe.

4. SSO flow

CIAM implements single sign-on (SSO) using the standard authorization code flow.

Your business system redirects the user to the CIAM authentication address. You can include redirectUrl and state as parameters. After the user authenticates with CIAM, CIAM calls back to your business system to complete the SSO flow. The state parameter is passed through without being processed.

Request example

https://xxxx.aliyun.com?code=xxxx&state=xxxx

Response example

Your business system is responsible for redirecting the user based on the redirectUrl in the data object.

{
    "success": true,
    "code": "Operation.Success",
    "message": "Operation.Success",
    "requestId": "165778288****$bebbd27b-e9c3-db44-b06f-adbc5ef0****",
    "data": {
        "redirectUrl": "https://xxxx.aliyun.com?code=xxxx&state=xxxx"
    }
}

5. Key concepts

Term	Description
OAuth 2.0	A standard authorization protocol that lets applications access user information on other websites without sharing passwords. OAuth 2.0 provides specific authorization flows for web applications, desktop applications, mobile phones, and smart devices, and is more secure than OAuth 1.0.
OIDC	OpenID Connect is a simple identity layer on top of the OAuth 2.0 protocol. It allows clients to verify the identity of the end user based on the authentication performed by an authorization server and to obtain basic profile information about the end user in an interoperable and REST-like manner. OpenID Connect supports various clients, including web-based, mobile, and JavaScript clients.
authorization code (`code`)	A temporary, single-use credential with a short validity period that is used to enter different systems. This corresponds to the authorization code in the OAuth 2.0 protocol.
single sign-on (SSO)	SSO allows a user to log in once to access all authorized applications. Historically, SSO has been implemented in various ways as applications have evolved. In the context of IDaaS, SSO refers specifically to identity federation mechanisms based on standard protocols such as SAML and OIDC.
ID token (`id_token`)	An ID token contains information about the logged-on account, which you obtain by parsing the token.
access token (`access_token`)	Use an access token to call APIs provided by CIAM.
refresh token (`refresh_token`)	Use a refresh token to obtain a new access token when the current one expires.
idaasAppId	The unique identifier of an application in IDaaS. You can find this ID in the application list in the IDaaS console.
enterpriseAuthId	The unique identifier of an authentication source in IDaaS. You can find this ID in the authentication source list in the IDaaS console.
multi-factor authentication (MFA) / two-factor authentication (2FA)	MFA requires users to provide multiple authentication factors to verify their identity. It is often used to enhance the security of password-based logon. IDaaS supports MFA for password authentication using SMS, email, or one-time passwords (OTP).
authentication source	An IDaaS concept that corresponds to social and security authentication providers. Administrators can configure connection details for an authentication source to enable integration, allowing users to log on to the platform using credentials from that provider.

6. Scopes

In the OAuth 2.0 protocol, the scope parameter limits an application's access to a user's account. A protected resource can perform different operations and return different information based on the scope. To pass multiple scopes, separate them with spaces, such as openid profile phone.

In the OIDC protocol, scope can also control the claims in the ID token or the content returned from the userinfo endpoint. For example, if you pass the phone scope during authorization, the user information will include phone_number and phone_number_verified.

CIAM uses two types of scopes: protocol-based scopes from OIDC and OAuth 2.0 (lowercase names) and CIAM API permission scopes (uppercase names).

The following table lists the scopes supported by CIAM.

Scope name	Permissions	Description	Granting method
APPLICATION_API	Read	Grants access to application-level APIs.	Granted to new applications by default. Can be dynamically configured in the permission settings of the application.
MANAGEMENT_APPLICATION_API	Read/Write	Grants access to administrator-level APIs.	You can only configure this in the application's permission settings.
USER_API	Read/Write	Grants access to user-level APIs.	Cannot be dynamically configured. This permission is granted to applications by default.
openid	Read	An OIDC scope. The token endpoint returns an `id_token` only when this scope is present.
profile	Read	Grants permission to read the user's default attributes, such as `name`, `nickname`, and `gender`.
email	Read	Authorizes access to the user's email address and returns `email` and `email_verified`.
phone	Read	Authorization to read the user's mobile phone number returns `phone_number` and `phone_number_verified`.

Note

After a user completes logon authentication, the token endpoint returns tokens (access_token, refresh_token, and id_token). The access_token is granted the USER_API scope by default, which allows it to call user-level APIs. When the access_token expires, the client can use the refresh_token to obtain a new one. When doing so, you must explicitly include USER_API in the scope parameter. This ensures the new access_token can continue to access user-level APIs.

7. Response type

In the OAuth 2.0 protocol, response_type specifies the required authorization flow and determines which parameters CIAM returns. The OAuth 2.0 protocol defines the following values for response_type:

Response type	Description
code	Specifies the authorization code flow, which returns an authorization code after successful authentication.
token	Specifies the implicit grant, which returns token information after successful authentication.

Note

In user registration and logon scenarios, if the response_type parameter is not within the range defined by the OAuth 2.0 protocol, CIAM defaults to token.