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

# SDK에서 페더레이션 ID 사용하기

> JSON Web Token(JWT) 기반 ID 페더레이션을 사용하면 API 키 없이 W&B SDK 및 CLI에 인증할 수 있습니다.

ID 페더레이션을 사용하면 수명이 긴 API 키 대신 조직 자격 증명으로 W\&B SDK 및 CLI에 로그인할 수 있습니다. W\&B 조직 관리자가 조직에 SSO를 설정했다면, 이미 해당 자격 증명으로 W\&B 앱 UI에 로그인하고 있을 것입니다. ID 페더레이션은 W\&B SDK용 SSO와 비슷하지만, JSON Web Token(JWT)을 직접 사용한다는 점이 다릅니다. API 키 대신 ID 페더레이션을 사용하세요.

이 페이지는 W\&B 조직의 JWT 발급자를 설정하는 조직 관리자와 JWT로 W\&B에 인증하는 사용자 또는 서비스 계정을 대상으로 합니다.

SDK의 ID 페더레이션은 [RFC 7523](https://datatracker.ietf.org/doc/html/rfc7523)을 기반으로 합니다.

<Note>
  ID 페더레이션은 Multi-tenant Cloud, Dedicated Cloud, Self-Managed에서 프리뷰로 사용할 수 있으며, [엔터프라이즈 라이선스](/ko/products/wandb/platform/hosting/enterprise-licenses)가 필요합니다. 자세한 내용을 확인하거나 도움을 받으려면 담당 AISE 또는 [지원팀](mailto:forge-support@coreweave.com)에 문의하세요.
</Note>

<Note>
  이 문서에서는 "ID 공급자"와 "JWT 발급자"를 같은 의미로 사용합니다. 이 기능에서 두 용어는 동일한 대상을 가리킵니다.
</Note>

<h2 id="set-up-the-jwt-issuer">
  JWT 발급자 설정
</h2>

사용자가 JWT로 인증하려면 먼저 조직 관리자가 W\&B 조직과 공개적으로 액세스할 수 있는 JWT 발급자 간에 페더레이션을 설정해야 합니다.

1. 조직 대시보드의 **Settings** 탭으로 이동하세요.
2. **Authentication** 옵션에서 **Set up JWT Issuer**를 클릭하세요.
3. 텍스트 상자에 JWT 발급자 URL을 입력하고 **Create**를 클릭하세요.

W\&B는 `${ISSUER_URL}/.well-known/openid-configuration` 경로에서 OIDC 검색 문서를 자동으로 찾습니다. 그런 다음 검색 문서를 참조하여 해당 URL에 있는 JSON Web Key Set(JWKS)을 찾습니다. W\&B는 이 JWKS로 JWT를 실시간 검증하여 해당 ID 공급자가 발급한 JWT인지 확인합니다.

이 단계를 마치면 W\&B 조직이 JWT 발급자와 페더레이션됩니다. 이제 조직의 사용자는 해당 공급자가 발급한 JWT를 사용하여 W\&B에 인증할 수 있습니다.

<h2 id="use-the-jwt-to-access-wb">
  JWT를 사용하여 W\&B에 액세스하기
</h2>

조직 관리자가 JWT 발급자를 설정하면 사용자는 해당 ID 공급자가 발급한 JWT로 W\&B 프로젝트에 액세스할 수 있습니다. JWT를 사용하는 방법은 다음과 같습니다.

1. 조직에서 사용 가능한 방법 중 하나로 ID 공급자에 로그인해야 합니다. 일부 공급자는 API 또는 SDK를 통해 자동으로 액세스할 수 있지만, 관련 UI를 통해서만 액세스할 수 있는 공급자도 있습니다. 자세한 내용은 W\&B 조직 관리자 또는 JWT 발급자의 소유자에게 문의하세요.
2. ID 공급자에 로그인하여 JWT를 발급받은 후 안전한 위치의 파일에 저장하세요. 그런 다음 환경 변수 `WANDB_IDENTITY_TOKEN_FILE`에 해당 파일의 절대 경로를 설정하세요.
3. W\&B SDK 또는 CLI를 사용하여 W\&B 프로젝트에 액세스하세요. SDK 또는 CLI는 JWT를 자동으로 감지하여 검증한 후 W\&B 액세스 토큰으로 교환합니다. W\&B 액세스 토큰을 사용하면 run, 메트릭, 아티팩트 로깅 등 AI 워크플로에 필요한 API에 액세스할 수 있습니다. 액세스 토큰은 기본적으로 `~/.config/wandb/credentials.json` 경로에 저장됩니다. 이 경로는 환경 변수 `WANDB_CREDENTIALS_FILE`을 지정하여 변경할 수 있습니다.

<Note>
  JWT는 API 키나 비밀번호 같은 장기 자격 증명의 단점을 보완하는 단기 자격 증명입니다. JWT 만료 시간은 ID 공급자의 설정에 따라 다릅니다. JWT가 만료되기 전에 갱신하고, 갱신된 JWT가 환경 변수 `WANDB_IDENTITY_TOKEN_FILE`이 참조하는 파일에 저장되어 있는지 확인하세요.

  W\&B 액세스 토큰에도 기본 만료 기간이 있으며, 기간이 지나면 SDK 또는 CLI가 JWT를 사용하여 토큰 갱신을 시도합니다. 이 시점에 사용자 JWT도 만료되었고 갱신되지 않은 상태라면 인증에 실패합니다. 가능하면 W\&B SDK 또는 CLI를 사용하는 AI 워크로드에 JWT 발급 및 만료 후 갱신 메커니즘을 함께 구현하세요.
</Note>

<h3 id="jwt-validation">
  JWT 검증
</h3>

유효한 토큰으로만 액세스할 수 있도록 JWT는 다음 검증을 거칩니다. 이 검증은 SDK 또는 CLI가 JWT를 W\&B 액세스 토큰으로 교환한 뒤 프로젝트에 액세스할 때 실행됩니다.

* W\&B는 W\&B 조직 수준의 JWKS를 사용해 JWT 서명을 검증합니다. 이 단계는 첫 번째 방어선으로, 여기서 실패하면 JWKS 또는 JWT 서명 방식에 문제가 있다는 뜻입니다.

* JWT의 `iss` 클레임은 조직 수준에서 설정한 발급자 URL과 일치해야 합니다.

* JWT의 `sub` 클레임은 W\&B 조직에 설정된 사용자 이메일 주소와 일치해야 합니다.

* JWT의 `aud` 클레임은 AI 워크플로에서 액세스하는 프로젝트가 속한 W\&B 조직의 이름과 일치해야 합니다.

  [Dedicated Cloud](/ko/products/wandb/platform/hosting/hosting-options/dedicated-cloud) 또는 [Self-Managed](/ko/products/wandb/platform/hosting/hosting-options/self-managed) 인스턴스의 경우:

  * 대상(audience) 검증을 건너뛰려면 환경 변수 `FEDERATED_AUTH_AUDIENCES`를 `wandb`로 설정하세요.
  * 일부 조직에는 대상(audience)에 관한 별도의 요구 사항이 있습니다. `aud` 값을 사용자 지정하려면 환경 변수 `FEDERATED_AUTH_AUDIENCES`를 쉼표로 구분한 대상 값 목록 문자열로 설정하세요.

* W\&B는 JWT의 `exp` 클레임을 검사하여 토큰이 유효한지, 아니면 만료되어 갱신해야 하는지 확인합니다.

<h2 id="external-service-accounts">
  외부 서비스 계정
</h2>

W\&B는 오래전부터 수명이 긴 API 키를 사용하는 기본 제공 서비스 계정을 지원해 왔습니다. SDK 및 CLI용 ID 페더레이션을 사용하면 JWT로 인증하는 외부 서비스 계정도 함께 사용할 수 있습니다. 이러한 JWT는 조직에 설정된 발급자가 발급한 것이어야 합니다. 팀 관리자는 기본 제공 서비스 계정과 마찬가지로 팀 범위 내에서 외부 서비스 계정을 설정할 수 있습니다.

외부 서비스 계정을 설정하려면 팀 관리자가 다음 단계를 수행해야 합니다.

1. 팀의 **Service Accounts** 탭으로 이동하세요.
2. **New service account**를 클릭하세요.
3. 서비스 계정의 이름을 입력하세요.
4. **Authentication Method**로 **Federated Identity**를 선택한 다음 **Subject**를 입력하세요. 자세한 내용은 [ID 공급자의 Subject 값 확인](#determine-the-subject-value-for-your-identity-provider)을 참조하세요.
5. **Create**를 클릭하세요.

이 단계를 마치면 외부 서비스 계정이 팀에 등록되며, 설정된 ID 공급자가 발급한 JWT로 W\&B에 액세스할 수 있습니다. 외부 서비스 계정 JWT의 `sub` 클레임은 팀 관리자가 팀 수준 **Service Accounts** 탭에서 설정한 subject와 일치해야 합니다. W\&B는 [JWT 검증](#jwt-validation) 과정에서 이 클레임을 확인합니다. `aud` 클레임 요구 사항은 사람 사용자의 JWT와 비슷합니다.

[외부 서비스 계정의 JWT를 사용해 W\&B에 액세스](#use-the-jwt-to-access-wb)할 때는 워크플로를 자동화하는 편이 더 간편한 경우가 많습니다. 자동화하면 초기 JWT를 생성하고 필요할 때마다 갱신할 수 있습니다. 외부 서비스 계정으로 로깅한 run을 사람 사용자에게 귀속시키려면 기본 제공 서비스 계정과 마찬가지로 AI 워크플로에 환경 변수 `WANDB_USERNAME` 또는 `WANDB_USER_EMAIL`을 설정하세요.

<Note>
  W\&B는 데이터 민감도 수준이 서로 다른 AI 워크로드 전반에서 기본 제공 서비스 계정과 외부 서비스 계정을 함께 사용할 것을 권장합니다. 두 방식을 함께 사용하면 유연성과 단순성 사이에서 균형을 맞출 수 있습니다.
</Note>

<h3 id="determine-the-subject-value-for-your-identity-provider">
  ID 공급자의 Subject 값 확인
</h3>

**Subject**에 입력하는 값은 IdP가 서비스 계정에 발급한 JWT의 `sub`(subject) 클레임과 정확히 일치해야 합니다. W\&B는 모든 ID 공급자에 대해 동일한 방식으로 값을 비교합니다. 완전히 일치해야 하며 대소문자와 공백도 구분하므로, 끝에 공백이 하나 있거나 대소문자가 하나만 달라도 인증에 실패합니다.

**Subject** 값은 전적으로 IdP에 따라 달라지므로, W\&B App은 비어 있지 않은 값이면 유효성을 검사하지 않고 그대로 받아들입니다. 따라서 W\&B는 서비스 계정을 생성할 때 올바르지 않은 값을 감지할 수 없으며, 나중에 서비스 계정이 JWT를 제시하는 시점에 인증이 실패합니다.

올바른 값을 확인하는 가장 확실한 방법은 실제 토큰에서 값을 조회하는 것입니다. 서비스 계정용으로 발급된 샘플 JWT를 획득한 다음, 로컬에서 페이로드(두 점 사이의 가운데 부분)를 base64url 디코딩하고 `sub` 값을 그대로 **Subject** 필드에 복사하세요. JWT는 자격 증명이므로 서드파티 온라인 디코더에 붙여넣지 마세요.

값은 공급자마다 다릅니다. 다음은 일반적인 예시이며, 반드시 실제 토큰과 대조하여 확인하세요.

| ID 공급자 | `sub` 값을 찾는 위치 |
| - | - |
| Microsoft Entra ID | [Microsoft Entra 관리 센터](https://entra.microsoft.com)의 **Enterprise Applications**에서 확인할 수 있는 서비스 주체의 **Object ID**입니다. **App registration**의 Object ID가 아닌 **Enterprise Application**(서비스 주체)의 Object ID를 사용하세요. 앱 전용(클라이언트 자격 증명) 토큰에서는 일반적으로 Entra ID가 이 값을 `sub`에 넣습니다. |
| Google Cloud (GCP) | Google이 서비스 계정용으로 발급하는 ID 토큰의 `sub` 값입니다. |