> 출처: https://myiam.io/docs/quickstart/react
> React 앱에 MyIAM 로그인, 회원가입, 로그아웃 기능을 추가하는 방법을 안내합니다.
> 샘플 코드: https://github.com/myiam-io/react-samples
> 목차: https://myiam.io/llms.txt · 전체 문서 한 파일: https://myiam.io/llms-full.txt

# React로 시작하기

이 가이드는 Vite, React, TypeScript 환경 기준입니다.

React 앱에 로그인, 회원가입, 로그아웃 기능을 추가하는 방법을 안내합니다. 처음이라도 코드를 복사해서 붙여넣기만 하면 동작하는 샘플 앱을 만들 수 있습니다.

> **사전 준비**
>
> MyIAM 계정이 필요합니다. 로그인 또는 회원가입 후 진행하세요.
> 
> - **Node.js 20 이상**이 설치되어 있어야 합니다. 터미널에서 `node -v`로 확인할 수 있습니다.

### Step 1: 프로젝트 생성

터미널을 열고 아래 명령어를 실행하면 `my-app`이라는 새 프로젝트 폴더가 만들어집니다.

`터미널`

```bash
npm create vite@latest my-app -- --template react-ts
cd my-app
```
### Step 2: SDK 설치

MyIAM SDK와 페이지 이동을 위한 라이브러리를 설치합니다.

`터미널`

```bash
npm install @myiam.io/web-sdk react-router-dom
```

- `@myiam.io/web-sdk` — MyIAM 인증 기능을 사용하기 위한 SDK
- `react-router-dom` — 여러 페이지 간 이동을 처리하는 라이브러리
### Step 3: 환경 변수 설정

프로젝트 최상위 폴더에 `.env` 파일을 만들고, 내 서비스 정보를 입력합니다. 이 값들은 MyIAM 관리 화면에서 확인할 수 있습니다.

- `VITE_SERVICE_UID` = `<YOUR_SERVICE_UID>`
  서비스 설정 페이지에서 확인할 수 있는 서비스 고유 식별자입니다.
- `VITE_OAUTH2_CLIENT_ID` = `<YOUR_OAUTH2_CLIENT_ID>`
  OAuth2 설정 페이지에서 확인할 수 있는 클라이언트 식별자입니다.

`.env`

```env
VITE_SERVICE_UID=<YOUR_SERVICE_UID>
VITE_OAUTH2_CLIENT_ID=<YOUR_OAUTH2_CLIENT_ID>
```

`.env`는 `.gitignore`에 추가하여 저장소에 포함되지 않도록 합니다.

