Hướng dẫn tích hợp SSO VNPT-IDP

HƯỚNG DẪN TÍCH HỢP SSO VÀ CÁC API SỬ DỤNG

1. Giới thiệu.................................................................................................................................2
2. Danh sách endpoint tích hợp SSO...........................................................................................2
3. Hướng dẫn tích hợp SSO.........................................................................................................2
3.1. Mô tả luồng SSO..............................................................................................................3
3.2. Cách đăng ký sử dụng dịch vụ SSO.................................................................................4
4. Mô tả chi tiết api......................................................................................................................9
4.1. API yêu cầu xác thực tài khoản........................................................................................9
4.2. Lấy access token.............................................................................................................10
4.3. Lấy thông tin user...........................................................................................................14
4.4. Logout.............................................................................................................................15
4.5. Revoke............................................................................................................................16
4.6. Check valid token...........................................................................................................16
4.7. Lấy thông tin JWT key...................................................................................................18
4.8. Lấy thông tin cấu hình oauth2, OIDC............................................................................18
4.9. Kiểm tra session..............................................................................................................18

1|Page
 Hướng dẫn tích hợp SSO VNPT-IDP

1. Giới thiệu

Tài liệu này mô tả các api, cách sử dụng dùng trong SSO
2. Danh sách endpoint tích hợp SSO

- IP-PORT-SERVER = domain site xác thực

ST EndPoint Mô tả
T
1 https://IP-PORT-SERVER/oauth2/ API yêu cầu xác thực tài khoản
authorize
2 https://IP-PORT-SERVER/oauth2/ API lấy accessToken từ authorization
token code hoặc refresh token hoặc qua một số
loại grant type (password, credential và
device code)
3 https://IP-PORT-SERVER/oauth2/ Thu hồi access token
revoke
4 https://IP-PORT-SERVER/oauth2/ Lấy thông tin người dùng
userinfo
5 https://IP-PORT-SERVER/oidc/ Logout
logout
6 https://IP-PORT-SERVER/oauth2/ Check validate token
introspect
7 https://IP-PORT-SERVER/oauth2/ JWT key dùng để check signature trong
jwks JWT
8 https:// Kiểm tra session
IP-PORT-SERVER/oidc/checksessio
n
9 https://IP-PORT-SERVER/oauth2/ Thông tin cấu hình oauth2/OIDC
oidcdiscovery/.well-known/openid-
configuration
10 https:// ISS: Thông tin nhà cung cấp token
IP-PORT-SERVER/oauth2/token

3. Hướng dẫn tích hợp SSO

Note: Hướng dẫn theo luồng grant type: authorization code

2|Page
 Hướng dẫn tích hợp SSO VNPT-IDP

Note: VNPT-IDP hệ thống xác thực Sso

3.1. Mô tả luồng SSO

- Bước 1: Hệ thống dịch vụ kiểm tra người dùng đã từng xác thực bằng tài
khoản VNPT-IDP hay chưa (bằng cách kiểm tra Id Token và Access Token
(có thể đã lưu như mô tả trong bước 9) đã được lưu trong session của trang
web của Hệ thống dịch vụ hay chưa). Nếu chưa có trong session, chuyển sang
bước 2. Nếu đã có trong session, chuyển sang bước 8.
- Bước 2: Hệ thống dịch vụ chuyển lại (redirect) về trang xác thực SSO
o Chú ý: Tham khảo url trang xác thực của VNPT-IDP ở mục 3.2.3 và giá
trị client id, client secret ở mục 3.2.2
- Bước 3: VNPT-IDP thực hiện xác thực người dùng trên trang của VNPT-IDP
và tạo mã xác thực.
- Bước 4: VNPT-IDP chuyển lại sang hệ thống dịch vụ cùng với tham số mã
xác thực (code).
o Chú ý: hệ thống dịch vụ cần cung cấp đường link callback url như trên
(tham khảo ở mục 3.2.1)
- Bước 5: Hệ thống dịch vụ gửi mã xác thực vào cổng VNPT-IDP để lấy
Access Token và Id Token.
o Chú ý: Gọi get access token api (tham khảo ở mục 3.2.4)
3|Page
 Hướng dẫn tích hợp SSO VNPT-IDP

