DataGSM OAuth SDK Java / Kotlin

dependencies {
  implementation("com.github.themoment-team:datagsm-oauth-sdk-java:1.1.0")
}

repositories {
  maven { url = uri("https://jitpack.io") }
}

import team.themoment.datagsm.sdk.oauth.DataGsmOAuthClient;

// 기본 설정으로 클라이언트 생성
DataGsmOAuthClient client = DataGsmOAuthClient.builder("your-client-id", "your-client-secret").build();

// 커스텀 Base URL 설정 (선택사항)
DataGsmOAuthClient clientWithCustomUrl = DataGsmOAuthClient.builder("your-client-id", "your-client-secret")
  .authorizationBaseUrl("https://oauth.data.hellogsm.kr")
  .userInfoBaseUrl("https://oauth-userinfo.data.hellogsm.kr")
  .build();

import team.themoment.datagsm.sdk.oauth.model.AuthorizationUrlBuilder;

String redirectUri = "https://myapp.com/callback";

AuthorizationUrlBuilder urlBuilder = client.createAuthorizationUrl(redirectUri)
  .state("random-csrf-token") // CSRF 방지 (권장)
  .scope("read write");       // Scope 설정 (선택)

String authorizationUrl = urlBuilder.build();
// 사용자를 authorizationUrl로 리다이렉트

import team.themoment.datagsm.sdk.oauth.model.TokenResponse;

// 콜백에서 받은 Authorization Code와 Redirect URI로 토큰 교환
String authorizationCode = "사용자로부터_받은_인증_코드";
String redirectUri = "https://myapp.com/callback";
TokenResponse tokenResponse = client.exchangeCodeForToken(authorizationCode, redirectUri);

// 토큰 사용
String accessToken = tokenResponse.getAccessToken();
String refreshToken = tokenResponse.getRefreshToken();
String tokenType = tokenResponse.getTokenType();   // 보통 "Bearer"
Long expiresIn = tokenResponse.getExpiresIn();     // 만료 시간(초)

// Refresh Token으로 새로운 토큰 발급
TokenResponse newTokenResponse = client.refreshToken(refreshToken);

String newAccessToken = newTokenResponse.getAccessToken();
String newRefreshToken = newTokenResponse.getRefreshToken();

// Scope를 줄여서 갱신 (다운스코핑)
TokenResponse limitedTokenResponse = client.refreshToken(refreshToken, "read");

import team.themoment.datagsm.sdk.oauth.model.UserInfo;
import team.themoment.datagsm.sdk.oauth.model.Student;

// Access Token으로 사용자 데이터 조회
UserInfo userInfo = client.getUserInfo(accessToken);

// 기본 사용자 데이터
System.out.println("ID: " + userInfo.getId());
System.out.println("이메일: " + userInfo.getEmail());
System.out.println("역할: " + userInfo.getRole());

// 학생인 경우 추가 데이터 조회
if (userInfo.isStudent()) {
  Student student = userInfo.getStudent();
  System.out.println("이름: " + student.getName());
  System.out.println("학번: " + student.getStudentNumber());
  System.out.println("학년: " + student.getGrade());
  System.out.println("반: " + student.getClassNum());
  System.out.println("전공: " + student.getMajor());
}

import team.themoment.datagsm.sdk.oauth.model.AuthorizationUrlBuilder;

String redirectUri = "myapp://callback";

// Step 1: PKCE가 활성화된 Authorization URL 생성
AuthorizationUrlBuilder urlBuilder = client.createAuthorizationUrl(redirectUri)
  .enablePkce()              // PKCE 자동 생성 (S256 메소드)
  .state("random-state");

String authorizationUrl = urlBuilder.build();
String codeVerifier = urlBuilder.getCodeVerifier(); // 반드시 저장!

// 사용자를 authorizationUrl로 리다이렉트

// Step 2: 콜백에서 Authorization Code를 받은 후 Code Verifier와 함께 토큰 교환
String authorizationCode = "received-code-from-callback";
TokenResponse tokenResponse = client.exchangeCodeForToken(
  authorizationCode,
  redirectUri,
  codeVerifier  // PKCE 검증용
);

System.out.println("Access Token: " + tokenResponse.getAccessToken());

