SSO Bridge

Đăng nhập một lần duy nhất trên toàn bộ sub-domains.

Giới thiệu

Bằng cách thiết lập một shared_ecn_session vào cookie của wildcard domain, các sub-domain có thể sử dụng shared_ecn_session này để kiểm tra phiên đăng nhập và lấy thông tin cơ bản của người dùng.

Sơ đồ hoạt động

Đây là sequence diagram mô tả cách người dùng đăng nhập vào hệ thống và cách hệ thống xác thực người dùng

work-flow

Danh sách domain mà GG đã triển khai

Domain
*.vnggames.com
*.zing.vn
*.vng.games

🚨 Lưu ý: Nếu dịch vụ tích hợp không triển khai trên các domain trên, vui lòng liên hệ qua email BaoNQ3 để được hướng dẫn tích hợp SSO Bridge

Tích hợp

1. Đăng ký thông tin tích hợp

Để tích hợp với SSO Bridge, hệ thống tích hợp cần đăng ký thông tin tích hợp, bạn vui lòng liên hệ qua email BaoNQ3 và cung cấp các thông tin sau:

Tham số yêu cầu	Kiểu dữ liệu	Tính bắt buộc	Mô tả
Domain	string	có	Domain cần tích hợp vào SSO Bridge. Ví dụ: `pay.zing.vn`

VGA sẽ cung cấp thông tin tích hợp bao gồm:

Tham số cung cấp	Kiểu dữ liệu	Tính bắt buộc	Mô tả
`service-id`	string	có	Dùng để định danh và xác định wildcard domain. Client dùng `service-id` để redirect người dùng đăng nhập với SSO Bridge.
`api-key`	string	có	Dùng để định danh yêu cầu tới Backend service. Client cần truyền thông tin này ở header cho yêu cầu tới backend API.
`secret-key`	string	có	Dùng để xác thực yêu cầu tới Backend service. Client cần dùng `secret-key` này để ký yêu cầu tới backend API
`bridge-domain`	string	có	Domain dùng để điều hướng đăng nhập và lấy thông tin người dùng.

2. Điều hướng đăng nhập

Điều hướng người dùng tới đường dẫn sau với các tham số yêu cầu để bắt đầu quá trình đăng nhập.

URL: https://{{bridge-domain}}/sso/bridge

Method: GET

Tham số

Tham số	Kiểu dữ liệu	Tính bắt buộc	Mô tả
service_id	string	có	`service-id` định danh hệ thống tích hợp được cung cấp bởi VGA .
redirect_uri	string	có	Điều hướng người dùng sau khi đăng nhập thành công. Đường dẫn điều hướng phải có wildcard domain trùng với wildcard domain đã đăng ký của `service-id`
lang	string	không	Ngôn ngữ mong muốn theo chuẩn ISO_639-1. Nếu tham số không được chỉ đinh, SSO Bridge sẽ sử dụng ngôn ngữ được người dùng lựa chọn trước đó hoặc ngôn ngữ mặc định là `en`
target_client_id	string	không	`target_client_id` được dùng trong trường hợp muốn điều hướng đăng nhập bằng kênh `protected_guest`, muốn chỉ định cụ thể client cần đăng nhập, tham số client này phải thuộc loại `legacy`
auth_method	string	không	Dùng khi đăng nhập vào hệ thống VGA thông qua các kênh social, các giá trị tương ứng như sau: - Apple: apple - Google: google - Facebook: facebook - ZingID: zing - VGA Guest: guest - Protected Guest: protected_guest

Ví dụ:

curl --vvv --request GET 'https://stg-sso.zing.vn/sso/bridge?service_id=zing&redirect_uri=https://pay.zing.vn&lang=vi&auth_method=protected_guest&target_client_id=984745454866530308'

TH1: không sử dụng các số tuỳ chọn

target_client_id và auth method Sau khi người dùng đăng nhập thành công, SSO Bridge sẽ điều hướng quay lại redirect_uri, đồng thời thiết lập một shared_ecn_session vào cookie cho mục đích chia sẻ phiên đăng nhập. Tham số lang có thể được thêm vào nếu người dùng thay đổi ngôn ngữ.

TH2: sử dụng tham số target_client_id và auth method

