DataGSM

DataGSM OAuth SDK for React

개요

datagsm-oauth-react는 React 애플리케이션에서 DataGSM OAuth 인증을 쉽고 빠르게 연동할 수 있도록 돕는 공식 SDK입니다.

이 SDK를 사용하면 복잡한 OAuth 리디렉션 흐름을 직접 구현할 필요 없이, 제공되는 React 컴포넌트와 Hook을 통해 간편하게 로그인 기능을 구현할 수 있습니다. 특히 보안이 강화된 PKCE(Proof Key for Code Exchange) 인증 방식을 지원하여 보다 안전한 인증 환경을 구축할 수 있습니다.

PKCE 사용 권장

datagsm-oauth-react 는 auth모드를 'PKCE'로 설정하면 내부적으로 code_challenge와 code_challenge_method를 사용하여 Authorization Code 탈취 공격을 방지할 수 있습니다. 자세한 내용은 PKCE 가이드를 참고하세요.

주요 특징

특징설명
간편한 연동OAuthProvider와 OAuthLoginButton 컴포넌트만으로 빠르게 로그인 UI를 구성할 수 있습니다.
PKCE 지원추가적인 설정 없이 authMode 변경만으로 PKCE 인증 방식을 적용할 수 있습니다.
React Hook 지원useOAuth Hook을 제공하여 커스텀 로그인 버튼이나 로직을 유연하게 작성할 수 있습니다.
TypeScript 지원모든 컴포넌트와 Hook은 TypeScript로 작성되어 타입 안정성을 보장합니다.

시스템 요구사항

항목최소 버전권장 버전
React1819 이상

설치

npm install @themoment-team/datagsm-oauth-react

빠른 시작

1. OAuthProvider 설정

애플리케이션의 최상단 (예: App.js)을 OAuthProvider로 감싸고, DataGSM ↗에서 발급받은 clientId와 로그인 성공 후 리다이렉트될 redirectUri를 props로 전달합니다.

// src/main.jsx

import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';
import { OAuthProvider } from '@themoment-team/datagsm-oauth-react';

const root = ReactDOM.createRoot(document.getElementById('root'));

root.render(
  <React.StrictMode>
    <OAuthProvider
      clientId="YOUR_CLIENT_ID"
      redirectUri="YOUR_REDIRECT_URI"
      authMode="PKCE"
    >
      <App />
    </OAuthProvider>
  </React.StrictMode>
);
Prop타입필수 여부설명
clientIdstring필수DataGSM에서 발급받은 클라이언트 ID
redirectUristring필수로그인 성공 후 리디렉션될 URI
authMode'STANDARD' | 'PKCE'선택인증 방식 설정. 기본값은 'STANDARD'입니다.
childrenReactNode필수OAuthProvider의 하위에 렌더링될 React 컴포넌트

2. 로그인 버튼 사용

OAuthLoginButton 컴포넌트를 사용하여 로그인 버튼을 렌더링할 수 있습니다. 버튼을 클릭하면 설정된 authMode에 맞춰 자동으로 DataGSM 로그인 페이지로 리다이렉션됩니다.

// src/App.jsx

import { OAuthLoginButton } from '@themoment-team/datagsm-oauth-react';

function App() {
  return (
    <div>
      <OAuthLoginButton />
    </div>
  );
}

export default App;

OAuthLoginButton은 표준 HTML <button> 태그의 모든 속성을 지원하며, 추가적으로 다음을 props로 받습니다.

Prop타입필수 여부설명
childrenReactNode선택버튼 내부에 렌더링될 내용. 기본값은 "Data GSM 로그인"입니다.
onClick(event) => void선택기본 login 함수 호출 전에 실행할 커스텀 클릭 핸들러.

useOAuth Hook 사용하기

디자인 시스템에 맞는 커스텀 버튼을 만들거나, 로그인 기능을 버튼 클릭 외의 다른 액션과 연결하고 싶을 때는 useOAuth Hook을 사용할 수 있습니다.

// src/components/CustomLoginButton.jsx

import { useOAuth } from '@themoment-team/datagsm-oauth-react';

function CustomLoginButton() {
  const { login } = useOAuth();

  const handleLogin = async () => {
    // PKCE 모드인 경우 login() 호출 시 code_verifier가 자동 생성되어 sessionStorage에 저장됩니다.
    await login();
  };

  return (
    <button onClick={handleLogin}>
      커스텀 로그인 버튼
    </button>
  );
}

export default CustomLoginButton;

useOAuth Hook은 다음 값을 포함하는 객체를 반환합니다.

반환 값타입설명
login() => Promise<void>호출 시 DataGSM OAuth 로그인 페이지로 리디렉션하는 함수
clientIdstringOAuthProvider에 전달된 클라이언트 ID
redirectUristringOAuthProvider에 전달된 리디렉션 URI
authMode'STANDARD' | 'PKCE'현재 설정된 인증 방식
getCodeVerifier() => string | null저장된 PKCE code_verifier를 가져오는 함수
clearVerifier() => void저장된 PKCE code_verifier를 삭제하는 함수

PKCE 인증 방식 사용하기

PKCE(Proof Key for Code Exchange) 모드를 사용하면 로그인 과정에서 보안을 한층 더 강화할 수 있습니다.

  1. OAuthProvider의 authMode를 "PKCE"로 설정합니다.
  2. login() 함수가 실행되면 SDK 내부적으로 code_verifier를 생성하여 sessionStorage에 저장하고, 이에 대응하는 code_challenge를 생성하여 인증 서버로 함께 보냅니다.
  3. 리다이렉트된 페이지(Callback URI)에서 백엔드에 액세스 토큰을 요청할 때, getCodeVerifier()를 통해 저장된 code_verifier 값을 가져와 함께 전달해야 합니다.
  4. 토큰 요청이 완료된 후에는 clearVerifier()를 호출하여 저장된 값을 삭제하는 것이 권장됩니다.
// Callback 페이지 예시
import { useEffect } from 'react';
import { useOAuth } from '@themoment-team/datagsm-oauth-react';

function CallbackPage() {
  const { getCodeVerifier, clearVerifier } = useOAuth();

  useEffect(() => {
    const codeVerifier = getCodeVerifier();
    const code = new URLSearchParams(window.location.search).get('code');

    if (code && codeVerifier) {
      // 백엔드 API 호출 시 code와 codeVerifier를 함께 전달
      fetchAccessToken(code, codeVerifier).finally(() => {
        clearVerifier(); // 사용 후 정리
      });
    }
  }, []);

  return <div>로그인 중...</div>;
}

export default CallbackPage;

문제 해결

자주 발생하는 문제

Error: useOAuth must be used within OAuthProvider

원인: useOAuth Hook이나 OAuthLoginButton 컴포넌트가 OAuthProvider의 자식 컴포넌트로 렌더링되지 않았습니다.

해결 방법:

  1. 애플리케이션의 최상위 컴포넌트가 OAuthProvider로 감싸져 있는지 확인하세요.
  2. useOAuth 또는 OAuthLoginButton을 사용하는 컴포넌트가 OAuthProvider의 하위 트리에서 렌더링되는지 확인하세요.

추가 리소스

문의사항이나 버그 리포트는 GitHub Issues를 통해 제출해 주세요.