- Bước 6: Cổng VNPT-IDP trả Access Token, Id token cho Hệ thống dịch vụ
- Bước 7: Hệ thống dịch vụ thực hiện kiểm tra tính hợp lệ Access Token, Id
Token như Access Token còn hạn sử dụng hay không so với thời gian (giờ)
của hệ thống dịch vụ, và lưu lại thông tin tài khoản sso của VNPT-IDP trên
session trang của hệ thống dịch vụ (Access Token, Id Token)
- Bước 8: Hệ thống dịch vụ thực hiện lấy thông tin người sử dụng từ hệ thống
VNPT-IDP (chi tiết tại bảng dưới) bằng Access Token
o Hệ thống dịch vụ gọi để lấy thông tin người sử dụng (tham khảo mục
3.2.5)
- Bước 9: Hệ thống VNPT-IDP thực hiện trả thông tin người sử dụng.

- Bước 10: Hệ thống dịch vụ sử dụng email, phone,.. trong thông tin người sử
dụng để tìm kiếm tài khoản tương ứng của người sử dụng trên Hệ thống dịch
vụ (Trí Nam xây dựng). Nếu email ,phone,... đã được mapping tương ứng với
một tài khoản trên Hệ thống dịch vụ => Chuyển sang bước 13. Nếu chưa được
mapping => Chuyển sang bước 11
- Bước 11: Hệ thống dịch vụ yêu cầu người sử dụng đăng nhập bằng tài khoản
của hệ thống dịch vụ. Nếu người dùng đăng nhập thành công chuyển sang
bước 12. Nếu người dùng chưa có tài khoản => Hệ thống dịch vụ tự động tạo
tài khoản ở Hệ thống dịch vụ cho người sử dụng dựa vào các thông tin do
VNPT-IDP gửi về hoặc hiển thị màn hình yêu cầu người sử dụng xác nhận
thông tin và nhập thêm các thông tin khác cần thiết để tạo tài khoản ở Hệ
thống dịch vụ.
- Bước 12: Hệ thống dịch vụ mapping một trường thông tin của người sử dụng
với tài khoản của Hệ thống dịch vụ.
- Bước 13: Hệ thống dịch vụ cho phép người sử dụng thực hiện dịch vụ công
trên Hệ thống dịch vụ.

3.2. Cách đăng ký sử dụng dịch vụ SSO

3.2.1. SP (đơn vị đang cần tích hợp SSO)

4|Page
 Hướng dẫn tích hợp SSO VNPT-IDP

- Tạo URL callback trên Hệ thống dịch vụ (Service Provider)

- Mục đích: Lấy authorization code sau khi người dùng đăng nhập
- Đường dẫn: callback url
- Method: GET
- Header:
- Input: Request Params
o code : Mã authorization code
VD:

URL-CALLBACL/redirect?
code=g0ZGZmNjVmOWIjNTk2NTk4ZTYyZGI3&state=xcoiv98y2kd22v
usuye3kch

3.2.2. SP đăng ký dịch vụ SSO trên VNPT-IDP (liên lạc với nhân viên hỗ trợ tích hợp
của hệ thống VNPT-IDP qua đầu mối hỗ trợ)

- Khai báo cấu hình SSO cho SP trên con VNPT-IDP (bao gồm url callback tạo ở
bước 7.1)
- Lấy thông tin client ID và secret ID
3.2.3. Server SP - khi cần xác thực người dùng- sẽ redirect tới trang xác thực của VNPT-
IDP
- Đường dẫn: https://IP-PORT-SERVER/oauth2/authorize
- Method: GET
- Input: Request Param
o response_type=code : (Required) Mô tả loại ủy quyền nào. ở đây là
authorization code. Hoặc token đối với implicit.
o client_id : (Required)định danh cho 1 ứng dụng
o redirect_uri : (Required) url callback sau khi người dùng chấp nhận ủy quyền
thành công
o scope : (Required) Danh sách các quyền mà ứng dụng yêu cầu. Bắt buộc phải
có openid.
o state : (optional) ứng dụng gửi lên 1 mã random. Mã này sẽ được gửi lại
trong step url callback để ứng dụng xác nhận đúng server mình gửi yêu cầu
(CSRF attack)
o acr_values : (optional) Quyền truy cập ( LOA1 > LOA4 ).
VD:

