> ## Documentation Index
> Fetch the complete documentation index at: https://wb-21fd5541-docs-hivemind-launch.mintlify.site/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를 인증할 수 있습니다.

오래 유지되는 API 키를 사용하는 대신, ID 페더레이션을 사용해 조직 자격 증명으로 W\&B SDK 및 CLI에 로그인할 수 있습니다. W\&B 조직 관리자가 조직에 SSO를 구성했다면 이미 해당 자격 증명을 사용해 W\&B App UI에 로그인하고 있습니다. ID 페더레이션은 W\&B SDK용 SSO와 비슷하지만 JSON Web Token(JWT)을 직접 사용합니다. ID 페더레이션을 API 키의 대안으로 사용하세요.

이 페이지는 W\&B 조직의 JWT 발급자를 구성하는 조직 관리자를 위한 문서입니다. 또한 JWT를 사용해 W\&B에 인증하는 사용자 또는 서비스 계정을 위한 문서이기도 합니다.

[RFC 7523](https://datatracker.ietf.org/doc/html/rfc7523)는 SDK의 ID 페더레이션을 뒷받침하는 기반 표준입니다.

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

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

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

사용자가 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 디스커버리 문서를 자동으로 찾습니다. 디스커버리 문서에서 W\&B는 해당 URL의 JSON Web Key Set(JWKS)을 찾습니다. W\&B는 JWT를 실시간으로 검증하기 위해 JWKS를 사용하며, 이를 통해 해당 JWT가 올바른 ID 공급자에 의해 발급되었는지 확인합니다.

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

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

조직 관리자가 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를 자동으로 감지하고, JWT를 검증한 뒤 W\&B 액세스 토큰으로 교환합니다. W\&B 액세스 토큰은 Runs, 메트릭, 아티팩트 로깅과 같이 AI 워크플로를 수행하는 데 필요한 관련 API에 대한 액세스를 부여합니다. 기본적으로 액세스 토큰은 `~/.config/wandb/credentials.json` 경로에 저장됩니다. 환경 변수 `WANDB_CREDENTIALS_FILE`을 지정해 해당 경로를 변경할 수 있습니다.

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

  W\&B 액세스 토큰에도 기본 만료 기간이 있으며, 이 기간이 지나면 SDK 또는 CLI는 JWT를 사용해 이를 갱신하려고 시도합니다. 그 시점에 사용자의 JWT도 만료되었고 갱신되지 않았다면 인증이 실패합니다. 가능하다면 JWT를 가져오고 만료 후 갱신하는 메커니즘을 W\&B SDK 또는 CLI를 사용하는 AI 워크로드의 일부로 구현하세요.
</Note>

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

유효한 토큰만 액세스를 부여하도록 보장하기 위해 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/platform/hosting/hosting-options/dedicated-cloud) 또는 [Self-Managed](/ko/platform/hosting/hosting-options/self-managed) 인스턴스에서는:

  * audience 클레임 검증을 건너뛰려면 환경 변수 `FEDERATED_AUTH_AUDIENCES`를 `wandb`로 설정할 수 있습니다.
  * 일부 조직에는 audience에 대한 특정 요구 사항이 있습니다. `aud` 값을 사용자 지정하려면 환경 변수 `FEDERATED_AUTH_AUDIENCES`를 audience 값의 쉼표로 구분된 목록이 포함된 문자열로 설정하세요.

* W\&B는 JWT의 `exp` 클레임을 확인하여 토큰이 유효한지, 또는 만료되어 새로 고침이 필요한지 판단합니다.

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

W\&B는 오랫동안 장기간 유효한 API 키를 사용하는 기본 제공 서비스 계정을 지원해 왔습니다. SDK 및 CLI용 ID 페더레이션을 사용하면 JWT로 인증하는 외부 서비스 계정도 연동해 사용할 수 있습니다. 이러한 JWT는 조직에 설정된 issuer가 발급해야 합니다. 팀 관리자는 기본 제공 서비스 계정과 마찬가지로 팀 범위 내에서 외부 서비스 계정을 구성할 수 있습니다.

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

1. 팀의 **Service Accounts** 탭으로 이동합니다.
2. **New service account**를 클릭합니다.
3. 서비스 계정 이름을 입력하고, **Authentication Method**로 **Federated Identity**를 선택하고, **Subject**를 입력한 다음, **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를 생성하고 필요할 때마다 이를 갱신합니다. 외부 서비스 계정을 사용해 로깅한 Runs를 일반 사용자에게 귀속시키려면, 기본 제공 서비스 계정과 마찬가지로 AI 워크플로에 환경 변수 `WANDB_USERNAME` 또는 `WANDB_USER_EMAIL`을 설정하세요.

<Note>
  W\&B는 데이터 민감도 수준이 서로 다른 AI 워크로드 전반에서 기본 제공 서비스 계정과 외부 서비스 계정을 혼합해 사용할 것을 권장합니다. 이러한 혼합 방식은 유연성과 단순성 사이의 균형을 맞춰 줍니다.
</Note>