备案控制台
文档
产品文档
输入文档关键字查找
首页 应用身份服务 (IDaaS) CIAM 用户身份服务 开发参考 API 概览

API 概览

更新时间：
一键部署
提交缺陷
产品详情
相关技术圈
我的收藏

此 API 文档专为希望使用 RESTful API 方式集成 CIAM 的用户而设计，接口分为认证接口、管理接口、用户接口。

技术类文档，涉及到部分专业名词，正式调用接口前请先参考本文了解相关名词术语以及业务流程。

1. API 地址

请参考阿里云账号下应用身份管理-CIAM 用户身份服务中对应实例的“实例开放接口域名”。格式如下：

https://xxxx.api.aliyunidaas.com

获取路径请参考：

image.png

2. API 接口分类

CIAM 产品提供了丰富的 API 接口能力，可分为认证接口、管理接口、用户接口。

API 类型

调用方

用途范围

使用限制

鉴权

认证接口

业务系统服务端

账密登录、短信登录、社交媒体登录、社交媒体注册、短信注册、密码找回。

CIAM 控制台应用中必须授权 APPLICATION_API scope

受应用的 accessToken 保护

管理接口

业务系统服务端

对账号生命周期做管理，注销，查看用户详情。

CIAM 控制台应用中必须授权 MANAGEMENT_APPLICATION_API scope

受应用的 accessToken 保护

用户接口

业务系统服务端

修改手机、修改邮箱、查询个人信息、绑定三方社交账号、注销账号

只要是终端用户登录后都可以适用

受用户的 accessToken 保护

3. API 业务流程

在 CIAM 中，我们以 fId 标记整个流程，在一个完整的流程中（如账密登录->二次认证->完善信息->登录成功），只有返回授权 code 或者 token 后才标志着这个流程完整执行。

根据CIAM控制台中针对应用配置不同，在整个的登录或者注册流程也会不同，比如账密登录后是否需要二次认证，是否需要完善个人信息（名称，手机号，邮箱，修改密码）等。

基于fId串联整个登录流程，当前处理完下一步是否需要有子流程，由data下的flowTyp统一标识。如账密登录完需要二次认证，返回结果如下。

{
    "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认证后callBack业务系统实现SSO（state原样返回）。

请求示例

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

返回示例

业务端根据 data 中 redirectUrl 自行实现跳转。

{
    "success": true,
    "code": "Operation.Success",
    "message": "Operation.Success",
    "requestId": "1657782880567$bebbd27b-e9c3-db44-b06f-adbc5ef07ef6",
    "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 才会返回 id_token

profile

读

授权读取用户的默认属性，比如：name、nickname、gender等等

email

读

授权读取用户的邮箱，返回 email和 email_verified

phone

读

授权读取用户的手机号，返回：phone_number和phone_number_verified​

说明

用户在登录认证完成后，从 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。

文档推荐
  • 本页导读 （0）
文档反馈