5|Page
 Hướng dẫn tích hợp SSO VNPT-IDP

https://login.laocai.gov.vn/oauth2/authorize?
response_type=code
&client_id=UrLqW3r7VnBYcSMRMwuijHAw9KAa
&redirect_uri=https://login.laocai.gov.vn/apps/login/
callback
&scope=openid

Chú ý: Nếu muốn thêm nhiều scope thì các scope cách nhau dấu +.
VD: scope=openid+email+…

3.2.4. Sau khi nhận được Auth Code, Server SP gọi API Get access token
Sau khi đăng nhập và đồng ý chấp nhận chia sẻ thuộc tính thành công thì VNPT-
IDP sẽ gọi lại url callback của SP để trả lại authorization code
SP sử dụng authorization code để call API lấy access token:
 Input:
 Đường dẫn: https://IP-PORT-SERVER/oauth2/token
 Method: POST
 Header:
o Content-Type: application/x-www-form-urlencoded
 Body: Query Params
o grant_type=authorization_code
o code : Mã authorization code
o redirect_uri :
o client_id: client id của ứng dụng
o client_secret : là key bí mật của ứng dụng. Giá trị này được gửi lên để
server xác thực có chính xác là ứng dụng đó hay không hay. Phòng
tránh kẻ tấn công có được authorization code ở bước trước đó
VD:

6|Page
 Hướng dẫn tích hợp SSO VNPT-IDP

 Output:
HTTP/1.1 200 OK
{
"access_token": "11e6bccd-e16a-35a6-98d2-c7fe594e0045",
"refresh_token": "0d41ffa7-f942-38fa-94cf-25a2cc60cd5e",
"scope": "openid",
"id_token":
"eyJ4NXQiOiJOVGhsWm1GaE4yTmpZamt4TmpoalpEVmxOekZsTURReE9UZGpZel
UzTkRVM05UaGpNelF6WkEiLCJraWQiOiJOVGhsWm1GaE4yTmpZamt4TmpoalpE
VmxOekZsTURReE9UZGpZelUzTkRVM05UaGpNelF6WkEiLCJhbGciOiJSUzI1NiJ9.
eyJhdF9oYXNoIjoiVkVVVlZaTjh1TURsby1nWmVuMlJIdyIsImF1ZCI6Inp1SDlqRXJt
ZVZmajlxS0p1cmhWMV9XUmg4Y2EiLCJzdWIiOiJhZG1pbiIsIm5iZiI6MTU2MjkyMj
g4NywiYXpwIjoienVIOWpFcm1lVmZqOXFLSnVyaFYxX1dSaDhjYSIsImFtciI6WyJw
YXNzd29yZCJdLCJpc3MiOiJodHRwczpcL1wvbWNhLnZucHQtY2Eudm46OTQ0M1
wvb2F1dGgyXC90b2tlbiIsImV4cCI6MTU2MjkyNjQ4NywiaWF0IjoxNTYyOTIyODg3
fQ.HvoJ5OzOy4FnEkqY2YSjr5trG19UYz2D8izHuvSu5l0ywiQOEuVjZU3fxF9m4QcI
MArRLyGO97JWAyZIBiuL1-
uwJNvqLdqbh8PCuSrPIErfy19oXzNpStSMgIzEi4ky1VRodt_KmjnUIA0cBzrE1-
IQycy8H9fNnUzUjG3qzxg",
"token_type": "Bearer",
"expires_in": 3600
}

3.2.5. Server SP gọi API Get user info (tùy chọn, nếu muốn lấy dữ liệu thông tin người
dùng từ S)
- Có accsess token tiến hành call api Get userinfo.
- Input:
- Đường dẫn: https://IP-PORT-SERVER/oauth2/userinfo
- Method: POST
- Header:
o Accept: application/json
o Content-Type: application/x-www-form-urlencoded
o Authorization: Bearer <access token>
- Body: none
- VD:

7|Page
 Hướng dẫn tích hợp SSO VNPT-IDP

- Output: thông tin người dung – gồm thuộc tính cơ bản của user (lưu ý là chỉ
những trường có dữ liệu thì VNPT-IDPmới trả về thông tin).
VD:
{
"sub": "admin"
}

