Skip to main content

ECN Java SDK

Tích hợp server side​

ECN Java SDK cung cấp các hàm gọi qua hệ thống GG ID tương ứng với các Tài liệu API social được đóng gói lại thành các interface để thuận tiện cho việc tích hợp hơn khi client sử dụng ngôn ngữ Java, cung cấp các tính năng sau:

  • Hỗ trợ một số hàm để thực quá trình OAuthentication trên hệ thống GG ID
  • Hỗ trợ hàm lấy thông tin token sau khi người dùng thực hiện quá trình đăng nhập từ hệ thống GG ID
  • Hỗ trợ ứng dụng lấy thông tin tài khoản của người dùng
  • Hỗ trợ đăng xuất khỏi hệ thống GG ID

Xem thêm về mã nguồn

1. Sơ đồ hoạt động​

Đây là sequence diagram mô tả cách lấy thông tin về token và thông tin của user từ hệ thống người dùng đến hệ thống GG.

2. Cấu hình và dependency​

Thêm các thông tin sau vào file pom.xml

  • repository
      <repository>
          <id>nexus</id>
          <name>nexus</name>
          <url>https://nexus-repo.vnggames.app/repository/maven-public/</url>
      </repository>
  • dependency
      <dependency>
          <groupId>vn.vng.ge.ecn</groupId>
          <artifactId>ecn-java-sdk</artifactId>
          <version>0.0.10</version>
      </dependency>

Thêm cấu hình sau vào file config

ecn-java-sdk:
  clientId: 984745454866530308
  clientSecret: hhNUpUbXMzQmhBNzRxZ2NDMkg
  profile: test
  • clientId và clientSecret: Thông tin được cấp khi đăng ký với hệ thống GG ID
  • profile: Tương ứng với các môi trường mà phía client đang tích hợp với bên GG, hiện tại gg cung cấp 3 môi trường tương ứng với cấu hình như sau:
    • test: Tương tác với các hệ thống GG ID trên môi trường test
    • stg: Tương tác với các hệ thống GG ID trên môi trường staging
    • prod: Tương tác với các hệ thống GG ID trên môi trường production

Cài đặt bean EcnJavaSdkInitializer

@Configuration
@Import({EcnJavaSdkInitializer.class})
public class AppConfiguration {
}

Các hàm được hỗ trợ nằm trong EcnSdkClient

public interface EcnSdkClient {
  String generateCodeVerifier();
  String generateCodeChallenge(String codeVerifier);
  String createRedirectUrl(String redirectUri, String state, String codeChallenge, List<String> scopes,
      Map<String, String> extraParams);
  ExchangeTokenResponse exchangeToken(String redirectUri, String code, String codeVerifier);
  RevokeAccessTokenResponse revokeToken(String accessToken);
  GetUserInfoResponse getUserInfo(GetUserInfoRequest request);
}

3. Tạo redirectUrl​

Tạo redirectUrl để hướng người dùng vào trang đăng nhập trên hệ thống của GG ID

public interface EcnSdkClient {
  String createRedirectUrl(String redirectUri, String state, String codeChallenge, List<String> scopes,
      Map<String, String> extraParams);
}

Dùng để tạo ra đường dẫn để chuyển hướng đến cổng xác thực của hệ thống GG ID

Thông tin dữ liệu đầu vào

  • redirectUri: Thông tin đường dẫn sẽ được chuyển hướng đến sau khi người dùng hoàn tất quá trình đăng nhập. URL đã đăng ký với hệ thống GG ID
  • state: Nằm trong params trả về của redirectUri sau khi người dùng hoàn tất quá trình đăng nhập.
    • Định dạng redirectUri về ở bước 7, ví dụ: redirectUri?state=$state&code=$code
    • Không vượt quá 255 kí tự.
    • Dùng để kiểm tra xem có thực sự là bên GG ID trả về hay không để đảm bảo về an toàn dữ liệu.
    • Dựa vào biến state để lấy các thông tin được tạo ra trước đó như codeVerifier, codeChallenge,... (hệ thống phải lưu lại các thông tin này ở bước 4).
  • codeChallenge: Dùng để kiểm tra ở bước exchange token (bước này cần truyền codeVerifier) để kiểm tra xem cặp giá trị này được tạo đúng từ phía client hay không.
  • scopes: Nếu không truyền hoặc truyền rỗng sẽ lấy theo thông tin mặc định đã được đăng ký. Tham khảo tài liệu trường thông tin người dùng (scopes)
  • extraParams: Các params mà client muốn thêm vào phục vụ cho việc lấy authorization code như auth_method, source, lang... Tham khảo