Người dùng sẽ được điều hướng đến kênh đăng nhập bằng protected_guest trên game có client_id là 984745454866530308. Sau khi người dùng đăng nhập thành công, SSO Bridge sẽ điều hướng quay lại redirect_uri, đồng thời thiết lập một shared_ecn_session vào cookie cho mục đích chia sẻ phiên đăng nhập. Tham số lang có thể được thêm vào nếu người dùng thay đổi ngôn ngữ.

3. Kiểm tra phiên đăng nhập

Sử dụng để kiểm tra phiên đăng nhập của người dùng. API được sử dụng cho Backend service. Whitelist IP có thể được thiết lập.

🚨 Lưu ý: Hiện tại phiên đăng nhập của người dùng có giá trị hiệu lực trong vòng 2 tuần và có thể được thay đổi theo yêu cầu của hệ thống

Sử dụng SSO Bridge SDK

Sử dụng API:

URL: https://{{bridge-domain}}/api/v1/shared-session/verify

Method: GET

Header

Tham số	Kiểu dữ liệu	Tính bắt buộc	Mô tả
service-id	chuỗi (string)	có	`service-id` định danh hệ thống tích hợp được cung cấp bởi VGA .
session-id	chuỗi (string)	có	Giá trị của cookie `shared_ecn_session` từ wildcard domain.
api-key	chuỗi (string)	có	`api-key` định danh Backend service được cung cấp bởi VGA .
sign	chuỗi (string)	có	Chuỗi băm để xác thực yêu cầu.
`sign=Sha256(session-id + current_timestamp + secret-key)` .

Tham số

Tham số	Kiểu dữ liệu	Tính bắt buộc	Mô tả
current_timestamp	chuỗi (string)	có	Current UTC Milliseconds của hệ thống, yêu cầu vượt quá 5 phút có thể bị từ chối.
client_id	chuỗi (string)	không	Thông tin client_id cụ thể, khi có truyền tham số này có nghĩa là muốn lấy thêm thông tin về user_id trên client_id này

Response

HTTP Status:
200: Yêu cầu thành công.
400: Nếu sign không hợp lệ, hoặc yêu cầu quá thời gian.
401: Nếu phiên đăng nhập hiện tại hết hạn hoặc không hợp lệ.
403: Nếu api-key hoặc service-id không hợp lệ.
Body:
Thành công:

{
  "status": true,
  "errorCode": "success",
  "data": {
    "ggId": "3f7639b24f6fb981",
    "signInMethod": 8,
    "sessionClientId": "0",
    "clientId": "984745454866530308",
    "userId": "1130759147585343488"
  }
}

Trong đó

sessionClientId: là thông tin của client_id tạo nên shared_ecn_session hiện tại.
clientId: Được trả về trong trường hợp có truyền client_id trong param, nếu clientId không tồn tại trong hệ thống, sẽ trả về rỗng.
userId: Được trả về trong trường hợp có truyền client_id trong param, sẽ trả về UserId trong game trên client_id đó.
signInMethod: Kênh đăng nhập được sử dụng để tạo nên shared_ecn_session hiện tại.
- 1: Email
- 2: PhoneNumber
- 3: Username
- 4: Facebook
- 5: Google
- 6: Apple
- 7: Zing
- 8: Protected Guest
Thất bại:

{
  "status": false,
  "errorCode": "invalid_request",
  "errorMessage": "Invalid request"
}

4. Lấy thông tin người dùng

Tích hợp widget

Sử dụng API

Lấy thông tin người dùng với phiên đăng nhập hiện tại.

URL: https://{{bridge-domain}}/api/v1/users/basic-profile

Method: GET

Cookie: Enable submit request within Cookies

Response

HTTP Status:
200: Yêu cầu thành công.
401: Nếu phiên đăng nhập hiện tại hết hạn hoặc không hợp lệ.
404: Nếu thông tin user không tồn tại.
Body:
Thành công:

{
  "status": true,
  "errorCode": "success",
  "data": {
    "ggId": "string",
    "avatar": "string",
    "displayName": "string",
    "territory": "string",
    "emailVerified": "bool", // nullable
    "phoneNumberVerified": "bool", // nullable
    "sessionClientInfo": {
      "signInMethod": 4,
      "sessionClientId": "",
      "sessionTargetClientId": "984745454866530308",
      "sessionClientName": "2048",
      "sessionClientAvatarUrl": "https://cdn.tgdd.vn/GameApp/4/249808/Screentshots/persona-5-30-08-2021-1.jpg"
    },
    "gameAccountInfo": {
      "clientId": "984745454866530309",
      "userId": "1712371264936701952",
      "clientName": "2049",
      "clientAvatarUrl": "https://cdn.tgdd.vn/GameApp/4/249808/Screentshots/persona-5-30-08-2021-1.jpg"
    }
  }
}

