ICS35.080

CCSL77

團體標準

T/ZGCSA1.7—2024

數(shù)字政府應(yīng)用服務(wù)規(guī)范

第7部分：單點登錄服務(wù)接口規(guī)范

ElectronicGovernmentApplicationServiceSpecification—

Part7:Single-sign-onServiceAPISpecification

（征求意見稿）

2024-XX-XX發(fā)布2024-XX-XX實施

中關(guān)村軟件和信息服務(wù)產(chǎn)業(yè)創(chuàng)新聯(lián)盟發(fā)布

T/ZGCSA1.7—2024

數(shù)字政府應(yīng)用服務(wù)規(guī)范

第7部分：單點登錄服務(wù)接口規(guī)范

1范圍

該部分規(guī)定了單點登錄服務(wù)接口，定義了單點登錄票據(jù)的模式。規(guī)定了生物認證登錄服務(wù)接口和非

生物認證登錄服務(wù)接口，適用于需做單點登錄整合的應(yīng)用系統(tǒng)。

本部分適用于全國各級黨政機關(guān)、企事業(yè)單位、國土、財政、水利、統(tǒng)計等行業(yè)以及NGO的信息系

統(tǒng)規(guī)劃、建設(shè)，以及系統(tǒng)集成商、軟件開發(fā)商和監(jiān)理單位進行數(shù)字政府信息系統(tǒng)的開發(fā)與整合。

在涉及國家秘密的信息系統(tǒng)規(guī)劃、建設(shè)中，需參照《涉及國家秘密的信息系統(tǒng)分級保護管理辦法》

和相關(guān)標準、規(guī)定。

2規(guī)范性引用文件

下列文件中的條款通過本部分的引用而成為本部分的條款。凡是注日期的引用文件，其隨后所有的

修改單（不包括勘誤的內(nèi)容）或修訂版均不適用于本部分，然而，鼓勵根據(jù)本部分達成協(xié)議的各方研究

是否可使用這些文件的最新版本。凡是不注日期的引用文件，其最新版本適用于本部分。

T/ZGCSA1.1—2024數(shù)字政府應(yīng)用服務(wù)規(guī)范第1部分：總則

T/ZGCSA1.2—2024數(shù)字政府應(yīng)用服務(wù)規(guī)范第2部分：組織身份模型數(shù)據(jù)規(guī)范

T/ZGCSA1.3—2024數(shù)字政府應(yīng)用服務(wù)規(guī)范第3部分：組織身份服務(wù)接口規(guī)范

3術(shù)語和定義

票據(jù)：

用戶在通過單點登錄驗證后獲得，包含用戶的基本信息，如唯一標識、登錄名、票據(jù)的有效期等。

票據(jù)標識：

用戶在通過單點登錄驗證后獲得票據(jù)的唯一標識。

OAuth（OpenAuthorization）：

是一個開放標準協(xié)議，在無需將用戶賬號密碼告訴給第三方應(yīng)用的基礎(chǔ)上，允許第三方應(yīng)用在授權(quán)

的情況下訪問用戶應(yīng)用上存儲的信息資源。

4作用

通過單點登錄服務(wù)讓用戶在一次輸入用戶名密碼驗證登錄后，訪問所有應(yīng)用系統(tǒng)而不需要再輸入用

戶名和密碼進行驗證；用戶在一次注銷后，即可在所有應(yīng)用系統(tǒng)實現(xiàn)注銷。

1

T/ZGCSA1.7—2024

單點登錄服務(wù)以組織身份模型為數(shù)據(jù)基礎(chǔ)，以組織身份服務(wù)為運行支撐。實現(xiàn)單點登錄服務(wù)的前提

是，各應(yīng)用系統(tǒng)采用統(tǒng)一的組織身份數(shù)據(jù)模型。單點登錄服務(wù)中的認證及獲取用戶信息均應(yīng)調(diào)用組織身

份服務(wù)接口。

5單點登錄服務(wù)邏輯

5.1服務(wù)代理

為用戶提供單點登錄認證，認證成功后為該用戶頒發(fā)對應(yīng)的票據(jù)。將票據(jù)和票據(jù)標識保存在服務(wù)器

