泛微移动办公云OA(eteams)：一体化的团队协作移动办公云平台

该文档是依据竹云IDaaS•开放平台（https://open.bccastle.com/development/docs/web/auth_java.html）进行详细说明：

步骤1：获取 ClientId 和 ClientSecret 参数

企业中心添加应用后，系统将自动生成 ClientId 和 ClientSecret；

进入认证配置，默认开启标准授权模式；

添加回调地址，该地址是应用在用户登录完成后返回给应用授权码的地址。

步骤2：获取Authorization Code

用户访问该应用系统时，应用通过下面接口向竹云IDaaS平台发起授权登录请求，用户输入用户名密码认证成功后，竹云IDaaS平台将重定向到第三方应用系统，并且带上授权码code参数。

请求说明：

参数	描述
请求地址	https://{your_domain}/api/v1/oauth2/authorize
请求方式	GET
是否需要证书	否

请求参数：

参数	名称	必须	示例	描述
response_type	授权类型	必须	code	规定为code
client_id	应用标识	必须	2t0d17l08r343dsfsdff0	应用通用信息处获取
redirect_uri	回调地址	必须	http://demo.com	成功授权后的回调地址，（可以多个域名，用逗号分隔），建议设置为应用首页。注意需要将url进行URLEncode。
state	应用端状态码	可选	15924362	client端的状态值。用于第三方应用系统防止CSRF攻击，成功授权后回调时会原样带回。请务必严格按照流程检查用户与state参数状态的绑定。
scope	授权范围	可选	get_user_info	默认get_user_info

请求示例：

https://{your_domain}/api/v1/oauth2/authorize?response_type=code&client_id=2t0d17l08r343dsfsdff0&redirect_uri=http://oauthdemo.bccastle.com/demo/index.jsp&state=15924362

返回参数说明：

用户成功登录并授权，则会跳转到指定的回调地址，并在redirect_uri地址后带上Authorization Code和原始的state值。

参数	名称	必须	描述
code	授权码	必须	用户登录并授权后，授权服务器返回给应用的授权码。注意：此code会在5分钟内过期。
state	应用端状态码	可选	client端的状态值。用于第三方应用系统防止CSRF攻击，成功授权后回调时会原样带回。

正确返回示例：

{redirect_uri}?code=9A5F**06AF&state=15924362

错误返回示例：

HTTP Status: 302 REDIRECT

{redirect_uri}?error=unauthorized_user&error_description=Unauthorized%20user

步骤3：获取Access Token

通过用户验证登录授权后，获取授权令牌Access Token，Access Token是第三方应用在调用竹云IDaaS平台获取用户信息时必须传入的参数。

请求说明：

参数	描述
请求地址	https://{your_domain}/api/v1/oauth2/token
请求方式	POST
是否需要证书	否

请求参数：

参数名	名称	必须	示例值	描述
grant_type	授权类型	必须	authorization_code	此值固定为authorization_code。
client_id	应用标识	必须	201708300616238	申请接入后分配给第三方应用的clientid。
client_secret	应用秘钥	必须	9c25b1c7cb9641b	申请接入后分配给应用的clientsecret。
code	授权码	必须	6dce46bb65f67de9f81504c651963086	上一步返回的authorization code。
redirect_uri	回调地址	必须	http://oauthdemo.bccastle.com/demo/index.jsp	与上面一步中传入的redirect_uri保持一致。

请求示例：

https://%7Byour_domain%7D/api/v1/oauth2/token?grant_type=authorization_code&client_id=20170830061623854-E5A8-B2FABDC35&client_secret=9c25b1c7cb9641bba4cb8ce4960e24ea&code=6dce46bb65f67de9f81504c651963086&redirect_uri=http://oauthdemo.bccastle.com/demo/index.jsp

返回参数说明：

如果成功返回，即可在返回信息中获取到Access Token。

参数名	名称	必须	示例值	描述
access_token	授权令牌	必须	skiew234i3i4o6uy77b4k3b3v2j1vv53j	授权服务器返回给第三方应用的授权令牌。
expires_in	授权令牌的有效期	必须	1500	授权服务器返回给应用的访问票据的有效期。（注意：有效期以秒为单位）
refresh_token	刷新令牌	必须	iewoer233422i34o2i34uio55iojhg6g
token_type	令牌类型	必须	bearer
scope	授权范围	必须	get_user_info

正确返回示例：

HTTP Status: 200 OK

{
    "access_token":"b7e1fda8-33ce-432c-9b97-7ff035facc27",
    "token_type":"bearer",
    "expires_in":43199,
    "refresh_token":"42e8rrqfqw76k79jnngww24576",
    "scope":"get_user_info"
}

错误返回示例：

HTTP Status: 400 BAD REQUEST

{
"error":"invalid_grant",
"error_description":"Invalid authorization code: 5XEpk2"
}

HTTP Status: 400 BAD REQUEST

{
"error":"invalid_grant",
"error_description":"Redirect URI mismatch."
}

步骤4：刷新 AccessToken（可选）

