中国科学技术大学统一身份认证系统开发者手册¶

本指南适用于校内应用系统开发者，帮助您对接统一身份认证（CAS / OAuth2.0 / OIDC）。

⚠️ 校外应用（不在校内部署、域名不为 ustc.edu.cn）目前不提供对接支持。

1. 概述¶

统一身份认证系统提供单点登录（SSO）能力，支持：

CAS 3.0：CAS Protocol 3.0 Specification
【推荐】OAuth 2.0：OAuth 2.0 中授权码模式（Authorization Code Grant）
OIDC 1.0：OpenID Connect 1.0

需要注意的是，对于新接入的应用系统，我们仅推荐使用OAuth 2.0进行对接，CAS 3.0和OIDC 1.0作为兼容协议进行支持。统一身份认证系统推荐通过 OAuth2.0 授权码模式（Authorization Code Grant） 接入。针对不同类型应用，对接前请做好准备：

网页应用：在网络安全工作平台完成建站申请及网站备案后，由网站负责人或管理员填写统一身份认证接入申请
公众号/小程序应用：OA公文系统完成新媒体备案后，联系wf0229@ustc.edu.cn
移动APP：联系wf0229@ustc.edu.cn

系统管理员收到应用接入申请后提供相关参数信息（如client_id&client_secret等）

2. 系统接口¶

2.1 OAuth2.0 [推荐]¶

开始对接时，开发者需要获得 client_id、client_secret。

第一步：第三方应用将用户认证重定向至统一身份认证¶

Field	Details
endpoint	`https://id.ustc.edu.cn/cas/oauth2.0/authorize`
method	`GET`

重定向时，请提供相关参数：

Parameter	Required	Example	Description
response_type	MUST	`code`	固定值`code`，表示授权码模式
client_id	MUST	`oauth_test_client_id`	应用的 Client ID，由系统管理员提供
redirect_uri	MUST	`https://webapp.ustc.edu.cn/callback`	授权完成后回调地址,需要urlencode
scope	OPTIONAL	`gid email name`	请求的权限范围，多个权限用空格分隔
state	OPTIONAL	`xyz987`	随机生成的字符串，用于防止CSRF攻击

示例代码：

curl https://id.ustc.edu.cn/cas/oauth2.0/authorize?response_type=code&client_id=oauth_test_client_id&redirect_uri=https%3A%2F%2Fwebapp.ustc.edu.cn%2Fcallback

统一身份认证接到请求后，会向用户代理（User Agent，即浏览器）展示登录页面。

用户提供有效登录凭据后，统一身份认证服务器向用户代理做出响应：

HTTP/1.1 302 Found
Location: https://webapp.ustc.edu.cn/callback?code=ABCD1234&state=xyz123

其中:

Parameter	Example	Description
code	`ABCD1234`	统一身份认证生成的随机字符串，用以下一步换取access_token
state	`xyz987`	与request时候传递相同

值得注意的是：

一般情况下不需要传递 scope，统一身份认证系统因为兼容CAS协议的原因，会根据配置好每个webapp所需的用户属性在后续的profile接口中返回。
第三方应用需要必要的机制来预防CSRF(Cross-Site Request Forgery)，例如通过传递随机生成的 state 并校验，以避免统一身份认证的响应被劫持后导致会话混淆,即攻击者可以代替受害者与应用系统建立连接，详见 How does CSRF work without state parameter in OAuth2.0?

第二步：第三方应用使用 `code` 获取 `access_token`¶

第三方应用回调地址获取到 code 后，使用 code 获取 access_token 。

Field	Details
endpoint	`https://id.ustc.edu.cn/cas/oauth2.0/accessToken`
method	`POST`

在获取 access_token 时，需要增加请求头:

Content-Type: application/x-www-form-urlencoded

同时携带相关参数：

Parameter	Required	Example	Description
grant_type	MUST	`authorization_code`	授权模式固定值
client_id	MUST	`oauth_test_client_id`	应用的 Client ID，系统管理员提供
client_secret	MUST	`9aggRf1kk0tS...`	应用的 Client Secret，系统管理员提供
redirect_uri	MUST	`https://webapp.ustc.edu.cn/callback`	回调地址，需与第一步一致并URL编码
code	MUST	`OC-9-iQBaj2rYndjtttJqJ`	从第一步授权返回的 code

🌿 请求示例

