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

ID 페더레이션을 사용하면 W\&B SDK를 통해 조직 자격 증명으로 로그인할 수 있습니다. W\&B 조직 관리자가 조직에 SSO를 구성했다면 이미 조직 자격 증명을 사용해 W\&B App UI에 로그인하고 있을 것입니다. 그런 의미에서 ID 페더레이션은 W\&B SDK용 SSO와 비슷하지만 JSON Web Token(JWT)을 직접 사용한다는 점이 다릅니다. ID 페더레이션은 API 키의 대안으로 사용할 수 있습니다.

[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="jwt-issuer-setup">
  ## JWT 발급자 설정
</div>

첫 번째 step으로, 조직 관리자는 W\&B 조직과 공개적으로 접근 가능한 JWT 발급자 간의 페더레이션을 설정해야 합니다.

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

W\&B는 `${ISSUER_URL}/.well-known/openid-configuration` 경로에서 OIDC 디스커버리 문서를 자동으로 찾고, 디스커버리 문서의 관련 URL에서 JSON Web Key Set(JWKS)을 찾습니다. JWKS는 해당 JWT가 관련 ID 공급자에서 발급되었는지 확인하기 위해 JWT를 실시간으로 검증하는 데 사용됩니다.

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

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

* 조직에서 사용할 수 있는 방식 중 하나로 ID 공급자에 로그인해야 합니다. 일부 공급자는 API 또는 SDK를 사용해 자동화된 방식으로 액세스할 수 있지만, 일부는 해당 UI를 통해서만 액세스할 수 있습니다. 자세한 내용은 W\&B 조직 관리자 또는 JWT 발급자 소유자에게 문의하세요.
* ID 공급자에 로그인한 뒤 JWT를 조회했으면, 이를 안전한 위치의 파일에 저장하고 해당 파일의 절대 경로를 환경 변수 `WANDB_IDENTITY_TOKEN_FILE`에 설정하세요.
* W\&B SDK 또는 CLI를 사용해 W\&B 프로젝트에 액세스하세요. SDK 또는 CLI는 JWT를 자동으로 감지하고, JWT가 성공적으로 검증되면 이를 W\&B 액세스 토큰으로 교환합니다. W\&B 액세스 토큰은 AI 워크플로를 수행하는 데 필요한 관련 API에 액세스하는 데 사용됩니다. 즉, run, 메트릭, artifact 등을 기록하는 데 사용됩니다. 액세스 토큰은 기본적으로 `~/.config/wandb/credentials.json` 경로에 저장됩니다. 환경 변수 `WANDB_CREDENTIALS_FILE`을 지정해 해당 경로를 변경할 수 있습니다.

<Note>
  JWT는 API 키, 비밀번호 등과 같은 장기 자격 증명의 한계를 보완하기 위한 단기 자격 증명입니다. ID 공급자에 설정된 JWT 만료 시간에 따라 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를 W\&B 액세스 토큰으로 교환한 뒤 프로젝트에 액세스하는 워크플로의 일부로, JWT에는 다음과 같은 검증이 수행됩니다.

* JWT 서명은 W\&B 조직 수준의 JWKS를 사용해 검증됩니다. 이는 첫 번째 방어선이며, 이 검증이 실패하면 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 값의 쉼표로 구분된 목록이 포함된 문자열로 설정하세요.

* JWT의 `exp` 클레임은 토큰이 유효한지, 또는 만료되어 새로 고침이 필요한지 확인하기 위해 검사됩니다.

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

W\&B는 오랫동안 수명이 긴 API 키를 사용하는 기본 제공 서비스 계정을 지원해 왔습니다. SDK 및 CLI의 ID 페더레이션 기능을 사용하면 외부 서비스 계정도 사용할 수 있습니다. 단, 인증에 JWT를 사용하려면 조직 수준에서 구성한 것과 동일한 issuer가 발급한 JWT여야 합니다. 팀 관리자는 기본 제공 서비스 계정과 마찬가지로 팀 범위 내에서 외부 서비스 계정을 구성할 수 있습니다.

외부 서비스 계정을 구성하려면 다음을 수행합니다.

* 팀의 **Service Accounts** 탭으로 이동합니다.
* **New service account**를 클릭합니다.
* 서비스 계정 이름을 입력하고, `Authentication Method`로 `Federated Identity`를 선택하고, `Subject`를 입력한 다음, **Create**를 클릭합니다.

외부 서비스 계정 JWT의 `sub` 클레임은 팀 수준의 **Service Accounts** 탭에서 팀 관리자가 해당 계정의 subject로 구성한 값과 같아야 합니다. 이 클레임은 [JWT 검증](#jwt-validation)의 일부로 검증됩니다. `aud` 클레임 요구 사항도 사람 사용자 JWT의 경우와 유사합니다.

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

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