// 수동으로 Code Verifier를 지정하는 경우
AuthorizationUrlBuilder urlBuilder = client.createAuthorizationUrl(redirectUri)
  .enablePkce("my-custom-code-verifier-43-to-128-chars", "S256"); // S256 또는 plain

// 기본 scope로 토큰 발급
TokenResponse tokenResponse = client.getClientCredentialsToken();

// scope를 지정하여 토큰 발급
TokenResponse tokenResponseWithScope = client.getClientCredentialsToken("read");

System.out.println("Access Token: " + tokenResponse.getAccessToken());
System.out.println("Token Type: " + tokenResponse.getTokenType());
System.out.println("Expires In: " + tokenResponse.getExpiresIn());
// Client Credentials Grant에서는 Refresh Token이 발급되지 않습니다.

import team.themoment.datagsm.sdk.oauth.exception.*;

try {
  UserInfo userInfo = client.getUserInfo(accessToken);
  // 성공적인 응답 처리
} catch (UnauthorizedException e) {
  // 토큰 만료 - 갱신 필요
  logger.error("Token expired or invalid", e);
  TokenResponse newToken = client.refreshToken(refreshToken);
} catch (ForbiddenException e) {
  // 권한 범위 부족
  logger.warn("Insufficient permissions", e);
} catch (RateLimitException e) {
  // Rate limit 초과 - 재시도 로직 구현 필요
  logger.warn("Rate limit exceeded", e);
  // exponential backoff 등의 재시도 전략 구현 권장
} catch (BadRequestException e) {
  // 잘못된 요청 파라미터
  logger.error("Invalid request parameters: {}", e.getMessage());
} catch (NotFoundException e) {
  // 리소스를 찾을 수 없음
  logger.error("Resource not found: {}", e.getMessage());
} catch (ServerErrorException e) {
  // 서버 오류
  logger.error("Server error occurred", e);
} catch (DataGsmException e) {
  // 기타 예외
  logger.error("API error: {}", e.getMessage(), e);
}

// Java의 try-with-resources 사용
try (DataGsmOAuthClient client = DataGsmOAuthClient.builder("your-client-id", "your-client-secret").build()) {
  TokenResponse token = client.exchangeCodeForToken(code, redirectUri);
  UserInfo userInfo = client.getUserInfo(token.getAccessToken());
  // 클라이언트 사용
} // 블록이 끝나면 자동으로 리소스 정리

package com.example.config;

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import team.themoment.datagsm.sdk.oauth.DataGsmOAuthClient;

@Configuration
public class DataGsmOAuthConfig {

  @Bean
  @ConfigurationProperties(prefix = "datagsm.oauth")
  public DataGsmOAuthProperties dataGsmOAuthProperties() {
      return new DataGsmOAuthProperties();
  }

  @Bean
  public DataGsmOAuthClient dataGsmOAuthClient(DataGsmOAuthProperties properties) {
      return DataGsmOAuthClient.builder(properties.getClientId(), properties.getClientSecret())
          .authorizationBaseUrl(properties.getAuthorizationBaseUrl())
          .userInfoBaseUrl(properties.getUserInfoBaseUrl())
          .build();
  }

  public static class DataGsmOAuthProperties {
      private String clientId;
      private String clientSecret;
      private String authorizationBaseUrl;
      private String userInfoBaseUrl;

      public String getClientId() { return clientId; }
      public void setClientId(String clientId) { this.clientId = clientId; }
      public String getClientSecret() { return clientSecret; }
      public void setClientSecret(String clientSecret) { this.clientSecret = clientSecret; }
      public String getAuthorizationBaseUrl() { return authorizationBaseUrl; }
      public void setAuthorizationBaseUrl(String url) { this.authorizationBaseUrl = url; }
      public String getUserInfoBaseUrl() { return userInfoBaseUrl; }
      public void setUserInfoBaseUrl(String url) { this.userInfoBaseUrl = url; }
  }

}

package com.example.service;

import org.springframework.stereotype.Service;
import team.themoment.datagsm.sdk.oauth.DataGsmOAuthClient;
import team.themoment.datagsm.sdk.oauth.model.*;

@Service
public class AuthService {

  private final DataGsmOAuthClient dataGsmOAuthClient;