curl -X POST "https://id.ustc.edu.cn/cas/oauth2.0/accessToken" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=authorization_code" \
     -d "client_id=oauth_test_client_id" \
     -d "client_secret=9aggRf1kk0tS..." \
     -d "redirect_uri=https%3A%2F%2Fwebapp.ustc.edu.cn%2Fcallback" \
     -d "code=OC-9-iQBaj2rYndjtttJqJE9P6Qn-eoinZGnJ"

统一身份认证服务器在验证成功后将返回如下响应：

{
    "access_token":"AT-98-kkxRFRAp7JP4HvKcooOlTjqEslglCNoU",
    "token_type":"bearer",
    "expires_in":28800
}

其中：

Parameter	Example	Description
access_token	`AT-98-kkxRFRAp7JP4HvKcooOlTjqEslglCNoU`	用于后续获取用户信息的访问令牌
token_type	`bearer`	令牌类型，固定为 `bearer`
expires_in	`28800`	有效期（单位：秒）

如果校验失败，错误代码解释如下：

Parameter	Example	Description

第三步：第三方应用使用access_token获取用户信息¶

第三方应用在获取 access_token 后，需要使用该令牌调用接口获取用户信息。

Field	Details
endpoint	`https://id.ustc.edu.cn/cas/oauth2.0/profile`
method	`POST`

在获取用户信息时，需要增加请求头:

Content-Type: application/x-www-form-urlencoded

同时携带相关参数：

Parameter	Required	Example	Description
access_token	MUST	`AT-98-kkxRFRAp7JP4HvKcooOlTjqEslglCNoU`	第二步获取的 access_token

🌿 POST 请求示例

curl -X POST "https://id.ustc.edu.cn/cas/oauth2.0/profile" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "access_token=AT-98-kkxRFRAp7JP4HvKcooOlTjqEslglCNoU"

统一身份认证服务器在验证成功后将返回如下响应：

{
    "active": true,
    "attributes": {
        "deptCode": "304",
        "email": "zhangsan@mail.ustc.edu.cn",
        "gid": "9202420483",
        "jrzjhm": "45433",
        "login": "45433",
        "loginip": "117.152.207.90",
        "logintime": "2025-05-20 22:48:42",
        "name": "张三",
        "objectId": "673493032d5b870006ebcf85",
        "ryfldm": "102010000",
        "ryzxztdm": "10",
        "xbm": "1",
        "zjhm": "45433"
    },
    "id": "45433",
    "client_id": "xxx"
}

返回参数说明：

Parameter	Description	Dictionary Reference
id	学工号	无
client_id	应用 ID	无
attributes	用户属性列表	无
deptCode	部门编码	无
email	邮箱	无
gid	GID	无
login	用户输入的账号（GID或学工号）	无
loginip	登录 IP	无
logintime	登录时间	无
name	姓名	无
ryfldm	人员类型代码	有
ryzxztdm	在校状态码	有
xbm	性别码	有
zjhm	证件号码（学工号）	无

⚠️ 安全提示：

access_token是敏感凭据，请勿在客户端或日志中暴露。
如需了解人员类型、性别等字典对应关系，请联系系统管理员获取完整数据字典。

2.2 CAS 3.0¶

第一步：应用请求用户认证¶

应用向统一身份认证（CAS）服务器发起认证请求。

Field	Details
endpoint	`https://id.ustc.edu.cn/cas/login`
method	`GET`

请求参数：

Parameter	Required	Example	Description
service	MUST	`https%3A%2F%2Fwebapp.ustc.edu.cn%2Flogin%2Fcas_login`	用户认证成功后，CAS将携带Ticket重定向回该地址，要求URLENCODE
renew	OPTIONAL	`True`	如果设置此参数，SSO 单点状态将被绕过。在这种情况下，无论CAS是否存在SSO session，CAS都要求客户端提供凭证。
gateway	OPTIONAL	`True`	如果设置了此参数，则CAS不会要求客户端提供凭据。

注意不要同时设置 renew和gateway参数，两者都设置统一身份认证服务器会忽略gateway。
gateway为True时：
如果用户代理与统一身份认证服务器已经存在单点会话（session），统一身份认证服务器会将用户代理重定向到service指定的URL，并附加一个有效的ticket。
如果用户代理与统一身份认证服务器尚不存在单点会话（session），统一身份认证服务器会将用户代理重定向到service指定的URL。
中国科大统一身份认证服务器/login接口不支持method参数

🌿 请求示例

curl "https://id.ustc.edu.cn/cas/login?service=https%3A%2F%2Fwebapp.ustc.edu.cn%2Flogin%2Fcas_login"

