> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# 인증 연동 가이드: 아키텍처와 프로덕션 배포

> Didit 인증을 프로덕션에 연동하는 방법을 설명합니다. 호스팅 화면 또는 자체 UI 선택, 토큰 저장, 백엔드 검사, 세션, 네이티브 앱, 배포 절차를 다룹니다.

이 가이드는 첫 리디렉션부터 출시 전 체크리스트까지, 프로덕션 환경에서 Didit Authentication 연동이 어떻게 구성되는지 설명합니다.
사용자를 아직 로그인시키지 않으셨다면 [빠른 시작](https://docs.didit.me/ko/authentication/quickstart.md)부터 시작하십시오. 각 SDK의 코드는 플랫폼별 빠른 시작 가이드를 참고하십시오.

## 아키텍처

```mermaid theme={null}
sequenceDiagram
    participant App as Your app (browser or mobile)
    participant Hosted as Your Didit sign-in origin
    participant API as Your backend
    participant Webhook as Your webhook endpoint

    App->>Hosted: Open /sign-in (redirect_uri, state, PKCE challenge)
    Note over Hosted: Sign-in method, MFA,<br/>bot protection, verification
    Hosted-->>App: Redirect to redirect_uri with code and state
    App->>Hosted: POST /token/ (code, PKCE verifier)
    Hosted-->>App: Access token (5 min), ID token, refresh token
    App->>API: Request with Authorization: Bearer access token
    Note over API: Verify the signature<br/>with the cached JWKS
    API->>Hosted: GET /session/ before a sensitive action
    Hosted-->>API: Live session, or 401
    Hosted->>Webhook: auth.signup, auth.login, auth.new_device ...
```

네 가지 구성 요소가 관여합니다.

| 구성 요소 | 담당 역할 |
| - | - |
| 귀사의 앱 | 로그인 시작, PKCE verifier와 `state` 보관, 토큰 보관, 액세스 토큰을 백엔드로 전송. 이 모든 작업은 SDK가 수행합니다. |
| 귀사의 로그인 오리진 | `https://<slug>.auth.didit.me`(또는 [커스텀 도메인](https://docs.didit.me/ko/authentication/branding-and-custom-domain.md#커스텀-도메인)): 호스팅 페이지, 토큰 엔드포인트, 세션, 디스커버리, 서명 키. |
| 귀사의 백엔드 | 보호된 요청마다 액세스 토큰 검증, 민감한 작업 전 세션 확인, 사용자가 수행할 수 있는 작업 결정. |
| Didit 콘솔 및 webhook | 구성, 사용자와 세션, 로그인 이벤트, 서버가 구독하는 `auth.*` webhook. |

Didit API 키와 시크릿은 앱에 절대 포함되어서는 안 됩니다. 공개용 키(publishable key)는 공개되어도 괜찮으며, 코드 교환은 클라이언트 시크릿 대신 PKCE로 보호됩니다.

## 호스팅 페이지 또는 직접 만든 화면

사용자가 이메일, 비밀번호, 코드를 입력하는 위치를 선택합니다.
설정 값은 `sign_in_ui`이며, 기본값은 `hosted`이고 `own`으로 바꿀 수 있습니다. 나중에 변경할 수도 있습니다.

| | 호스팅 페이지(권장) | 직접 만든 화면 |
| - | - | - |
| 구현할 항목 | 로그인 버튼과 콜백 페이지. | 모든 화면과 모든 중간 단계. |
| 방식 | 매직 링크, 회사 SSO, 패스키를 포함한 모든 방식. | 헤드리스 메서드를 통한 SDK의 비밀번호, 이메일 코드, 휴대폰 코드, MFA 및 보호 확인 챌린지. 매직 링크는 호스팅 페이지에서만 동작합니다. |
| 다음 단계 | 자동으로 처리됩니다: MFA, MFA 등록, 보호 확인 챌린지, 회원가입 시 인증. | 직접 만든 화면에서 `mfa_required`, `mfa_enrollment_required`, `protection_required`, `verification_required`를 처리해야 합니다. [로그인 방식](https://docs.didit.me/ko/authentication/sign-in-methods.md)을 참조하세요. |
| 브랜드 | [브랜딩](https://docs.didit.me/ko/authentication/branding-and-custom-domain.md)에서 로고, 색상, 문구를 설정합니다. | 전적으로 직접 설정합니다. |
| 설정 | 리디렉션 URL. | 리디렉션 URL과 **Allowed origins**에 웹 출처를 추가합니다. |

패스키는 애플리케이션의 로그인 출처에 연결됩니다.
SDK의 패스키 메서드는 해당 출처에서 제공되는 페이지에서만 동작하므로, 다른 도메인의 직접 만든 화면에서는 패스키를 사용하려면 호스팅 페이지로 안내해야 합니다.

## SDK 선택

| 사용 중인 앱 | 패키지 | 토큰 저장 위치 |
| - | - | - |
| 싱글 페이지 웹 앱 | [`@didit-protocol/auth`](https://docs.didit.me/ko/authentication/quickstarts/javascript) 또는 [`@didit-protocol/auth-react`](https://docs.didit.me/ko/authentication/quickstarts/react) | 브라우저의 웹 스토리지 또는 메모리. 엄격한 콘텐츠 보안 정책(Content Security Policy)을 유지하십시오. |
| 서버 렌더링 웹 앱 | [`@didit-protocol/auth-nextjs`](https://docs.didit.me/ko/authentication/quickstarts/nextjs) | 서버에서 설정한 HttpOnly 쿠키. 페이지는 토큰을 전혀 보지 않습니다. |
| iOS | [`DiditAuth`](https://docs.didit.me/ko/authentication/quickstarts/ios) | Keychain. |
| Android | [`me.didit:didit-auth`](https://docs.didit.me/ko/authentication/quickstarts/android) | Android Keystore로 보호되는 저장소. |
| React Native 또는 Flutter | [`@didit-protocol/auth-react-native`](https://docs.didit.me/ko/authentication/quickstarts/react-native) 또는 [`didit_auth`](https://docs.didit.me/ko/authentication/quickstarts/flutter) | 네이티브 모듈을 통해 사용하는 플랫폼의 보호된 저장소. |
| 모든 백엔드 | [서버 SDK](https://docs.didit.me/ko/integration/server-sdks/overview.md), `@didit-protocol/auth/server`의 `verifyToken`, 또는 어떤 JWT 라이브러리든 | 저장할 필요가 없습니다. 수신한 토큰을 검증합니다. |

SDK를 사용하지 않는다면 PKCE를 사용한 인가 코드 흐름을 직접 구현하십시오. [JavaScript 빠른 시작](https://docs.didit.me/ko/authentication/quickstarts/javascript.md#sdk-없이-사용하기)에서 전체 규격을 확인할 수 있습니다.

## 백엔드 보호

프론트엔드의 세션 확인은 화면에 표시할 내용만 제어합니다.
백엔드는 검증된 토큰을 기준으로 모든 결정을 내립니다.

1. **모든 요청마다 액세스 토큰을 검증합니다.** 발급자의 JWKS를 사용해 ES256 서명을 확인한 다음 `iss`, `aud`, `exp`, `typ: at+jwt`를 확인하고, 라우트가 [AI 에이전트](https://docs.didit.me/ko/authentication/agent-access.md)를 허용하는 경우를 제외하고 `act`가 `null`이 아닌 토큰은 거부합니다. [서버에서 토큰을 검증하는 방법](https://docs.didit.me/ko/authentication/tokens-and-jwks.md#서버에서-토큰-검증)을 참조하십시오.
2. **민감한 작업 전에 라이브 세션을 확인합니다.** 액세스 토큰은 만료될 때까지 최대 5분 동안 유효합니다. `GET /session/`은 세션이 취소되었거나 유휴 상태가 되었거나 만료된 경우, 사용자가 차단된 경우, 또는 세션이 더 이상 MFA 정책을 충족하지 않는 경우 즉시 실패합니다. [세션 확인하기](https://docs.didit.me/ko/authentication/tokens-and-jwks.md#세션-확인)를 참조하십시오.
3. **작업이 위험한 경우 추가 인증을 요청합니다.** 지급, 새 은행 계정 등록, 이메일 또는 전화번호 변경 전에 Didit에 사용자가 다시 인증해야 하는지 문의하고, 백엔드가 직접 읽은 `approved` 상태의 추가 인증에 대해서만 조치합니다. [민감한 작업 전 추가 인증](https://docs.didit.me/ko/authentication/verified-identity.md#민감한-작업-전-추가-인증)을 참조하십시오.
4. **`vendor_data`는 검증된 토큰에서 가져옵니다.** 브라우저가 보낸 필드에서는 절대 가져오지 않습니다. 이 값은 사용자의 인증 및 거래에 사용합니다.

## Sessions

| 이벤트 | 발생하는 일 |
| - | - |
| 로그인 | 세션이 시작됩니다. 세션 기간은 `session_lifetime`(기본값 30일)이며, 활동이 없으면 `idle_timeout`(기본값 1일) 이후 더 일찍 종료됩니다. |
| 몇 분마다 | SDK가 access token을 갱신합니다. access token의 유효 기간은 최대 5분입니다. refresh token은 교체되며, 각 토큰은 한 번만 사용할 수 있습니다. |
| 이미 사용한 refresh token이 다시 전송됨 | Didit은 이를 탈취로 간주하고 세션을 종료합니다. 세션당 한 번에 하나의 갱신만 실행하세요. |
| 다른 기기에서 로그인 | `multiple_sessions: false`이면 해당 사용자의 다른 세션이 종료됩니다. |
| 비밀번호 재설정 | `revoke_on_password_change`가 켜져 있으면(기본값) 모든 세션이 종료됩니다. |
| 로그아웃 | `DELETE /session/`은 세션을 종료하고, 앱은 사용자를 `post_logout_redirect_uri`로 이동시킵니다. |
| 귀사 팀의 조치 | 콘솔에서 세션 하나를 취소하거나, 사용자를 모든 세션에서 로그아웃시키거나, 사용자를 차단할 수 있습니다. [콘솔 가이드](https://docs.didit.me/ko/authentication/console.md#로그인-및-세션)를 참조하세요. |

세션 기간은 **Authentication > Security and sessions**에서 변경하거나, [애플리케이션 설정](https://docs.didit.me/ko/authentication/overview.md#애플리케이션-설정)에서 API를 통해 변경할 수 있습니다.

![Didit Business Console의 Active sessions 화면. 로그인된 세션의 기기, 위치, 시작 시각, 마지막 활동, 종료 시각과 Revoke 버튼이 표시되어 있습니다.](https://mintcdn.com/didit-0f962782/RpqZjIB1GnUPdMTN/images/authentication/console-active-sessions.png?fit=max\&auto=format\&n=RpqZjIB1GnUPdMTN\&q=85\&s=098f6be31804b0af7c680e569f341bfb)

Authentication > Sign-ins > Active sessions 화면. 각 세션에 Revoke 버튼이 표시됩니다.

## 네이티브 앱

Didit은 HTTPS 리디렉션으로만 사용자를 네이티브 앱으로 돌려보냅니다. 사용자 지정 URL 스킴은 지원하지 않습니다.

* **iOS:** 리디렉션을 연결된 도메인으로 설정하고, `apple-app-site-association`에 `webcredentials`를 포함하세요.
* **Android:** 리디렉션을 App Link로 설정하고, `assetlinks.json`을 사용하세요.
* 모든 리디렉션 URL을 웹 콜백과 같은 방식으로 **Authentication > Security and sessions**에 등록하세요.

앱에서 패스키를 사용하려면, 애플리케이션의 패스키를 공유하는 앱을 [인증 관리 API](https://docs.didit.me/ko/authentication/set-up-by-api.md)의 `PUT native-apps/`로 등록하세요. 그러면 Didit은 등록된 앱을 로그인 오리진에서 제공하는 `apple-app-site-association`과 `assetlinks.json`에 나열합니다.
`MANAGEMENT_BASE`는 애플리케이션의 관리 API 주소이며, `authentication` 범위에서 **쓰기** 권한이 있는 API 키로 이 호출을 할 수 있습니다.
이 호출은 두 목록을 모두 교체하므로, 두 목록을 함께 보내세요:

```bash theme={null}
curl --fail-with-body --request PUT "${MANAGEMENT_BASE}native-apps/" \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ios_app_ids": ["ABCDE12345.com.example.app"],
    "android_apps": [
      {
        "package_name": "com.example.app",
        "sha256_cert_fingerprints": ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
      }
    ]
  }'
```

| 필드 | 규칙 |
| - | - |
| `ios_app_ids` | Team ID와 번들 식별자를 조합한 항목을 최대 10개까지 입력합니다. 예: `ABCDE12345.com.example.app`. |
| `android_apps` | 최대 10개의 앱을 등록할 수 있으며, 각 앱에는 `package_name`과 1개 이상 5개 이하의 SHA-256 서명 인증서 지문이 필요합니다. |

앱 측 설정은 [iOS](https://docs.didit.me/ko/authentication/quickstarts/ios.md) 및 [Android](https://docs.didit.me/ko/authentication/quickstarts/android.md) 빠른 시작 가이드에서 확인할 수 있습니다.

## 신원 확인 및 거래 모니터링 연결

모든 사람에게는 토큰과 세션에 담기는 `vendor_data` 값이 하나씩 있습니다.
[인증 세션을 생성](https://docs.didit.me/ko/sessions-api/create-session.md)하거나 [거래를 제출](https://docs.didit.me/ko/transaction-monitoring/transactions.md)할 때 이 값을 `vendor_data`로 사용하면, 콘솔에서 로그인, 인증, 거래를 같은 사람에 대해 확인할 수 있습니다.

* 회원가입 시점이나 지급 전에 다시 인증 흐름을 직접 구축하지 않고 사람을 확인하려면 [검증된 신원](https://docs.didit.me/ko/authentication/verified-identity.md)을 사용하십시오.
* 로그인 이벤트는 [이벤트 규칙](https://docs.didit.me/ko/transaction-monitoring/event-rules.md)과 사기 탐지 화면으로 자동 전달됩니다. 같은 로그인에 대해 `auth.login` 이벤트를 직접 전송하지 마십시오.
* 로그인이 성공해도 인증이나 거래가 승인되지는 않습니다. 각 제품의 결정은 개별적으로 처리하십시오.

[여러 제품에서 한 사용자 유지하기](https://docs.didit.me/ko/authentication/overview.md#여러-제품에서-동일-인물-유지)를 참고하십시오.

## 로그인 이벤트 수신

[webhook 대상](https://docs.didit.me/ko/integration/webhooks.md)이 필요한 `auth.*` 유형(예: `auth.new_device`, `auth.account_locked`)을 구독하도록 설정하십시오.
중복 제거는 `auth_event.event_id`를 기준으로 하고, 모든 Didit webhook과 마찬가지로 서명을 검증하십시오.
모든 유형과 페이로드는 [이벤트 및 webhook](https://docs.didit.me/ko/authentication/events-and-webhooks.md)에서 확인하십시오.

## 기존 사용자 이전

이미 다른 신원 인증 플랫폼이나 자체 데이터베이스에 계정을 가진 사용자가 있다면, 로그인 방식을 전환하기 전에 [사용자를 가져오십시오](https://docs.didit.me/ko/authentication/migration.md).
원본에서 제공되는 경우 비밀번호 해시를 가져오고, 소셜 연동 정보를 유지하며, 자체 사용자 ID는 `external_id`로 보관하십시오. 이 값은 사용자의 `vendor_data`가 됩니다.
앱을 Didit으로 전환하기 전까지 사용자에게는 아무것도 달라지지 않습니다.

## 운영 전환 체크리스트

1. 인증 기능이 **Products** 페이지에서 Live 애플리케이션에 대해 켜져 있어야 합니다.
2. 운영용 `https://` 리디렉션 URL과 허용 출처가 Live 애플리케이션에 등록되어 있어야 합니다. Live 애플리케이션은 `http://` 주소를 허용하지 않습니다.
3. 각 소셜 로그인 방식은 자사 앱의 클라이언트 ID와 시크릿을 사용해야 합니다. Didit의 테스트 자격 증명은 샌드박스에서만 작동합니다.
4. 운영 환경 설정에 Live 공개 키(`pk_live_`)와 Live 발급자가 포함되어 있어야 합니다.
5. MFA 정책, 세션 유효 기간, 유휴 시간 제한, 비밀번호 길이, 가입 정책이 원하는 대로 설정되어 있어야 합니다. [애플리케이션 설정](https://docs.didit.me/ko/authentication/overview.md#애플리케이션-설정)을 참고하십시오.
6. [봇 방지](https://docs.didit.me/ko/authentication/bot-protection.md)가 켜져 있고 유출된 비밀번호 확인이 설정되어 있어야 합니다.
7. 백엔드가 모든 액세스 토큰을 검증하고, 민감한 작업 전에 `GET /session/`을 호출해야 합니다.
8. 브랜딩, 페이지 문구, 이용약관 및 개인정보처리방침 링크가 설정되어 있어야 합니다. [커스텀 도메인](https://docs.didit.me/ko/authentication/branding-and-custom-domain.md#커스텀-도메인)을 사용할 계획이라면, 사용자가 패스키를 추가하기 시작하기 전에 활성화하십시오.
9. webhook 대상이 처리하는 `auth.*` 유형을 구독하고 있어야 합니다.
10. Live 애플리케이션에서 가입, 기존 계정 재로그인, 가입 취소, 비밀번호 찾기, MFA, 세션 만료, 로그아웃, 철회된 세션을 모두 테스트했어야 합니다.

## 문제 해결

| 증상 | 원인 및 해결 방법 |
| - | - |
| 모든 런타임 라우트가 `404`를 응답합니다 | 애플리케이션에 인증이 꺼져 있거나, 주소에 샌드박스 오리진과 프로덕션 환경 오리진이 섞여 있습니다. **Products** 페이지에서 인증을 켜고, 퍼블리셔블 키가 가리키는 origin을 사용하세요. |
| 로그인 페이지가 `400`을 응답하며 주소 등록을 요청하거나, `POST /authorize/`가 `invalid_redirect_uri`를 응답합니다 | `redirect_uri`가 정확히 등록되어 있지 않습니다. 스킴, 호스트, 포트, 경로, 쿼리가 한 글자도 틀리지 않고 일치해야 합니다. [리디렉션 URL](https://docs.didit.me/ko/authentication/overview.md#리디렉션-url)을 참고하세요. |
| 브라우저에서 로그인 origin으로 보낸 호출이 `origin_not_allowed`와 함께 `403`을 응답합니다 | 웹 origin이 **Allowed origins**에 없습니다. 경로와 끝의 슬래시 없이 추가하세요. |
| `POST /token/`이 `invalid_grant`를 응답합니다 | 코드가 이미 사용되었거나, 60초가 지났거나, 다른 PKCE 검증자 또는 `redirect_uri`와 함께 전송되었습니다. 갱신의 경우 갱신 token이 이미 사용되어 세션이 종료된 것입니다. 로그인을 처음부터 다시 시작하세요. |
| 올바른 비밀번호인데도 비밀번호 로그인이 `invalid_credentials`를 응답합니다 | 이메일이 인증되지 않았거나, 계정이 잠겼거나 차단되었습니다. Didit은 의도적으로 같은 응답을 반환합니다. **Users**에서 해당 사용자를 확인하세요. |
| `GET /session/`이 `401`을 응답합니다 | 세션이 취소되었거나, 유휴 상태가 되었거나 만료되었거나, 사용자가 차단되었거나, token이 refresh token으로 교체되었거나, 세션이 더 이상 MFA 정책을 충족하지 않습니다. token을 갱신하거나 사용자가 다시 로그인하도록 하세요. |
| 패스키 또는 인증 앱을 추가하는 요청이 `403 reauthentication_required`를 응답합니다 | 이 작업에는 최근 5분 안에 생성된 세션이 필요합니다. 먼저 사용자가 다시 로그인하도록 하세요. |
| 전화 코드 요청이 `503 delivery_unavailable`을 응답합니다 | 코드를 전송할 수 없었습니다. 사용자가 다시 시도하도록 하거나 다른 방법을 제공하세요. |
| 호출이 `429`를 응답합니다 | 속도 제한에 도달했습니다. `Retry-After`에 표시된 시간 후에 다시 시도하세요. [속도 제한](https://docs.didit.me/ko/authentication/bot-protection.md#속도-제한)을 참고하세요. |
| API 키를 사용한 설정 호출이 `409 product_disabled`를 응답합니다 | 애플리케이션에 인증이 꺼져 있습니다. 사용자가 콘솔에서 인증을 켜야 합니다. |
| 호출이 `403 plan_required`를 응답합니다 | 커스텀 역할이나 회사 SSO 설정 링크 같은 기능에는 Scale 또는 Enterprise 요금제가 필요합니다. 샌드박스 애플리케이션은 요금제와 관계없이 이 기능을 사용할 수 있습니다. |
| 커스텀 도메인을 활성화한 후 token 검증이 실패합니다 | 발급자와 퍼블리셔블 키가 변경되었습니다. 새 키를 앱에 복사하고, 백엔드가 확인하는 발급자를 업데이트하세요. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.