> ## Documentation Index
> Fetch the complete documentation index at: https://wb-21fd5541-docs-sandboxes-integrations-placement.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 페더레이션을 뒷받침하는 기반 표준입니다.
ID 페더레이션은 Multi-tenant Cloud, Dedicated Cloud 및 Self-Managed에서 프리뷰로 사용 가능합니다. [엔터프라이즈 라이선스](/ko/platform/hosting/enterprise-licenses)가 필요합니다. 자세한 내용이나
도움이 필요하면 AISE 또는 [지원팀](mailto:support@wandb.com)에 문의하세요.
이 문서에서는 "ID 공급자"와 "JWT 발급자"라는 용어를 같은 의미로 사용합니다. 이 기능의 맥락에서 두 용어는 모두 동일한 대상을 가리킵니다.
## JWT 발급자 설정
사용자가 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에 인증할 수 있습니다.
## JWT를 사용하여 W\&B에 액세스하기
조직 관리자가 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`을 지정해 해당 경로를 변경할 수 있습니다.
JWT는 API 키 및 비밀번호와 같은 장기 자격 증명의 단점을 보완하는 단기 자격 증명입니다. JWT 만료 시간은 ID 공급자의 설정에 따라 달라집니다. JWT가 만료되기 전에 갱신하고, 환경 변수 `WANDB_IDENTITY_TOKEN_FILE`이 가리키는 파일에 저장되어 있는지 확인하세요.
W\&B 액세스 토큰에도 기본 만료 기간이 있으며, 이 기간이 지나면 SDK 또는 CLI는 JWT를 사용해 이를 갱신하려고 시도합니다. 그 시점에 사용자의 JWT도 만료되었고 갱신되지 않았다면 인증이 실패합니다. 가능하다면 JWT를 가져오고 만료 후 갱신하는 메커니즘을 W\&B SDK 또는 CLI를 사용하는 AI 워크로드의 일부로 구현하세요.
### JWT 검증
유효한 토큰만 액세스를 부여하도록 보장하기 위해 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` 클레임을 확인하여 토큰이 유효한지, 또는 만료되어 새로 고침이 필요한지 판단합니다.
## 외부 서비스 계정
W\&B는 오랫동안 장기간 유효한 API 키를 사용하는 기본 제공 서비스 계정을 지원해 왔습니다. SDK 및 CLI용 ID 페더레이션을 사용하면 JWT로 인증하는 외부 서비스 계정도 연동해 사용할 수 있습니다. 이러한 JWT는 조직에 설정된 issuer가 발급해야 합니다. 팀 관리자는 기본 제공 서비스 계정과 마찬가지로 팀 범위 내에서 외부 서비스 계정을 구성할 수 있습니다.
외부 서비스 계정을 구성하려면 팀 관리자가 다음을 수행해야 합니다.
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를 생성하고 필요할 때마다 이를 갱신합니다. 외부 서비스 계정을 사용해 로깅한 Runs를 일반 사용자에게 귀속시키려면, 기본 제공 서비스 계정과 마찬가지로 AI 워크플로에 환경 변수 `WANDB_USERNAME` 또는 `WANDB_USER_EMAIL`을 설정하세요.
W\&B는 데이터 민감도 수준이 서로 다른 AI 워크로드 전반에서 기본 제공 서비스 계정과 외부 서비스 계정을 혼합해 사용할 것을 권장합니다. 이러한 혼합 방식은 유연성과 단순성 사이의 균형을 맞춰 줍니다.
### ID 공급자의 Subject 값 확인
**Subject**에 입력하는 값은 서비스 계정용으로 IdP가 발급한 JWT의 `sub`(subject) 클레임과 정확히 일치해야 합니다. W\&B는 모든 ID 공급자에 대해 동일한 방식으로 비교합니다. 이 일치는 대/소문자를 구분하고 공백에도 민감하므로, 끝에 공백이 하나 있거나 대소문자가 다르기만 해도 인증에 실패합니다.
W\&B App은 이 값이 전적으로 IdP에 따라 결정되므로, 값을 검증하지 않고 비어 있지 않은 모든 **Subject**를 허용합니다. 따라서 서비스 계정을 만들 때는 올바르지 않은 값을 감지할 수 없습니다. 대신 나중에 서비스 계정이 JWT를 제시해 인증을 시도할 때 실패합니다.
올바른 값을 확인하는 가장 확실한 방법은 실제 토큰에서 직접 조회하는 것입니다. 서비스 계정용으로 발급된 샘플 JWT를 획득한 뒤, 해당 payload(가운데 세그먼트, 두 점 사이)를 로컬에서 base64url로 디코딩하고, `sub` 값을 **Subject** 필드에 그대로 복사하세요. JWT는 자격 증명이므로 서드파티 온라인 디코더에 붙여넣지 마세요.
이 값은 공급자마다 다릅니다. 아래는 일반적인 예이지만, 항상 실제 토큰으로 확인하세요.
| ID 공급자 | `sub` 값을 찾는 위치 |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Microsoft Entra ID | [Microsoft Entra admin center](https://entra.microsoft.com)의 **Enterprise Applications**에서 찾을 수 있는 서비스 주체의 **Object ID**입니다. **App registration** Object ID가 아니라 **Enterprise Application**(서비스 주체) Object ID를 사용하세요. 앱 전용(client credentials) 토큰의 경우, 일반적으로 Entra ID는 이 값을 `sub`에 넣습니다. |
| Google Cloud (GCP) | Google이 서비스 계정에 대해 발급한 ID 토큰의 `sub` 값입니다. |