STT Tên Định Mô tả Yêu Ghi chú

Trường dạng cầu

1 sub String

2 Phone_num String Số điện thoại

ber

3 email String Địa chỉ email

Bảng : Các trường kết quả lấy thông tin người dùng

8|Page
 Hướng dẫn tích hợp SSO VNPT-IDP

3.2.6. Server SP gọi Revoke token (nếu muốn logout)

- Người dùng logout khỏi ứng dụng SP thì sử dụng API revoke token để thu hồi
lại access token đã cấp cho SP trước đó:
- Đường dẫn: https://IP-PORT-SERVER/oauth2/revoke
- Method: POST
- Header:
o Content-Type: application/x-www-form-urlencoded
- Input: Query Params
o token: token muốn hủy
o token_type_hint = access_token
o client_id: client id của ứng dụng
o client_secret : là key bí mật của ứng dụng

4. Mô tả chi tiết api

4.1. API yêu cầu xác thực tài khoản

- Đường dẫn: https://IP-PORT-SERVER/oauth2/authorize

- Method: GET
- Input: Request Param
o response_type=code : (Required) Mô tả loại ủy quyền nào. ở đây là authorization
code. Hoặc token đối với implicit.
o client_id : (Required)định danh cho 1 ứng dụng
o redirect_uri : (Required) url callback sau khi người dùng chấp nhận ủy quyền
thành công
o scope : (Required) Danh sách các quyền mà ứng dụng yêu cầu
o state : (optional) ứng dụng gửi lên 1 đoạn mã json như sau
{"mã ngẫu nhiên server SP tự sinh":{ 'redirectUrl': '/protectedResource',
'expiresOn': 'thời gian mã ngẫu nhiên hết hiệu lực do SP quy định'}}
Note: Với grant type authorization code dùng cho trường hợp là web và native app.
Implicit dùng cho trường hợp ứng dụng viết bằng client như hybrid app

9|Page
 Hướng dẫn tích hợp SSO VNPT-IDP

4.2. Lấy access token

4.2.1. Lấy qua grant type authorization code

 Input:
- Đường dẫn: https://IP-PORT-SERVER/oauth2/token
- Method: POST
- Header:
o Content-Type: application/x-www-form-urlencoded
- Body: x-www-form-urlencoded
o grant_type=authorization_code
o code : Mã authorization code
o redirect_uri :
o client_id: client id của ứng dụng
o client_secret : là key bí mật của ứng dụng. Giá trị này được gửi lên để server xác
thực có chính xác là ứng dụng đó hay không hay. Phòng tránh kẻ tấn công có được
authorization code ở bước trước đó
VD:

- Output:
{
"access_token": "442fb30c-9a76-344b-b2b8-cc1b6c04cc13",
"refresh_token": "0c7a5de2-fdaa-326b-acb3-7323a0769e7f",

10 | P a g e
 Hướng dẫn tích hợp SSO VNPT-IDP

"scope": "openid",
"id_token": "eyJ4NXQiOiJOek01T0RNd1kyVmhaRGMwWm1ZMU1UVm1aR0l4T1dObU1HWmlOalZqTXpSa
05tWm1ZVE14TXciLCJraWQiOiJOek01T0RNd1kyVmhaRGMwWm1ZMU1UVm1aR0l4T1dObU1HWmlOalZqTXpSa05
tWm1ZVE14TXciLCJhbGciOiJSUzI1NiJ9.eyJhdF9oYXNoIjoiT2tLVV8xdlV4VXZCZTI0NktJM0ZSdyIsImF1
ZCI6Im1NZzNwSWZDOHp2VXpGeGp6TGI0c0tUZXpzWWEiLCJjX2hhc2giOiJaRHZYYjdaQ2tTNkJxVWs0dUQydU
d3Iiwic3ViIjoiYnVpcXVhbmdodXkiLCJuYmYiOjE1ODcxMDU1NzgsImF6cCI6Im1NZzNwSWZDOHp2VXpGeGp6
TGI0c0tUZXpzWWEiLCJhbXIiOlsiQmFzaWNBdXRoZW50aWNhdG9yIl0sImlzcyI6Imh0dHBzOlwvXC9sb2dpbi
55ZW5iYWkuZ292LnZuOjQ0M1wvb2F1dGgyXC90b2tlbiIsImV4cCI6MTU4NzEwOTE3OCwiaWF0IjoxNTg3MTA1
NTc4LCJzaWQiOiI2ZmMxZDM4OC0xZTJhLTQ2NjQtYmM1MC1mNTdhYTUyODJkMWUifQ.Eak0L7mypgncad1Ptco
SRpoEzTlQPt1vqH61z70vHeysr_sAmC0zpZMNXBA2EiI79veC4oocQc85O41hLsJdGJXxSHE2LebVUtkuNb1Sn
diQzo9bZRpNc39ixx4WYhk19MTgkPg8KYxC9fl4Mcre8V-
LQLl7fLL1Jd9UFvw1ll3v0ec8mlZ8maC6tmV24zAdumEu8n_sDS71-m2i32kJ0H7uny91uMdp6Yc5Ro-7yO-
dmAR6eh1Z3QNXJROgd3zFvgRiSe3NvNeilIUaaxIiRTR1ow2xGAVDBnnDlTpndGC0J39Oo8in3FVSk2Fotqry_
5YM3-vQeK49A3GDwoMC0w",
"token_type": "Bearer",
"expires_in": 3600
}
4.2.2. Lấy qua grant type password

 Input:
