> ## Documentation Index
> Fetch the complete documentation index at: https://wb-21fd5541-dbrian-docs-serverless-training-quickstart.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# SDKでフェデレーテッド アイデンティティを使用する
> JSON Web Tokens（JWT）を使ったアイデンティティ フェデレーションにより、APIキーを使わずにW&B SDKおよびCLIで認証できます。
長期間有効なAPIキーの代わりに、アイデンティティ フェデレーションを使用して、組織の認証情報でW\&B SDKおよびCLIにサインインできます。W\&B組織管理者が組織に対してSSOを設定している場合、W\&B App UIにはすでにそれらの認証情報でサインインしています。アイデンティティ フェデレーションはW\&B SDK向けのSSOに似ていますが、JSON Web Tokens (JWT) を直接使用する点が異なります。アイデンティティ フェデレーションは、APIキーの代替として使用できます。
このページは、W\&B組織のJWT issuerを設定する組織管理者向けです。また、JWTを使用してW\&Bに認証するユーザーやサービスアカウント向けでもあります。
[RFC 7523](https://datatracker.ietf.org/doc/html/rfc7523)は、SDKでのアイデンティティ フェデレーションの基盤となる仕様です。
アイデンティティ フェデレーションは、Multi-tenant Cloud、専用クラウド、セルフマネージドでプレビューとして利用できます。[Enterprise ライセンス](/ja/platform/hosting/enterprise-licenses)が必要です。詳細や
サポートが必要な場合は、担当のAISEまたは[サポート](mailto:support@wandb.com)にお問い合わせください。
このドキュメントでは、"アイデンティティプロバイダ"と"JWT issuer"という用語を同じ意味で使用しています。どちらも、この機能の文脈では同じものを指します。
## JWT issuer を設定する
ユーザーが JWT で認証できるようになる前に、組織管理者は W\&B 組織と公開されている JWT issuer の間でフェデレーションを設定する必要があります。
1. 組織のダッシュボードで **Settings** タブにアクセスします。
2. **Authentication** オプションで、**Set up JWT Issuer** をクリックします。
3. テキストボックスに JWT issuer の URL を入力し、**Create** をクリックします。
W\&B は、`${ISSUER_URL}/.well-known/openid-configuration` のパスにある OIDC discovery document を自動的に参照します。discovery document から、W\&B は該当する URL にある JSON Web Key Set (JWKS) を特定します。W\&B は JWKS を使用して JWT をリアルタイムで検証し、該当するアイデンティティプロバイダによって発行されたことを確認します。
この手順を完了すると、W\&B 組織は JWT issuer とフェデレーションされます。すると、組織内の Users は、その provider が発行した JWT を使用して W\&B に認証できるようになります。
## JWT を使用して W\&B にアクセスする
組織管理者が JWT issuer を設定すると、ユーザーはそのアイデンティティプロバイダが発行した JWT を使用して W\&B のプロジェクトにアクセスできるようになります。JWT を使用する仕組みは次のとおりです。
1. 組織で利用可能な方法のいずれかを使用して、アイデンティティプロバイダにサインインする必要があります。一部のプロバイダには API または SDK を使用して自動的にアクセスできますが、関連する UI からしかアクセスできないものもあります。詳細については、W\&B 組織管理者または JWT issuer の所有者にお問い合わせください。
2. アイデンティティプロバイダにサインインして JWT を取得したら、安全な場所にあるファイルに保存します。絶対ファイルパスを環境変数 `WANDB_IDENTITY_TOKEN_FILE` に設定してください。
3. W\&B SDK または CLI を使用して、W\&B のプロジェクトにアクセスします。SDK または CLI は JWT を自動的に検出し、JWT を検証した後、それを W\&B アクセストークンに交換します。W\&B アクセストークンは、run、メトリクス、アーティファクトのログ記録など、AI ワークフローを実行するために必要な関連 API へのアクセスを許可します。デフォルトでは、アクセストークンは `~/.config/wandb/credentials.json` に保存されます。環境変数 `WANDB_CREDENTIALS_FILE` を指定することで、その保存先を変更できます。
JWT は、APIキーやパスワードなどの長期間有効な認証情報の欠点を補う、短期間のみ有効な認証情報です。JWT の有効期限は、アイデンティティプロバイダの設定によって異なります。有効期限が切れる前に JWT を更新し、環境変数 `WANDB_IDENTITY_TOKEN_FILE` が参照するファイルに保存されていることを確認してください。
W\&B アクセストークンにもデフォルトの有効期間があり、その後 SDK または CLI は JWT を使用して更新を試みます。その時点でユーザーの JWT も期限切れになっており、更新されていない場合は、認証に失敗します。可能であれば、JWT の取得と期限切れ後の更新の仕組みを、W\&B SDK または CLI を使用する AI ワークロードの一部として実装してください。
### JWT 検証
有効なトークンのみがアクセスを許可することを確実にするため、JWT には次の検証が行われます。これらの検証は、SDK または CLI が JWT を W\&B アクセストークンに交換し、その後 project にアクセスする際に実行されます。
* W\&B は、W\&B 組織レベルの JWKS を使用して JWT 署名を検証します。これは最初の防御策であり、ここで失敗する場合は、JWKS または JWT の署名方法に問題があることを示します。
* JWT の `iss` クレームは、組織レベルで設定された issuer URL と一致している必要があります。
* JWT の `sub` クレームは、W\&B 組織で設定されたユーザーのメールアドレスと一致している必要があります。
* JWT の `aud` クレームは、AI ワークフローの一環としてアクセスするプロジェクトが属する W\&B 組織の名と一致している必要があります。
[専用クラウド](/ja/platform/hosting/hosting-options/dedicated-cloud) または [セルフマネージド](/ja/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 のアイデンティティ フェデレーションにより、認証に JWT を使用する外部サービスアカウントも利用できます。これらの JWT は、組織で設定された issuer によって発行されている必要があります。チーム管理者は、組み込みサービスアカウントと同様に、チームの範囲内で外部サービスアカウントを設定できます。
外部サービスアカウントを設定するには、チーム管理者は次を実行する必要があります。
1. チームの **Service Accounts** タブにアクセスします。
2. **New service account** をクリックします。
3. サービスアカウントの名前を入力します。
4. **Authentication Method** として **Federated Identity** を選択し、**Subject** を入力します。[アイデンティティ プロバイダの Subject 値を特定する](#determine-the-subject-value-for-your-identity-provider) を参照してください。
5. **Create** をクリックします。
この手順を完了すると、外部サービスアカウントがチームに登録され、設定されたアイデンティティプロバイダが発行した 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` を設定します。
W\&B は、データの機密性レベルが異なる AI ワークロード全体で、組み込みサービスアカウントと外部サービスアカウントを組み合わせて使用することを推奨します。この組み合わせにより、柔軟性とシンプルさのバランスを取ることができます。
### アイデンティティプロバイダの Subject の値を確認する
**Subject** に入力する値は、サービスアカウントに対して IdP が発行する JWT の `sub` (subject) クレームと完全に一致している必要があります。W\&B では、すべてのアイデンティティプロバイダに対して同じ方法で比較を行います。この一致は完全一致で、大文字と小文字、および空白も区別されます。そのため、末尾に空白が 1 つあるだけでも、あるいは大文字・小文字が異なるだけでも、認証は失敗します。
W\&B App では、**Subject** の値は IdP に完全に依存するため、その値を検証せず、空でない **Subject** であれば受け入れます。W\&B は、サービスアカウントの作成時点では誤った値を検出できません。代わりに、サービスアカウントが JWT を提示した時点で、後から認証が失敗します。
正しい値を確認する最も確実な方法は、実際の token から読み取ることです。サービスアカウント用に発行された JWT のサンプルを取得し、その payload (2 つのドットの間にある中央のセグメント) をローカルで base64url デコードして、`sub` の値をそのまま **Subject** フィールドにコピーしてください。JWT は認証情報であるため、サードパーティのオンラインデコーダには貼り付けないでください。
値は provider ごとに異なります。以下は一般的な例ですが、必ず実際の token で確認してください。
| アイデンティティプロバイダ | `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) の token では、通常、Entra ID はこの値を `sub` に設定します。 |
| Google Cloud (GCP) | Google がサービスアカウントに対して発行する ID token の `sub` 値です。 |