上，同時將票據(jù)的標識保存在用戶的客戶端。在用戶請求注銷時，負責(zé)通知各應(yīng)用系統(tǒng)注銷該用戶。

5.2訪問攔截組件

攔截用戶對應(yīng)用系統(tǒng)的訪問請求，根據(jù)保存在客戶端的用戶票據(jù)標識，向單點登錄代理服務(wù)器請求

用戶的票據(jù)，如果正確地得到了用戶的票據(jù)，則調(diào)用應(yīng)用系統(tǒng)二次認證接口（參見6.4）。如果二次認

證通過，則允許用戶訪問該應(yīng)用系統(tǒng)；如果票據(jù)標識不存在或者票據(jù)無效，則不允許用戶訪問該應(yīng)用系

統(tǒng)。

5.3對應(yīng)用系統(tǒng)的約束

5.3.1應(yīng)用系統(tǒng)二次認證

根據(jù)用戶的票據(jù)標識從單點登錄代理服務(wù)器中獲得用戶票據(jù)，從票據(jù)中獲得用戶的基本信息，再進

行應(yīng)用系統(tǒng)的本地認證。

5.3.2應(yīng)用系統(tǒng)本地注銷

用戶在入口點注銷后，由單點登錄服務(wù)代理通知各應(yīng)用系統(tǒng)，在所有的應(yīng)用系統(tǒng)中注銷該用戶。

6接口描述

統(tǒng)一身份認證平臺將基于Oauth2.0協(xié)議授權(quán)碼模式與應(yīng)用系統(tǒng)實現(xiàn)技術(shù)對接。

2

T/ZGCSA1.7—2024

上圖為OAuth2.0授權(quán)碼模式認證時序圖，描述了一個應(yīng)用的授權(quán)認證及訪問過程，分兩個階段。

a）階段一為單點認證階段：

1)訪問應(yīng)用系統(tǒng)，應(yīng)用系統(tǒng)檢測未登錄；

2)請求獲取授權(quán)碼端口/sso/oauth2.0/authorize；

3)系統(tǒng)檢測到用戶未登錄，重定向至登錄頁面；

4)用戶輸入用戶名密碼登錄；

5)認證服務(wù)認證通過后攜帶授權(quán)碼code重定向；

6)瀏覽器跳轉(zhuǎn)至應(yīng)用；

7)應(yīng)用系統(tǒng)前端調(diào)用應(yīng)用系統(tǒng)后端訪問令牌接口；

8)后端資源服務(wù)服務(wù)器再去調(diào)用統(tǒng)一認證/sso/oauth2.0/accessToken接口獲取訪問令牌

access_token。因為client_secret存儲在后端服務(wù)器中更為安全；

9)認證服務(wù)返回訪問令牌access_token給應(yīng)用系統(tǒng)后端；

3

T/ZGCSA1.7—2024

10)應(yīng)用系統(tǒng)前端拿到應(yīng)用系統(tǒng)后端返回的訪問令牌access_token后將其緩存在本地；

11)應(yīng)用通過獲取用戶信息接口/sso/oauth2.0/profile獲取用戶信息；

12)認證服務(wù)返回用戶信息。

b）階段二為訪問后端接口：

1)檢測應(yīng)用系統(tǒng)中的access_token是否存在；

2)應(yīng)用系統(tǒng)前端可先檢查訪問令牌access_token是否過期，過期的令牌可通過調(diào)用刷新訪問令牌

的接口，應(yīng)用系統(tǒng)前端調(diào)用應(yīng)用系統(tǒng)后端的刷新令牌接口。如果檢查訪問令牌沒有過期可以直

接到第六步執(zhí)行訪問接口；

3)應(yīng)用系統(tǒng)后端再調(diào)用統(tǒng)一認證的刷新訪問令牌接口/sso/oauth2.0/accessToken刷新令牌；

4)認證服務(wù)返回訪問令牌access_token到應(yīng)用系統(tǒng)后端；

5)應(yīng)用系統(tǒng)前端拿到應(yīng)用系統(tǒng)后端返回的訪問令牌access_token后將其緩存在本地；

6)請求應(yīng)用系統(tǒng)后端接口，并在請求頭中帶上訪問令牌access_token；