统一身份认证接到请求后，会向用户代理（User Agent，即浏览器）展示登录页面。

用户提供有效登录凭据后，统一身份认证服务器向用户代理做出响应：

HTTP/1.1 302 Found
Location: https://webapp.ustc.edu.cn/login/cas_login?ticket=ST-368-gChqIqVuq9j83YCG9dw4sh1KDaMrg-sso-fddcfb8db-z9ng2

参数说明：

Parameter	Example	Description
ticket	`ST-368-gChqIqVuq9j83YCG9dw4sh1KDaMrg-sso-fddcfb8db-z9ng2`	Service Ticket，用于下一步向CAS服务器验证用户身份

⚠️ 说明：

ticket只在一次性验证有效，使用后立即失效。
Service URL必须与后续验证请求中的service参数保持一致,且必须URLENCODE。

第二步：验证 Ticket（CAS 3.0 协议）¶

应用在收到 ticket 后，需要向统一身份认证服务器验证票据以获取用户信息。

Field	Details
endpoint	`https://id.ustc.edu.cn/cas/p3/serviceValidate`
method	`GET`

请求参数：

Parameter	Required	Example	Description
ticket	MUST	`ST-368-gChqIqVuq9j83YCG9dw4sh1KDaMrg-sso-fddcfb8db-z9ng2`	第一步认证后返回的 Service Ticket
service	MUST	`https%3A%2F%2Fwebapp.ustc.edu.cn%2Flogin%2Fcas_login`	与第一步完全一致的 Service URL（需 URLENCODE）
format	OPTIONAL	`JSON` 或 `XML`	选择返回信息的数据结构

统一身份认证服务器默认返回xml结构：

如果传递了format=json，则返回json格式数据

{
    "active": true,
    "attributes": {
        "deptCode": "304",
        "email": "zhangsan@mail.ustc.edu.cn",
        "gid": "9202420483",
        "jrzjhm": "45433",
        "login": "45433",
        "loginip": "117.152.207.90",
        "logintime": "2025-05-20 22:48:42",
        "name": "张三",
        "objectId": "673493032d5b870006ebcf85",
        "ryfldm": "102010000",
        "ryzxztdm": "10",
        "xbm": "1",
        "zjhm": "45433"
    },
    "id": "45433",
    "client_id": "xxx"
}

参数说明：

Element	Example	Description
user	`zhangsan`	用户名
email	`zhangsan@mail.ustc.edu.cn`	邮箱地址
name	`张三`	姓名
gid	`9202420483`	GID
deptCode	`304`	部门编码
ryfldm	`102010000`	人员类型代码
ryzxztdm	`10`	在校状态码
xbm	`1`	性别码
zjhm	`45433`	证件号码（学工号）

⚠️ 说明：

Service URL必须与第一步完全一致（包括协议、域名、路径、URL编码）。
返回的XML需由应用解析，提取 authenticationSuccess 元素下的用户信息。
如果验证失败，返回。

2.3 OIDC¶

第一步：第三方应用将用户认证重定向至统一身份认证¶

Field	Details
endpoint	`https://id.ustc.edu.cn/cas/oidc/authorize`
method	`GET`

重定向时，请提供相关参数：

Parameter	Required	Example	Description
response_type	MUST	`code`	固定值`code`，表示授权码模式
client_id	MUST	`oidc_client_id`	应用的 Client ID，由系统管理员提供
redirect_uri	MUST	`https://webapp.ustc.edu.cn/callback`	授权完成后回调地址,需要urlencode
scope	OPTIONAL	`gid email name`	请求的权限范围，多个权限用空格分隔
state	OPTIONAL	`xyz987`	随机生成的字符串，用于防止CSRF攻击

示例代码：

curl https://id.ustc.edu.cn/cas/oidc/authorize?response_type=code&client_id=oidc_client_id&redirect_uri=urlencode{https://webapp.ustc.edu.cn/callback}&scope=urlencode{gid email name}

统一身份认证接到请求后，会向用户代理（User Agent，即浏览器）展示登录页面。

用户提供有效登录凭据后，统一身份认证服务器向用户代理做出响应：

HTTP/1.1 302 Found
Location: https://webapp.ustc.edu.cn/callback?code=ABCD1234

其中:

Parameter	Example	Description
code	`ABCD1234`	统一身份认证生成的随机字符串，用以下一步换取access_token,10s过期
state	`xyz987`	与request时候传递相同

值得注意的是：

