ID 페더레이션은 Multi-tenant Cloud, Dedicated Cloud, Self-Managed에서 프리뷰로 사용할 수 있으며, 엔터프라이즈 라이선스가 필요합니다. 자세한 내용을 확인하거나 도움을 받으려면 담당 AISE 또는 지원팀에 문의하세요.
이 문서에서는 “ID 공급자”와 “JWT 발급자”를 같은 의미로 사용합니다. 이 기능에서 두 용어는 동일한 대상을 가리킵니다.
JWT 발급자 설정
사용자가 JWT로 인증하려면 먼저 조직 관리자가 W&B 조직과 공개적으로 액세스할 수 있는 JWT 발급자 간에 페더레이션을 설정해야 합니다.- 조직 대시보드의 Settings 탭으로 이동하세요.
- Authentication 옵션에서 Set up JWT Issuer를 클릭하세요.
- 텍스트 상자에 JWT 발급자 URL을 입력하고 Create를 클릭하세요.
${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에 인증할 수 있습니다.
JWT를 사용하여 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를 자동으로 감지하여 검증한 후 W&B 액세스 토큰으로 교환합니다. W&B 액세스 토큰을 사용하면 run, 메트릭, 아티팩트 로깅 등 AI 워크플로에 필요한 API에 액세스할 수 있습니다. 액세스 토큰은 기본적으로
~/.config/wandb/credentials.json경로에 저장됩니다. 이 경로는 환경 변수WANDB_CREDENTIALS_FILE을 지정하여 변경할 수 있습니다.
JWT는 API 키나 비밀번호 같은 장기 자격 증명의 단점을 보완하는 단기 자격 증명입니다. JWT 만료 시간은 ID 공급자의 설정에 따라 다릅니다. JWT가 만료되기 전에 갱신하고, 갱신된 JWT가 환경 변수
WANDB_IDENTITY_TOKEN_FILE이 참조하는 파일에 저장되어 있는지 확인하세요.W&B 액세스 토큰에도 기본 만료 기간이 있으며, 기간이 지나면 SDK 또는 CLI가 JWT를 사용하여 토큰 갱신을 시도합니다. 이 시점에 사용자 JWT도 만료되었고 갱신되지 않은 상태라면 인증에 실패합니다. 가능하면 W&B SDK 또는 CLI를 사용하는 AI 워크로드에 JWT 발급 및 만료 후 갱신 메커니즘을 함께 구현하세요.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 또는 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는 조직에 설정된 발급자가 발급한 것이어야 합니다. 팀 관리자는 기본 제공 서비스 계정과 마찬가지로 팀 범위 내에서 외부 서비스 계정을 설정할 수 있습니다. 외부 서비스 계정을 설정하려면 팀 관리자가 다음 단계를 수행해야 합니다.- 팀의 Service Accounts 탭으로 이동하세요.
- New service account를 클릭하세요.
- 서비스 계정의 이름을 입력하세요.
- Authentication Method로 Federated Identity를 선택한 다음 Subject를 입력하세요. 자세한 내용은 ID 공급자의 Subject 값 확인을 참조하세요.
- Create를 클릭하세요.
sub 클레임은 팀 관리자가 팀 수준 Service Accounts 탭에서 설정한 subject와 일치해야 합니다. W&B는 JWT 검증 과정에서 이 클레임을 확인합니다. aud 클레임 요구 사항은 사람 사용자의 JWT와 비슷합니다.
외부 서비스 계정의 JWT를 사용해 W&B에 액세스할 때는 워크플로를 자동화하는 편이 더 간편한 경우가 많습니다. 자동화하면 초기 JWT를 생성하고 필요할 때마다 갱신할 수 있습니다. 외부 서비스 계정으로 로깅한 run을 사람 사용자에게 귀속시키려면 기본 제공 서비스 계정과 마찬가지로 AI 워크플로에 환경 변수 WANDB_USERNAME 또는 WANDB_USER_EMAIL을 설정하세요.
W&B는 데이터 민감도 수준이 서로 다른 AI 워크로드 전반에서 기본 제공 서비스 계정과 외부 서비스 계정을 함께 사용할 것을 권장합니다. 두 방식을 함께 사용하면 유연성과 단순성 사이에서 균형을 맞출 수 있습니다.
ID 공급자의 Subject 값 확인
Subject에 입력하는 값은 IdP가 서비스 계정에 발급한 JWT의sub(subject) 클레임과 정확히 일치해야 합니다. W&B는 모든 ID 공급자에 대해 동일한 방식으로 값을 비교합니다. 완전히 일치해야 하며 대소문자와 공백도 구분하므로, 끝에 공백이 하나 있거나 대소문자가 하나만 달라도 인증에 실패합니다.
Subject 값은 전적으로 IdP에 따라 달라지므로, W&B App은 비어 있지 않은 값이면 유효성을 검사하지 않고 그대로 받아들입니다. 따라서 W&B는 서비스 계정을 생성할 때 올바르지 않은 값을 감지할 수 없으며, 나중에 서비스 계정이 JWT를 제시하는 시점에 인증이 실패합니다.
올바른 값을 확인하는 가장 확실한 방법은 실제 토큰에서 값을 조회하는 것입니다. 서비스 계정용으로 발급된 샘플 JWT를 획득한 다음, 로컬에서 페이로드(두 점 사이의 가운데 부분)를 base64url 디코딩하고 sub 값을 그대로 Subject 필드에 복사하세요. JWT는 자격 증명이므로 서드파티 온라인 디코더에 붙여넣지 마세요.
값은 공급자마다 다릅니다. 다음은 일반적인 예시이며, 반드시 실제 토큰과 대조하여 확인하세요.