7)應(yīng)用系統(tǒng)后端接收到請求后調(diào)用統(tǒng)一認證的訪問令牌校驗接口/sso/oauth2.0/introspect進

行令牌校驗；

8)校驗通過應(yīng)用系統(tǒng)后端會收到令牌狀態(tài)、用戶信息等返回，之后可繼續(xù)進行業(yè)務(wù)的處理；

9)應(yīng)用系統(tǒng)前端收到后端返回的業(yè)務(wù)數(shù)據(jù)；

10)瀏覽器渲染數(shù)據(jù)顯示。

7服務(wù)接口

7.1獲取授權(quán)碼

接口地址：https://ip:port/sso/oauth2.0/authorize

請求方法：GET

Content-Type：multipart/form-data

接口描述：授權(quán)用戶啟動身份驗證流程，瀏覽器訪問該端口

請求參數(shù)：

參數(shù)名描述

response_type為固定值code

client_id申請的客戶端id。

重定向url，認證通過后會重定向回來并以授權(quán)碼code

redirect_uri

作為請求參數(shù)。

7.2獲取訪問令牌

接口地址：https://ip:port/sso/oauth2.0/accessToken

4

T/ZGCSA1.7—2024

請求方法：POST

接口描述：通過授權(quán)碼code獲取訪問令牌

請求參數(shù)：

參數(shù)名描述

grant_type授權(quán)類型為固定值authorization_code。

client_id申請的客戶端id。

client_secret申請的客戶端密鑰。

請求授權(quán)返回的授權(quán)碼code，一個授權(quán)碼使用一次后便

code

會失效。

redirect_uri重定向url。

響應(yīng)字段：

字段描述

access_token訪問令牌。

refresh_token刷新令牌。

token_type令牌類型。

expires_in過期時間（秒）。

scope權(quán)限范圍。

響應(yīng)示例：

{

access_token:"AT-54-1EupnbVn1TkmLbALdI-WcvXaoKfzyzHM",

refresh_token:"RT-54-KpmWKmYFR4Fcqxfn9P4psadOtfvNRo-C",

token_type:"bearer",

expires_in:28800,

scope:""

}

7.3獲取用戶信息

接口地址：https://ip:port/sso/oauth2.0/profile

請求方法：GET

描述：獲取認證過的用戶信息

請求參數(shù)：

參數(shù)名描述

access_token訪問令牌

響應(yīng)字段：

字段描述

avator頭像url

CAIDCAID

dn由name組成的父子關(guān)系列表(倒序)，之間用逗號分隔

email郵箱

5

T/ZGCSA1.7—2024

guidPath由ID組成的父子關(guān)系列表(正序)，之間用逗號分隔

IDNum身份證號

isValidateIE是否為合法的IE版本（針對使用IE的情況）

loginName登錄名

loginType登錄類型

mobile電話號碼

name姓名

oauthClientIdoauth客戶端id

original是否為原始賬號（針對多崗）

originalID原始賬號id

parentID人員父節(jié)點id

password密碼

personID人員id

personType人員類型

roles角色

sex性別

tenantID租戶id

tenantLoginName租戶登錄名

tenantManager是否為租戶管理員

tenantName租戶名

service授權(quán)認證的服務(wù)url

id登錄名

client_idoauth客戶端id

響應(yīng)示例：