一般情况下不需要传递 scope，统一身份认证系统因为兼容CAS协议的原因，会根据配置好每个webapp所需的用户属性在后续的profile接口中返回。
第三方应用需要必要的机制来预防CSRF(Cross-Site Request Forgery)，例如通过传递随机生成的 state 并校验，以避免统一身份认证的响应被劫持后导致会话混淆,即攻击者可以代替受害者与应用系统建立连接，详见 How does CSRF work without state parameter in OAuth2.0?

第二步：第三方应用使用 `code` 获取 `access_token`¶

第三方应用回调地址获取到 code 后，使用 code 获取 access_token 。

Field	Details
endpoint	`https://id.ustc.edu.cn/cas/oidc/accessToken`
method	`POST`

在获取 access_token 时，需要增加请求头:

Content-Type: application/x-www-form-urlencoded

同时携带相关参数：

Parameter	Required	Example	Description
grant_type	MUST	`authorization_code`	授权模式固定值
client_id	MUST	`oidc_client_id`	应用的 Client ID，系统管理员提供
client_secret	MUST	`9aggRf1kk0tS...`	应用的 Client Secret，系统管理员提供
redirect_uri	MUST	`https://webapp.ustc.edu.cn/callback`	回调地址，需与第一步一致并URL编码
code	MUST	`OC-9-iQBaj2rYndjtttJqJ`	从第一步授权返回的 code

🌿 请求示例

curl -X POST "https://id.ustc.edu.cn/cas/oidc/accessToken" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=authorization_code" \
     -d "client_id=oidc_client_id" \
     -d "client_secret=9aggRf1kk0tS..." \
     -d "redirect_uri=http%3A%2F%2Fwebapp.ustc.edu.cn%2Fcallback" \
     -d "code=OC-9-iQBaj2rYndjtttJqJE9P6Qn-eoinZGnJ"

统一身份认证服务器在验证成功后将返回如下响应：

{
    "access_token":"AT-98-kkxRFRAp7JP4HvKcooOlTjqEslglCNoU",
    "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiJTVC00OS0yY2VTN1RRLU5PbkprV2xieGRRMm56T3B1V01yZy1zc28tbmF0aXZlLTViY2JkZDZiODQtemNsa2IiLCJpc3MiOiJodHRwczovL3Nzby0xMS5ydWlzaGFuLmNjIiwiYXVkIjoiT2F1dGhUZXN0IiwiZXhwIjoxNzY3NjA1OTQ3LCJpYXQiOjE3Njc1OTg3NDcsIm5iZiI6MTc2NzU5ODQ0Nywic3ViIjoiMTEyMDI1MTAwOCIsImFtciI6W10sImNsaWVudF9pZCI6Ik9hdXRoVGVzdCIsInN0YXRlIjoiIiwibm9uY2UiOiIiLCJhdF9oYXNoIjoiVUFDbHJ6UlNDTVJDSFRLdVk3VnJ1ZyIsInByZWZlcnJlZF91c2VybmFtZSI6Ik9hdXRoVGVzdCJ9.Bw0WvRPJraRI35iKqyY6mZYf9xVA49yKc2_e0zS_ClSFK8SbPEGGOaFzZK3F0X23R97jNDB-XLnbZI5U3Ly2bZCHACTZbpMgrhtsCMXWLxPDkvx4qcEgErgn6MIuHRPNZAOV6goHth2OwKe5JoB2rkK4qxK7mIQpm7RdhC2aVTPfmvm6xcu-z12TvO6XtsYQcsBVHVgFgYRRDXUwpUFOe2BSB_FD1rZqbq2aOxoYcigHdaupeKbsrH5Y84uxGoHAvOWNS8AzT25qusK-oc6fA6JAOszjgQUGikTLkO1_kQecCCOc3riEwcY2ZvmvR8XxXy7dGozra3cIyShvpB-m6Q",
    "token_type":"bearer",
    "expires_in":7200,
    "scope":""
}

其中：

Parameter	Example	Description
access_token	`AT-98-kkxRFRAp7JP4HvKcooOlTjqEslglCNoU`	用于后续获取用户信息的访问令牌
id_token	`eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXV.....`	用户的身份凭证
token_type	`bearer`	令牌类型，固定为 `bearer`
expires_in	`7200`	有效期（单位：秒）

如果校验失败，错误代码解释如下：

Parameter	Example	Description

第三步：第三方应用使用access_token获取用户信息¶

第三方应用在获取 access_token 后，需要使用该令牌调用接口获取用户信息。

Field	Details
endpoint	`https://id.ustc.edu.cn/cas/oidc/profile`
method	`POST`