- Đường dẫn: https://IP-PORT-SERVER/oauth2/token
- Method: POST
- Header:
o Content-Type: application/x-www-form-urlencoded
- Body: x-www-form-urlencoded
o grant_type=password
o username = xxx
o password = xxx
o client_id: client id của ứng dụng
o client_secret : là key bí mật của ứng dụng. Giá trị này được gửi lên để server xác
thực có chính xác là ứng dụng đó hay không hay. Phòng tránh kẻ tấn công có
được authorization code ở bước trước đó
o scope : (Required) Danh sách các quyền mà ứng dụng yêu cầu
VD:

11 | P a g e
 Hướng dẫn tích hợp SSO VNPT-IDP

Output:
{
"access_token": "a4c2987c-d01e-3242-a637-990ec6c74dbf",
"refresh_token": "627e4302-144e-387c-940e-971b8620b934",
"scope": "openid",
"id_token": "eyJ4NXQiOiJZalUyTkRVM01tRXdOek0xTnpCa1pUZzJOMkZtTXpZek9UWm1ZakUxT0RVN
VlUSTVZV1EwTmciLCJraWQiOiJZalUyTkRVM01tRXdOek0xTnpCa1pUZzJOMkZtTXpZek9UWm1ZakUxT0RVNVl
USTVZV1EwTmciLCJhbGciOiJSUzI1NiJ9.eyJhdF9oYXNoIjoiMU55cUUxNDNBdFBMS0Y2MENfcmdyZyIsImF1
ZCI6IlVyTHFXM3I3Vm5CWWNTTVJNd3VpakhBdzlLQWEiLCJzdWIiOiJhZG1pbiIsIm5iZiI6MTU4OTUzNzg4OS
wiYXpwIjoiVXJMcVczcjdWbkJZY1NNUk13dWlqSEF3OUtBYSIsImFtciI6WyJwYXNzd29yZCJdLCJpc3MiOiJo
dHRwczpcL1wvbG9naW4ubGFvY2FpLmdvdi52bjo0NDNcL29hdXRoMlwvdG9rZW4iLCJleHAiOjE1ODk1NDE0OD
ksImlhdCI6MTU4OTUzNzg4OX0.aDnm3lgXH5K5EFl4RHz8qNF6B3J-VuG-_jmgjacH2XBmQWes9R3aK-
O3DDk7e39qxUrQ1rllUoPq_3Pz5IX5Te3zm7Ik9gs4-0YMxndXW1vQETSJ8caqXqHI_eK-eS-
wLyZDNA_BFPjFQUd_mmyKbfYVCfHcPgYikF41QNHHzIesYjyIBBaOPMyy3etNiHKfoGdVLe1pTByRpNqbQrxeq
3FcVBeI7B3-EmIyWJrUJNOeNw-1OXg4PZ-xquy3Dz-
6d0CakcnXrbDRxMctSi4hJ2z92JVkFJKWwBtdOHI_zBoyvP-APoCUsrXFHar3XTfldESycM-
x8V4u0la7M9cUZw",
"token_type": "Bearer",
"expires_in": 952
}