  public AuthService(DataGsmOAuthClient dataGsmOAuthClient) {
      this.dataGsmOAuthClient = dataGsmOAuthClient;
  }

  public TokenResponse authenticate(String authorizationCode, String redirectUri) {
      return dataGsmOAuthClient.exchangeCodeForToken(authorizationCode, redirectUri);
  }

  public UserInfo getCurrentUser(String accessToken) {
      return dataGsmOAuthClient.getUserInfo(accessToken);
  }

  public TokenResponse refreshUserToken(String refreshToken) {
      return dataGsmOAuthClient.refreshToken(refreshToken);
  }

}

import team.themoment.datagsm.sdk.oauth.DataGsmOAuthClient;
import team.themoment.datagsm.sdk.oauth.exception.*;
import team.themoment.datagsm.sdk.oauth.model.*;

public class Main {
  public static void main(String[] args) {
      // try-with-resources로 자동 리소스 관리
      try (DataGsmOAuthClient client = DataGsmOAuthClient.builder("your-client-id", "your-client-secret").build()) {

          // 1. Authorization URL 생성 및 사용자 리다이렉트
          String redirectUri = "https://myapp.com/callback";
          String authUrl = client.createAuthorizationUrl(redirectUri)
              .state("random-csrf-token")
              .enablePkce()
              .build();
          // 사용자를 authUrl로 리다이렉트 (실제 구현 필요)

          // 2. Authorization Code로 토큰 교환
          String authCode = "authorization_code_from_callback";
          TokenResponse tokenResponse = client.exchangeCodeForToken(authCode, redirectUri);

          System.out.println("Access Token 발급 완료");
          System.out.printf("만료 시간: %d초%n", tokenResponse.getExpiresIn());

          // 3. 사용자 데이터 조회
          UserInfo userInfo = client.getUserInfo(tokenResponse.getAccessToken());

          System.out.printf("사용자 ID: %d%n", userInfo.getId());
          System.out.printf("이메일: %s%n", userInfo.getEmail());
          System.out.printf("역할: %s%n", userInfo.getRole());

          // 4. 학생 데이터 조회 (학생인 경우)
          if (userInfo.isStudent()) {
              Student student = userInfo.getStudent();
              System.out.printf("이름: %s%n", student.getName());
              System.out.printf("학번: %d%n", student.getStudentNumber());
              System.out.printf("학년/반/번호: %d학년 %d반 %d번%n",
                  student.getGrade(), student.getClassNum(), student.getNumber());
              System.out.printf("전공: %s%n", student.getMajor());

              // 동아리 데이터
              if (student.getMajorClub() != null) {
                  System.out.printf("전공동아리: %s%n", student.getMajorClub().getName());
              }
          }

          // 5. 토큰 갱신
          TokenResponse newToken = client.refreshToken(tokenResponse.getRefreshToken());
          System.out.println("토큰 갱신 완료");

      } catch (UnauthorizedException e) {
          System.err.println("인증 오류: 토큰이 유효하지 않습니다.");
          e.printStackTrace();
      } catch (RateLimitException e) {
          System.err.println("요청 제한 초과: 잠시 후 다시 시도해주세요.");
          e.printStackTrace();
      } catch (DataGsmException e) {
          System.err.println("API 오류 발생: " + e.getMessage());
          e.printStackTrace();
      } catch (Exception e) {
          System.err.println("예상치 못한 오류 발생: " + e.getMessage());
          e.printStackTrace();
      }
  }

}

public class Main {
  public static void main(String[] args) {
      // 환경 변수에서 Client ID, Secret 로드
      String clientId = System.getenv("DATAGSM_CLIENT_ID");
      String clientSecret = System.getenv("DATAGSM_CLIENT_SECRET");

      if (clientId == null || clientId.isEmpty()) {
          System.err.println("환경 변수 DATAGSM_CLIENT_ID가 설정되지 않았습니다.");
          System.exit(1);
      }
      if (clientSecret == null || clientSecret.isEmpty()) {
          System.err.println("환경 변수 DATAGSM_CLIENT_SECRET이 설정되지 않았습니다.");
          System.exit(1);
      }

      try (DataGsmOAuthClient client = DataGsmOAuthClient.builder(clientId, clientSecret).build()) {
          // OAuth 사용
      }
  }

}