Access Token的有效期默认是2个小时，最长可设置为24小时，过期后需要用户重新授权才能获得新的Access Token。本步骤可以实现授权自动续期，避免要求用户再次授权的操作，提升用户体验。

请求说明：

参数	描述
请求地址	https://{your_domain}/api/v1/oauth2/token
请求方式	POST
是否需要证书	否

请求参数：

参数名	名称	必须	示例值	描述
grant_type	授权类型	必须	refresh_token	此值固定为refresh_token。
client_id	应用标识	必须	201708300616238	申请接入后分配给第三方应用系统的clientid。
client_secret	应用秘钥	必须	9c25b1c7cb9641b	申请接入后分配给应用系统的clientsecret。
refresh_token	刷新令牌	必须	e8e2bef0da609fd13b086415e77e3638	在获取Access Token接口中，返回的refresh_token。

请求示例：

https://%7Byour_domain%7D/api/v1/oauth2/token?grant_type=refresh_token&client_id=20170830061623854-E5A8-B2FABDC35&client_secret=9c25b1c7cb9641bba4cb8ce4960e24ea&refresh_token=e8e2bef0da609fd13b086415e77e3638

返回参数说明：

如果成功返回，即可在返回信息中获取到Access Token。

参数名	名称	必须	示例值	描述
access_token	授权令牌	必须	skiew234i3i4o6uy77b4k3b3v2j1vv53j	授权服务器返回给第三方应用的授权令牌。
expires_in	授权令牌的有效期	必须	1500	授权服务器返回给应用的访问票据的有效期。（注意：有效期以秒为单位）
refresh_token	刷新令牌	必须	iewoer233422i34o2i34uio55iojhg6g
token_type	令牌类型	必须	bearer
scope	授权范围	必须	get_user_info

正确返回示例：

HTTP Status: 200 OK

{
    "access_token":"b7e1fda8-33ce-432c-9b97-7ff035facc27",
    "token_type":"bearer",
    "expires_in":43199,
    "refresh_token":"42e8rrqfqw76k79jnngww24576",
    "scope":"get_user_info"
}

错误返回示例：

HTTP Status: 400 BAD REQUEST

{
"error":"invalid_grant",
"error_description":"Invalid refresh token: 7753b3aa-4958-4741-8e85-a39"
}

步骤5：获取用户信息

此接口主要用于第三方应用系统使用竹云IDaaS平台登录时，从竹云IDaaS平台获取当前登录用户的信息。

调用受保护API接口时，需要将获取的access_token作为参数传递给受保护API接口，竹云IDaaS平台支持两种access_token传递方式：

URL传参：URL?access_token={access_token}

Header头：Authorization bearer {access_token}

请求说明：

参数	描述
请求地址	https://{your_domain}/api/v1/oauth2/token
请求方式	GET
是否需要证书	否

请求示例：

https://{your_domain}/api/v1/oauth2/userinfo?access_token=b7e1fda8-33ce-432c-9b97-7ff035

返回参数说明：

竹云IDaaS默认返回以下5个用户属性。

字段名称	名称	示例值
id	用户ID	483538f0-03f5-45df-88e7-3b15122ae04b
userName	用户名	zhangsan
name	姓名	张三
email	邮箱地址	zhangsan@qq.com
mobile	手机号	+86-13600001111

返回属性可根据应用系统需要，通过认证配置中的映射配置进行添加和删除。

正确返回示例：

HTTP Status: 200 OK

{
    "id":"483538f0-03f5-45df-88e7-3b15122ae04b",
    "userName":"zhangsan",
    "mobile":"+86-13600001111",
    "email":"zhanshang@qq.com",
    "name":"张三"
}

错误返回示例：

HTTP Status: 401 UNAUTHORIZED

{
"error":"invalid_token",
"error_description":"Invalid access token: 7753b3aa-4958-4741-8e85-a39f00e"
}

步骤6：验证

1、授权用户：

在应用信息-应用账号中点击添加账号按钮，选择授权用户

2、访问自建应用：

访问自建应用url，应用携带参数请求IDaaS登录授权（此部分逻辑需要应用开发者自行实现）

3、登录认证：

在IDaaS认证界面进行用户登录

4、进入应用

全局退出

全局退出即为用户在请求IDaaS退出时，将退出所有此次会话访问过的应用系统和认证源。

使用场景：应用在和IDaaS进行认证集成后，在退出应用系统后，会出现无法退出的情况，原因是没有注销IDaaS的登录会话。

所以应用在退出时，需要调用IDaaS的全局退出接口，进行IDaaS的用户会话注销。

请求说明：

参数	描述
参数	说明
请求地址	https://{IDaaS租户域名}/api/v1/logout
请求方式	GET
是否需要证书	否

请求参数：

参数名	名称	必须	示例	描述
redirectToUrl	退出重定向地址	必须	https://application.com/login	建议设置为退出应用的登录地址

示例：

https://xxx.bccastle.com/api/v1/logout?redirectToUrl=https://application.com

竹云统一身份认证对接接口文档

帮助中心