4.2.3. Refresh token

Mục đích: api này dung để sinh access token mới.
 Input:
- Đường dẫn: https://IP-PORT-SERVER/oauth2/token
- Method: POST
- Header:
o Content-Type: application/x-www-form-urlencoded
- Body:
o Grant_type = refresh_token
o Refresh_token = xxxxx: đc trả về khi gọi api access token
o Client_id: client id của ứng dụng
o Client_secret: là key bí mật của ứng dụng

- VD :

 Output: như authorization code (Mục 8.2.1)

12 | P a g e
 Hướng dẫn tích hợp SSO VNPT-IDP

4.3. Lấy thông tin user

 Input:
- Đường dẫn: https://IP-PORT-SERVER/oauth2/userinfo
- Method: POST
- Header:
o Accept: application/json
o Content-Type: application/x-www-form-urlencoded
o Authorization: Bearer <access token>
- Body: Null
- VD:

- Output: thông tin người dùng

-
{
"sub": "admin"
}
4.4. Logout

- Đường dẫn: https://IP-PORT-SERVER/oidc/logout

- Method: GET
- Header:
- Input: Query Params
o id_token_hint: (optional) id_token được trả lại bởi identity provider khi gọi api
/oauth2/token
o post_logout_redirect_uri: (optional) redirect URL được chuyển tới khi logout
thành công. Cần đăng ký cấu hình url logout trước cho quản trị hệ thống.
o state: (optional)
VD : https://login.laocai.gov.vn/oidc/logout

13 | P a g e
 Hướng dẫn tích hợp SSO VNPT-IDP

- Output: thông báo đăng xuất thành công hoặc redirect về uri redirect(trong trường
hợp request có id_token_hint và post_logout_redirect_uri)
4.5. Revoke

Input:
- Đường dẫn: https://IP-PORT-SERVER/oauth2/revoke
- Method: POST
- Authorization:

- Header:
o Content-Type: application/x-www-form-urlencoded
o
- Body:
o token: token muốn hủy
o token_type_hint = access_token
o client_id: client id của ứng dụng
o client_secret : là key bí mật của ứng dụng
VD :

- Output:

14 | P a g e
 Hướng dẫn tích hợp SSO VNPT-IDP

4.6. Check valid token

- Đường dẫn: https://IP-PORT-SERVER/oauth2/introspect

- Method: POST
- Header:
o Content-Type: application/x-www-form-urlencoded
o Authentication: Basic Auth - dạng username-password được set quyền quản
trị sp.

- Body: Query Params

o Access token: Nhận được sau khi gọi api lấy access
token

- Output:
{
"nbf": 1562922887,
"scope": "openid",
"active": true,
"token_type": "Bearer",
"exp": 1562926487,
"iat": 1562922887,
"client_id": "zuH9jErmeVfj9qKJurhV1_WRh8ca",

15 | P a g e
 Hướng dẫn tích hợp SSO VNPT-IDP

"username": "admin@carbon.super"
}

4.7. Lấy thông tin JWT key

- Đường dẫn: https://IP-PORT-SERVER/oauth2/jwks

- Method: GET
4.8. Lấy thông tin cấu hình oauth2, OIDC

- Đường dẫn:
https://IP-PORT-SERVER/oauth2/oidcdiscovery/.well-known/o
penid-configuration
- Method: GET
4.9. Kiểm tra session

- Đường dẫn: https://IP-PORT-SERVER/oidc/checksession

- Method: GET
- Input: Request Params
client_id: client id của ứng dụng

5. Back-channel logout

OpenID Connect back-channel logout là một tính năng cho phép người dùng đăng xuất ra khỏi
một client application/ một nhóm client application bằng cách giao tiếp thông qua request logout
giữa client application và máy chủ xác thực.
Yêu cầu các SP phải cung cấp một API có phương thức là POST cho SSO, khi có SP logout SSO
sẽ gọi API đó và gửi kèm một logout_token cho SP, SP dự vào logout_token này để thực
hiện logout ra khỏi hệ thống. Chi tiết tham khảo thêm tài liệu “Tài liệu hướng dẫn back-
channel logout.docx”

16 | P a g e