`VITE_` 접두사가 붙은 값은 빌드 시 브라우저 번들에 그대로 포함됩니다. `serviceUid`와 `oauth2ClientId`는 공개되어도 되는 값이지만, **API 키는 절대 여기에 두지 마세요.** REST API 호출이 필요하면 서버에서 [Server SDK](https://myiam.io/docs/sdk/web/server)를 사용합니다.
### Step 4: SDK 초기화

앱이 시작될 때 SDK에 내 서비스 정보를 알려주는 과정입니다. `src/main.tsx` 파일을 아래와 같이 수정하세요.

`src/main.tsx`

```react
import { myiamInit } from '@myiam.io/web-sdk/client'
import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import App from './App'

// 앱이 시작되기 전에 MyIAM SDK를 초기화합니다
myiamInit({
  serviceUid: import.meta.env.VITE_SERVICE_UID,
  oauth2ClientId: import.meta.env.VITE_OAUTH2_CLIENT_ID,
})

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <App />
  </StrictMode>,
)
```
### Step 5: 페이지 구성

앱에 필요한 세 개의 페이지를 연결합니다. 각 페이지는 다음 단계에서 만들 예정이니, 먼저 `src/App.tsx` 파일을 아래와 같이 수정하세요.

`src/App.tsx`

```react
import { BrowserRouter, Routes, Route } from 'react-router-dom'
import HomePage from './pages/HomePage'
import CallbackPage from './pages/CallbackPage'
import DashboardPage from './pages/DashboardPage'

export default function App() {
  return (
    <BrowserRouter>
      <Routes>
        <Route path="/" element={<HomePage />} />
        <Route path="/callback" element={<CallbackPage />} />
        <Route path="/dashboard" element={<DashboardPage />} />
      </Routes>
    </BrowserRouter>
  )
}
```

| 페이지 | 하는 일 |
| --- | --- |
| `/` | 로그인, 회원가입 버튼이 있는 첫 화면 |
| `/callback` | 로그인 완료 후 자동으로 거쳐가는 중간 페이지 |
| `/dashboard` | 로그인 성공 후 보여줄 화면 |
### Step 6: 로그인 / 회원가입 페이지

`src/pages` 폴더를 만들고 아래 파일을 생성하세요. 버튼을 클릭하면 MyIAM 로그인 화면으로 이동합니다.

> **설정 필요**
>
> 아래 개발용 콜백 주소를 **Redirect Url**에 등록하세요. 배포 시에는 실제 도메인으로 변경합니다.
> URL: `http://localhost:5173/callback`

`src/pages/HomePage.tsx`

```react
import { useSearchParams } from 'react-router-dom'
import { myiamLoginUrl, myiamSignupUrl } from '@myiam.io/web-sdk/client'

// 로그인이 끝나면 돌아올 주소
const CALLBACK_URL = `${window.location.origin}/callback`

export default function HomePage() {
  // 콜백이 실패하면 이 화면으로 error 코드를 달고 돌아옵니다
  const [searchParams] = useSearchParams()
  const error = searchParams.get('error')

  async function handleLogin() {
    // MyIAM 로그인 화면으로 이동
    window.location.href = await myiamLoginUrl(CALLBACK_URL)
  }

  async function handleSignup() {
    // MyIAM 회원가입 화면으로 이동
    window.location.href = await myiamSignupUrl(CALLBACK_URL)
  }

  return (
    <div>
      <h1>MyIAM React</h1>
      {error && <p>로그인에 실패했습니다 ({error}). 다시 시도해 주세요.</p>}
      <button onClick={handleLogin}>로그인</button>
      <button onClick={handleSignup}>회원가입</button>
    </div>
  )
}
```

**회원가입도 같은 `/callback`으로 끝납니다.** MyIAM은 가입이 끝나면 같은 인증 요청을 그대로 이어받아 자동으로 로그인시키고 콜백 주소로 돌려보냅니다. 가입용 콜백을 따로 만들 필요가 없습니다.

가입을 마쳤는데 로그인 화면이 한 번 더 뜬다면 서비스 > 서비스 정보 페이지의 회원가입 설정에서 **자동 로그인**이 꺼져 있는 것입니다 (기본값 ON).

로그인 링크와 회원가입 링크는 **각각 새 인증 요청을 시작합니다.** 하나를 시작해 두고 다른 쪽을 누르면 먼저 시작한 요청은 버려지므로, 그 화면에서 로그인을 끝내면 콜백이 `state_mismatch`로 실패합니다. 사용자에게는 링크를 하나만 누르게 하고, 실패하면 아래처럼 첫 화면으로 되돌려 다시 시작하게 하세요.
### Step 7: 콜백 페이지

사용자가 로그인을 마치면 MyIAM 서버가 이 페이지로 되돌려 보냅니다. 여기서 로그인 결과(토큰)를 받아 저장하고, 대시보드로 이동합니다.

아래 예시는 토큰을 `sessionStorage`에 저장합니다. 브라우저 저장소는 XSS에 노출되므로, 특히 리프레시 토큰을 다루는 프로덕션 앱이라면 토큰을 HttpOnly 쿠키에 담아 서버가 관리하는 [Server SDK](https://myiam.io/docs/sdk/web/server) 방식을 권장합니다.

`src/pages/CallbackPage.tsx`

```react
import { useEffect, useRef } from 'react'
import { useNavigate } from 'react-router-dom'
import { myiamHandleCallback, MyiamCallbackError } from '@myiam.io/web-sdk/client'

export default function CallbackPage() {
  const navigate = useNavigate()
  const called = useRef(false)

  useEffect(() => {
    // 한 번만 실행되도록 방지
    if (called.current) return
    called.current = true

    // MyIAM 서버에서 받은 인증 코드를 토큰으로 교환
    myiamHandleCallback()
      .then((tokens) => {
        // 받은 토큰을 브라우저에 저장
        sessionStorage.setItem('access_token', tokens.access_token)
        sessionStorage.setItem('refresh_token', tokens.refresh_token)
        // 대시보드로 이동
        navigate('/dashboard')
      })
      .catch((err) => {
        // 실패 이유를 남기지 않으면 "콜백에서 멈췄다"로만 보입니다
        const code = err instanceof MyiamCallbackError ? err.code : 'unknown'
        console.error('[myiam] callback failed:', code, err)
        navigate(`/?error=${code}`)
      })
  }, [navigate])

  return <p>로그인 처리 중...</p>
}
```

`MyiamCallbackError`의 `code`로 실패 원인이 갈립니다. 전체 목록은 [Client SDK의 MyiamCallbackError](https://myiam.io/docs/sdk/web/client)에 있고, 개발 중에 가장 자주 만나는 셋은 이렇습니다.

| `code` | 원인 |
| --- | --- |
| `missing_pkce_state` | 로그인을 시작한 지 30분이 지났습니다. 다시 로그인하면 됩니다 |
| `state_mismatch` | 로그인을 두 번 시작했습니다. 로그인과 회원가입을 이어서 누르면 나중 요청이 앞선 요청을 덮으므로, 앞선 화면에서 로그인을 끝내면 여기서 실패합니다 |
| `authorization_error` | 인증 서버가 요청을 거절했습니다. 대부분 **Redirect Url 등록값과 앱이 보낸 주소가 한 글자라도 다른 경우**입니다 |
### Step 8: 대시보드 페이지

로그인에 성공하면 보여줄 화면입니다. 토큰 갱신과 로그아웃 버튼을 만들어 봅니다.

> **설정 필요**
>
> 아래 개발용 주소를 **Logout Redirect Url**에 등록하세요. 배포 시에는 실제 도메인으로 변경합니다.
> URL: `http://localhost:5173`

`src/pages/DashboardPage.tsx`

```react
import { useState } from 'react'
import { myiamLogoutUrl, myiamRefreshToken } from '@myiam.io/web-sdk/client'

export default function DashboardPage() {
  const [accessToken, setAccessToken] = useState(
    () => sessionStorage.getItem('access_token'),
  )
  const [refreshToken, setRefreshToken] = useState(
    () => sessionStorage.getItem('refresh_token'),
  )

  // 토큰이 만료되었을 때 새 토큰을 발급받습니다
  async function handleRefresh() {
    if (!refreshToken) return
    const tokens = await myiamRefreshToken(refreshToken)
    sessionStorage.setItem('access_token', tokens.access_token)
    sessionStorage.setItem('refresh_token', tokens.refresh_token)
    setAccessToken(tokens.access_token)
    setRefreshToken(tokens.refresh_token)
  }

  // 로그아웃 후 첫 화면으로 돌아갑니다
  function handleLogout() {
    sessionStorage.removeItem('access_token')
    sessionStorage.removeItem('refresh_token')
    window.location.href = myiamLogoutUrl(window.location.origin)
  }

  return (
    <div>
      <h1>대시보드</h1>
      <p>Access Token: {accessToken?.slice(0, 20)}...</p>
      <p>Refresh Token: {refreshToken?.slice(0, 20)}...</p>
      <button onClick={handleRefresh}>토큰 갱신</button>
      <button onClick={handleLogout}>로그아웃</button>
    </div>
  )
}
```
### Step 9: 실행

모든 파일을 저장하고 아래 명령어로 개발 서버를 시작합니다.

`터미널`

```bash
npm run dev
```

브라우저에서 `http://localhost:5173`을 열면 로그인 버튼이 보입니다. 버튼을 클릭해서 로그인이 잘 되는지 확인해 보세요!

**전체 인증 흐름**

```mermaid
flowchart TD
    A["로그인 버튼 클릭"]
    A --> B["MyIAM 로그인 화면으로 이동<br/>SDK가 안전한 인증 URL을 만들어 줍니다"]
    B --> C["사용자가 로그인 완료<br/>MyIAM 서버에서 아이디/비밀번호를 확인합니다"]
    C --> D["우리 앱의 /callback 페이지로 돌아옴"]
    D --> E["토큰 발급<br/>SDK가 인증 결과를 토큰으로 교환합니다"]
    E --> F["대시보드 진입<br/>토큰을 저장하고 로그인 완료!"]
    G["회원가입 버튼 클릭"]
    G --> H["MyIAM 회원가입 화면으로 이동<br/>약관 동의 → 정보 입력 순서로 진행됩니다"]
    H --> I["가입 완료 후 자동 로그인<br/>서비스 정보의 자동 로그인 설정이 ON일 때 (기본값)"]
    I --> J["같은 /callback 페이지로 돌아옴<br/>여기서부터는 로그인과 완전히 같습니다"]
    K["로그아웃 버튼 클릭"]
    K --> L["MyIAM 서버로 로그아웃 요청<br/>세션을 정리하고 로그아웃을 처리합니다"]
    L --> M["설정한 Logout Redirect Url로 돌아옴<br/>로그아웃 완료! 첫 화면으로 이동합니다"]
```

**프로젝트 구조**

```
my-app/
├── src/
│   ├── main.tsx  -- SDK 초기화 + 렌더링
│   ├── App.tsx  -- 페이지 연결
│   └── pages/
│       ├── HomePage.tsx  -- 로그인/회원가입 화면
│       ├── CallbackPage.tsx  -- 로그인 완료 처리
│       └── DashboardPage.tsx  -- 로그인 후 화면
├── .env  -- 서비스 정보 설정
├── index.html
├── package.json
├── tsconfig.json
└── vite.config.ts
```

**다음 단계**

- **인증 가드 추가하기** [쉬움] — 로그인하지 않은 사용자가 대시보드에 직접 접근하면 첫 화면으로 돌려보내기
- **에러 처리 개선** [보통] — 로그인 실패나 토큰 갱신 실패 시 사용자에게 안내 메시지 보여주기
- **토큰 자동 갱신** [어려움] — API 호출 시 토큰이 만료되었으면 자동으로 새 토큰을 발급받아 재시도하기