在获取用户信息时，需要增加请求头:

Content-Type: application/x-www-form-urlencoded

同时携带相关参数：

Parameter	Required	Example	Description
access_token	MUST	`AT-98-kkxRFRAp7JP4HvKcooOlTjqEslglCNoU`	第二步获取的 access_token

🌿 POST 请求示例

curl -X POST "https://id.ustc.edu.cn/cas/oidc/profile" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "access_token=AT-98-kkxRFRAp7JP4HvKcooOlTjqEslglCNoU"

统一身份认证服务器在验证成功后将返回如下响应：

{
    "sub": "45433",
    "auth_time": 1767598733,
    "attributes": {
        "deptCode": "304",
        "email": "zhangsan@mail.ustc.edu.cn",
        "gid": "9202420483",
        "jrzjhm": "45433",
        "login": "45433",
        "loginip": "117.152.207.90",
        "logintime": "2025-05-20 22:48:42",
        "name": "张三",
        "objectId": "673493032d5b870006ebcf85",
        "ryfldm": "102010000",
        "ryzxztdm": "10",
        "xbm": "1",
        "zjhm": "45433"
    },
    "id": "45433"
}

返回参数说明：

Parameter	Description	Dictionary Reference
id	学工号	无
sub	用户标识（GID）	无
auth_time	认证时间	无
attributes	用户属性列表	无
deptCode	部门编码	无
email	邮箱	无
gid	GID	无
login	用户输入的账号（GID或学工号）	无
loginip	登录 IP	无
logintime	登录时间	无
name	姓名	无
ryfldm	人员类型代码	有
ryzxztdm	在校状态码	有
xbm	性别码	有
zjhm	证件号码（学工号）	无

⚠️ 安全提示：

access_token是敏感凭据，请勿在客户端或日志中暴露。
如需了解人员类型、性别等字典对应关系，请联系系统管理员获取完整数据字典。

2.4 单点登出¶

当应用需要让用户退出登录时，可调用统一身份认证服务器的退出接口。注意，这里会注销用户代理（即浏览器）的单点会话状态（session）。

Field	Details
endpoint	`https://id.ustc.edu.cn/cas/logout`
method	`GET`

请求参数：

Parameter	Required	Example	Description
service	OPTIONAL	`https%3A%2F%2Fwebapp.ustc.edu.cn%2Flogin%2Fcas_login`	用户登出后，CAS会自动重定向到指定地址（需URL编码）

如果logout时不设置service，登出后用户代理会停留在https://id.ustc.edu.cn

2.5 字典表¶

用户信息¶

参数	说明	是否有字典
id	用户名	否
client_id	应用ID	否
attributes	用户属性列表	否
deptCode	部门编码	否
email	邮箱	否
gid	GID	否
login	登录时输入的账号（用户输入的GID或学工号）	否
loginip	登录的IP	否
logintime	登录的时间	否
name	姓名	否
ryfldm	人员类型代码	是
ryzxztdm	在校状态码	是
xbm	性别码	是
zjhm	证件号码（学工号）	否

人员类型代码字典表¶

邮件联系wf0229@ustc.edu.cn获取。

xbm字典表¶

代码	字典值
1	男
2	女

ryzxztdm字典表¶

代码	字典值
10	在校
20	离校(含校内身份结束)
30	校内身份转换
40	离退休
50	暂时离校(休学/出国等)
99	其他
91	证件停用或注销

3 网页应用接入示例¶

TBC

中国科学技术大学 统一身份认证系统 开发者手册¶

1. 概述¶

2. 系统接口¶

2.1 OAuth2.0 [推荐]¶

第一步：第三方应用将用户认证重定向至统一身份认证¶

第二步：第三方应用使用 code 获取 access_token¶

第三步：第三方应用使用access_token获取用户信息¶

2.2 CAS 3.0¶

第一步：应用请求用户认证¶

第二步：验证 Ticket（CAS 3.0 协议）¶

2.3 OIDC¶

第一步：第三方应用将用户认证重定向至统一身份认证¶

第二步：第三方应用使用 code 获取 access_token¶

第三步：第三方应用使用access_token获取用户信息¶

2.4 单点登出¶

2.5 字典表¶

用户信息¶

人员类型代码字典表¶

xbm字典表¶

ryzxztdm字典表¶

3 网页应用接入示例¶

中国科学技术大学统一身份认证系统开发者手册¶

第二步：第三方应用使用 `code` 获取 `access_token`¶

第二步：第三方应用使用 `code` 获取 `access_token`¶