Kết quả nhận được

URI đã được encode và chuyển hướng đến redirectUri, trên giao hiện sẽ hiển thị giao diện login hub để cho người dùng thực hiện quá trình xác thực thông tin

    String uri = ecnSdkClient.createRedirectUrl(redirectUri, state, codeChallenge, scopes, params);
    RedirectView redirectView = new RedirectView(uri);
    return redirectView;

4. Access Token​

Lấy access_token sử dụng code và state

Để có thể nhận callback từ hệ thống GG ID ở bước 7, ta phải tạo controller với phương thức HTTP GET để có thể lấy được thông tin state, code và error(optional)

 @GetMapping("/gg/callback")
  public ResponseEntity<Object> handleGGCallback(
      @RequestParam() String state,
      @RequestParam(required = false) String code,
      @RequestParam(required = false) String error,
      HttpServletResponse httpServletResponse) {
  }

Đường dẫn /gg/callback là đường nằm trong biến redirectUri ở 3. Tạo redirectUrl, nếu không có error, dựa vào thông tin state và code và gọi hàm exchangeToken để lấy thông tin access_token

public interface EcnSdkClient {
  ExchangeTokenResponse exchangeToken(String redirectUri, String code, String codeVerifier);
}

Thông tin dữ liệu đầu vào

  • redirectUri: Cùng thông tin biến được truyền ở EcnSdkClient.createRedirectUrl()
  • code: nhận được từ params callback ở bước 9.
  • codeVerifier: Dựa vào state để lấy thông tin code_verifier ở bước 3.

Kết quả nhận được

  • ExchangeTokenResponse: Thông tin liên quan đến token access_token, refresh_token,...

5. Thông tin người dùng​

Lấy thông tin người dùng bằng cách sử dụng accessToken

public interface EcnSdkClient {
  GetUserInfoResponse getUserInfo(GetUserInfoRequest request);
}

Thông tin dữ liệu đầu vào

  • accessToken: Có được ở 4. Access Token
  • scopes: Các thông tin của người dùng, nếu không được truyền sẽ lấy thông tin mặc định, các thông tin về scope của người dùng được thể hiện trong class OAuthScope hoặc tham khảo tài liệu trường thông tin người dùng (scopes)

Kết quả nhận được

  • Nếu thành công sẽ trả về các thông tin của người dùng được định nghĩa trong scopes như displayName, userId, email,...
  • Nếu thất bại sẽ trả về mã lỗi error, mô tả mã lỗi error_description, tham khảo về tài liệu mã lỗi

6. Thu hồi quyền truy cập​

Sau khi thu hồi quyền truy cập của accessToken, accessToken hiện tại sẽ không thể sử dụng được nữa.

public interface EcnSdkClient {
  RevokeAccessTokenResponse revokeToken(String accessToken);
}

Thông tin dữ liệu đầu vào

Kết quả nhận được

  • Trả về trạng thái token, thành công status: true, thất bại status: false

  • Nếu thất bại sẽ trả về mã lỗi error, mô tả mã lỗi error_description, tham khảo tài liệu mã lỗi

Demo​


Tham khảo ứng dụng demo và chọn Đăng nhập REDIRECT

Tham khảo mã nguồn demo tích hợp phía server side

Tham khảo mã nguồn ECN Java SDK

Nếu muốn sử dụng trực tiếp các API bên phía GG hỗ trợ trong trường hợp sử dụng khác ngôn ngữ Java, có thể tham khảo thêm tại social API

Nhật ký thay đổi phiên bản​

Theo dõi thay đổi của từng phiên bản tại đây.

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 khác​