emailVerified, phoneNumberVerified: chứa thông tin để xác định xem số điện thoại hoặc email của người đã được xác nhận hay chưa. Lưu ý, 2 trường này là nullable và có thể sẽ không được trả về.
sessionClientInfo: chứa các thông tin liên quan đến nguồn tạo ra shared_ecn_session. Bao gồm
- signInMethod: Kênh đăng nhập được sử dụng để tạo nên shared_ecn_session hiện tại.
- sessionClientId: thông tin client_id trong bước tạo shared_ecn_session, nếu user đăng nhập bằng cách kênh social như facebook, google, apple thì client_id sẽ là clientId của GG, nếu user đăng nhập bằng kênh protected_guest thì client_id = target_client_id.
- sessionClientName và sessionClientAvatarUrl: tên và logo của client được cấu hình trong hệ thống.
gameAccountInfo:

Nếu không có tham số client_id trong request, sẽ trả về object null.

nếu có truyền thêm tham số client_id trong request, hệ thống sẽ kiểm tra và trả thêm về thông tin game account trên client_id đó.

client_id: dựa trên client_id trên tham só, nếu không hợp lệ sẽ trả về rỗng.
user_id: Được trả về trong trường hợp có truyền client_id trong tham số, sẽ trả về UserId trong game trên client_id đó, nếu trả về rỗng thì có nghĩa là user chưa chơi game trên client_id được truyền vào.
clientName và clientAvatarUrl: thông tin clientName và logo của game được cấu hình trong hệ thống.
Thất bại:

{
  "status": false,
  "errorCode": "invalid_request",
  "errorMessage": "Invalid request"
}

5. Đăng xuất người dùng

Đăng xuất người dùng khỏi hệ thống.

URL: https://{{bridge-domain}}/sso/bridge/sign-out

Method: GET

Cookie: Enable submit request within Cookies

Response

HTTP Status:
200: Yêu cầu thành công.
401: Nếu phiên đăng nhập hiện tại hết hạn hoặc không hợp lệ.
Body:
Thành công:

{
  "status": true,
  "errorCode": "success"
}

Thất bại:

{
  "status": false,
  "errorCode": "unauthorized",
  "errorMessage": "Invalid session"
}

Mã lỗi

Mã lỗi	Mô tả
success	Thành công
invalid_request	Request thiếu một tham số bắt buộc, hoặc một giá trị tham số không hợp lệ, không đúng định dạng.
unauthorized	Phiên đăng nhập không hợp lệ.
invalid_session_id	Phiên đăng nhập của người dùng không hợp lệ.
session_expired	Phiên đăng nhập hết hạn.
session_not_found	Phiên đăng nhập không tồn tại, người dùng có thể đã đăng xuất khỏi hệ thống.
session_not_match_claim	Phiên đăng nhập không hợp lệ, có thể tích hợp sai môi trường.
server_error	Lỗi không xác định từ server.

Demo

Tham khảo ứng dụng demo

Hỗ trợ

Nếu có thắc mắc trong quá trình tích hợp, bạn có thể liên hệ trực tiếp qua email BaoNQ3 để được trợ giúp.

Thông tin và bài viết liên quan

Tài liệu tích hợp server side ECN User Profile SDK
Tài liệu tích hợp server side ECN SSO Bridge Java SDK

SSO Bridge

Giới thiệu​

Sơ đồ hoạt động​

Danh sách domain mà GG đã triển khai​

Tích hợp​

1. Đăng ký thông tin tích hợp​

2. Điều hướng đăng nhập​

3. Kiểm tra phiên đăng nhập​

4. Lấy thông tin người dùng​

Sử dụng Widget​

Sử dụng API​

5. Đăng xuất người dùng​

Mã lỗi​

Demo​

Hỗ trợ​

Thông tin và bài viết liên quan​

Giới thiệu

Sơ đồ hoạt động

Danh sách domain mà GG đã triển khai

Tích hợp

1. Đăng ký thông tin tích hợp

2. Điều hướng đăng nhập

3. Kiểm tra phiên đăng nhập

4. Lấy thông tin người dùng

Sử dụng Widget

Sử dụng API

5. Đăng xuất người dùng

Mã lỗi

Demo

Hỗ trợ

Thông tin và bài viết liên quan