此 API 文檔專為希望使用 RESTful API 方式整合 CIAM 的使用者而設計，介面分為認證介面、管理介面、使用者介面。
1. API 地址
API地址的格式如下：
https://xxxx.api.aliyunidaas.com請前往IDaaS控制台，找到中對應執行個體的執行個體開放介面網域名稱。
2. API 介面分類
CIAM 產品提供了豐富的 API 介面能力，可分為認證介面、管理介面、使用者介面。
API 類型 | 調用方 | 用途範圍 | 使用限制 | 鑒權 |
認證介面 | 業務系統服務端 | 賬密登入、簡訊登入、社交媒體登入、社交媒體註冊、簡訊註冊、密碼找回。 | 必須授權 APPLICATION_API scope | 受應用的 accessToken 保護 |
管理介面 | 業務系統服務端 | 帳號生命週期管理、登出、查看使用者詳情等。 | 必須授權 MANAGEMENT_APPLICATION_API scope | 受應用的 accessToken 保護 |
使用者介面 | 業務系統服務端 | 修改手機、修改郵箱、查詢個人資訊、綁定三方社交帳號、登出帳號 | 終端使用者登入後可以使用 | 受使用者的 accessToken 保護 |
3. API 商務程序
在 CIAM 中，我們以 fId 標記整個流程，在一個完整的流程中（如賬密登入->二次認證->完善資訊->登入成功），只有返回授權 code 或者 token 後才標誌著這個流程完整執行。
根據CIAM控制台中針對應用配置不同，在整個的登入或者註冊流程也會有所不同，比如賬密登入後是否需要二次認證，是否需要完善個人資訊（名稱，手機號，郵箱，修改密碼）等。
基於fId串聯整個登入流程，當前處理完下一步是否需要有子流程，由data下的flowType統一標識。如賬密登入完需要二次認證，返回結果如下。
{
"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"
}
}
}additional為下個流程可能需要用到的資料，非必須。如二次認證頁面需要回顯手機號，則在上一步流程返回對應的內容（具體業務細講）。開發人員需要根據 flowType 執行下一步的流程，調用相關 API。
所有的子流程都對應一個流程類型和流程標識，流程標識即 fId，流程類型則是 flowType。當 API 介面存在子流程時，介面響應值中一定包含對應的 flowType，開發人員需要根據 flowType 執行下一步的子流程，flowType的參照表如下：
FlowType 流程類型 | 使用範圍 | 描述 |
NEED_TWO_FACTOR | 登入認證 | 需要進行二次認證 |
NEED_UPDATE_PASSWORD | 需要修改密碼 | |
NEED_BIND_SOCIAL_ACCOUNT | 需要綁定社交帳號 | |
NEED_BIND_PHONE_NUMBER | 需要綁定手機號 | |
NEED_BIND_EMAIL | 需要綁定郵箱 | |
NEED_SET_USERNAME | 需要設定使用者名稱 | |
NEED_LOGIN_OR_REGISTOR | 需要登入或者註冊 | |
NEED_COMPLETE_ACCOUNT_ATTR | 需要補充帳號屬性 | |
NEED_COMPLETE_EXTENSION_ATTR | 需要補充擴充屬性 | |
USER_TWO_FACTOR_AUTH | 使用者操作 | 關鍵操作的二次認證 |
USER_UPDATE_DEVICE | 使用者更新裝置資訊 | |
USER_UPDATE_EMAIL | 使用者修改郵箱 | |
USER_UPDATE_PWD | 使用者修改密碼 | |
USER_UPDATE_PHONE | 使用者修改手機號 | |
USER_UPDATE_SOCIAL | 使用者修改第三方帳號 | |
USER_UNSUBSCRIBE | 賬戶登出 |
4. SSO 流程
CIAM 系統中，基於標準的code模式實現 SSO 功能。
業務系統引導使用者跳轉至CIAM認證地址（可附帶 redirectUrl 、state），在CIAM認證結束後，回調業務系統實現SSO（state不會被處理）。
請求樣本
https://xxxx.aliyun.com?code=xxxx&state=xxxx返回樣本
業務端根據 data 中 redirectUrl 自行實現跳轉。
{
"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.名詞術語
名稱 | 描述 |
OAuth 2.0 | OAuth 是一套標準化的授權協議，通常用於互連網使用者授予網站或應用程式訪問其在其他網站上的資訊的許可權，但不提供密碼。OAuth2.0 為 Web 應用程式、傳統型應用程式、行動電話和智慧型裝置提供了特定的授權流，安全性方面要比 OAuth1.0 更優秀。 |
OIDC | OpenID Connect 是在 OAuth2.0 協議之上的一個簡單的身份層。它允許用戶端基於授權伺服器執行的身分識別驗證來驗證終端使用者的身份，並以可互操作和類似於 REST 的方式擷取有關終端使用者的基本設定檔資訊。OpenID Connect 允許各種各樣的用戶端，包括基於 Web 的用戶端、移動用戶端和 JavaScript 用戶端。 |
code（授權碼） | 進入不同系統的臨時票據，一次性且很短時間內有效。對應 OAuth 協議中的授權碼 |
單點登入（SSO） | Single Sign-On。指使用者僅需一次登入，即可訪問全部應用的實現，在歷史中根據應用變化，SSO 也有多種實現形態。在 IDaaS 的語境中，我們只把基於 SAML、OIDC 等標準協議的身份聯邦機制，稱為單點登入。 |
id_token | id_token 是身份令牌，可通過解析 id_token 內容，擷取當前已登入賬戶資訊。 |
access_token | 授權令牌，用於調用 CIAM 提供的介面。 |
refresh_token | 重新整理權杖，在 access_token 令牌到期後，可以使用 refresh_token 擷取新令牌。 |
idaasAppId | IDaaS 應用的唯一標識，在 IDaaS 控制台應用列表中可以擷取。 |
enterpriseAuthId | IDaaS 認證源的唯一標識，在 IDaaS 控制台認證源列表中可以擷取。 |
二次認證（MFA/2FA） | Multi-Factor Authentication 多因素認證、Two-Factor Authentication 雙因素/二次認證，指在登入時需要提供多種身份認證因子，交叉確認訪問者身份。由於密碼天然的安全弱點，通常用於加強帳號+密碼登入方式。IDaaS 中支援對賬密認證開啟簡訊、郵件或動態令牌（OTP）二次認證。 |
認證源 | IDaaS 以認證源來對應社交認證源、安全認證源，管理員只需要配置相應的認證源串連配置資訊，即可完成與各種認證源的對接，並使用這些認證源的原有帳號密碼或掃碼等方式進行登入平台。 |
6、Scope 定義
在 OAuth 2.0 協議中，scope 表示使用者授權的存取權杖可以訪問到的受保護資源的範圍，受保護的資源可以根據請求提供的存取權杖對應的 scope 範圍值和其他參數執行不同的操作並返回不同的資訊。當需要傳遞多個 scope 時以空格方式分隔，比如 openid profile phone。
在 OIDC 協議中，scope 還可以用來控制 id_token 的 claims 屬性或者 userinfo endpoint 的返回內容，比如授權時傳遞了 phonescope，則使用者資訊中將會返回 phone_number和phone_number_verified。
在 CIAM 中，scope 分為兩種，一種是基於 OIDC 和 OAuth 2.0 協議中的 scope（以小寫英文字元命名），另外一種是針對 CIAM API（資源）存取權限的 scope（以大寫英文字元命名）。
CIAM 目前支援並對外提供的 scope 列表如下：
scope名稱 | 授權 | 說明 | 授予方式 |
APPLICATION_API | 讀 | 授權訪問應用層級的介面 | 新應用預設授予，允許在應用詳情-使用權限設定中動態配置 |
MANAGEMENT_APPLICATION_API | 讀/寫 | 授權訪問管理員層級的介面 | 僅允許在應用詳情-使用權限設定中動態配置 |
USER_API | 讀/寫 | 授權訪問使用者層級的介面 | 不允許動態配置，應用預設授予的許可權 |
openid | 讀 | OIDC 範圍，只有存在該 scope 的情況下，token endpoint 才會返回 | |
profile | 讀 | 授權讀取使用者的預設屬性，比如： | |
讀 | 授權讀取使用者的郵箱，返回 | ||
phone | 讀 | 授權讀取使用者的手機號，返回： |
使用者在登入認證完成後，從 token endpoint 擷取到相應令牌（access_token、refresh_token、id_token），其中的存取權杖（access_token）預設授予了 USER_API的 scope，如此才能基於使用者的存取權杖，請求使用者層級的 API 介面。 在使用者的存取權杖到期後，允許用戶端重新整理應用的 token。重新整理使用者的令牌時，需要在 scope 參數中主動傳遞USER_API，如此重新整理出的使用者存取權杖才可以繼續訪問使用者層級的介面。
7、response_type 定義
在 OAuth 2.0 協議中，response_type 表示通知授權服務（CIAM）所需的授權處理流，包括從 CIAM 返回什麼參數。同時，OAuth 2.0 協議中也定義了 response_type 的可選範圍：
response_type | 描述 |
code | 授權碼模式，認證完成返回授權碼 code |
token | 隱式授權模式，認證完成後返回使用者的 token 資訊 |
在使用者註冊與登入情境中，請求中的response_type 參數不在 OAuth 2.0 協議定義的可選範圍內時，CIAM 會預設 response_type 為 token。