{

avator:"",

CAID:"",

dn:"cn=張三,ou=XX部門,o=XX集團",

email:"",

guidPath:"4868e899c5034a87a49b5cd9d345de96,dea693bbd9434bc0afdc81701efbf545,4c106

ab010ef47858e0acc84f98ea2a1",

IDNum:"",

isValidateIE:"true",

loginName:"張三",

loginType:"loginName",

mobile:"135*****412",

name:"張三",

oauthClientId:"clientid",

original:1,

originalID:"",

parentID:"dea693bbd9434bc0afdc81701efbf545",

password:"20:45:41:09:B4:4F:B4:1F:BD:C4:A9:C6:CC:79:4E:F9:01:06:5F:E6",

personID:"4c106ab010ef47858e0acc84f98ea2a1",

6

T/ZGCSA1.7—2024

personType:"deptPerson",

roles:

"110414316670487a830302c6cb0b377a,bcf4575777b848a2ac2895d82114c0b8,4077f1d749ea422fafb3dd

8edf62c520,4a9ab012256244359d3784ef39571421,33cf7e2e32fd4c1f880dd5c18062a6b4,efcb36000f58

463995bf2b4ca3d668f8,81071e045d1844e783b07f6fa1f54fec,13fcfb1ef8d14d60922b894457fb2ac9,6c

23871ef38842d4b88a10f3996462f5,b0f5787cd3834fa9b54f61420b7fe3e9,0ac46d6772734d33a8c0cf279

1fb38df,9b104ecf820f453d8840a35b7253249e,636559a379a74dc09024065094b85c43,fc188d02dc30491

b8902f839c7385a58,fe3a4bbbbc5d4c55890ed61e434235b6,fbc01a1a4f754331bbab077db661eb16,7c1a4

3e45c034752a9e2c781d0df7cbe,761132882ee949438dc975413490283c,32bdfd9969f343988e6516c6c4a4

2605,117c27048dfc4af98841b4771f4a64eb",

sex:1,

tenantLoginName:"risesoft",

tenantManager:true,

tenantName:"XX公司",

service:"https://localhost:port/platform",

id:"張三",

client_id:"clientid"

}

7.4刷新訪問令牌

接口地址：https://ip:port/sso/oauth2.0/accessToken

請求方法：POST

描述：當訪問令牌過期了可通過refresh_token去獲取新的訪問令牌

請求參數(shù)：

參數(shù)名描述

grant_type授權(quán)類型為固定值refresh_token

client_id申請的客戶端id

client_secret申請的客戶端密鑰

refresh_token刷新令牌

響應(yīng)示例：

{

access_token:"AT-80-YwO-UIy7ZkDaNHPQRZv5WE8nSFsBiOn7",

refresh_token:"RT-80-3DQO8G4lkqa9fgMGhVVbrRZqGEPnhakP",

token_type:"bearer",

expires_in:28800,

scope:""

}

7.5訪問令牌校驗

7

T/ZGCSA1.7—2024

接口地址：https://ip:port/sso/oauth2.0/introspect

請求方法：POST

描述：查詢訪問令牌access_token的狀態(tài)，其中應(yīng)用的憑證client_id和client_secret需以

BasicAuth的形式提供

請求參數(shù)：

參數(shù)名描述

token訪問令牌access_token

請求頭：

參數(shù)名描述

應(yīng)用的憑證，參數(shù)值為Basic<Auth>,其中<Auth>為經(jīng)過base64編碼的

Authorization

client_id和client_secret，即base64_encode(client_id:client_secret)

響應(yīng)示例：

{

"active":true,

"attr":

"{\"tenantLoginName\":\"risesoft\",\"oauthClientId\":\"clientid\",\"loginType\":\"login

Name\",\"roles\":\"035fc633bc624890bcefdceebf86e487,b3a518829f2443ee806f9d8331017b48,093e

6250f1fd44e0bc1312322e8271f6,5c460016c5c44412ac629a8ff2e7d5cf\",\"dn\":\"cn=張三,o=XX公

司

\",\"parentID\":\"4a725fe6f01b41ee9d5670a8bb2702de\",\"IDNum\":\"\",\"password\":\"3D:4F:

2B:F0:7D:C1:BE:38:B2:0C:D6:E4:69:49:A1:07:1F:9D:0E:3D\",\"tenantName\":\"XX公司

\",\"loginName\":\"swadmin\",\"tenantID\":\"8b60c9b967c947e6b6b5a5fe37525cdb\",

\"personID\":\"8ae05acc257b4a499b5d153db99a2e77\",\"originalID\":\"\",\"personType\":\"\",

\"tenantManager\":true,\"email\":\"\",\"original\":1,\"CAID\":\"_0000000000000000000000\",

\"sex\":0,\"guidPath\":\"4a725fe6f01b41ee9d5670a8bb2702de,8ae05acc257b4a499b5d153db99a2e7

7\",\"mobile\":\"1304*****11\",\"isValidateIE\":\"true\",\"positionId\":\"07a05d2e9b194c3

78ec7f43b07609732\",\"name\":\"張三\",\"avator