# 認証 {#bot-authentication} [ボット](/docs/ja/c/bot/index.md) は、`shishoctl` CLI を使って以下の 4 通りの方法のいずれかで Shisho Cloud にサインインできます。 | 環境 | 推奨認証方法 | | ------------------------------------------------------- | ------------------------------------------- | | GitHub Actions | [GitHub Actions OIDC](#github-actions-oidc) | | GitLab CI | [GitLab CI OIDC](#gitlab-ci-oidc) | | 自前で運用する CI/CD やその他の OIDC Discovery 対応 IdP | [カスタム OIDC](#custom-oidc) | | その他の CI/CD・自動化環境 | [API キー](#api-key) | OIDC を使う 3 つの方法は、いずれも **信頼条件（Trust Condition）** に基づいています。信頼条件とは、ボット側に設定しておく規則で、どの OIDC ID トークンをそのボットとしてのサインインの証明として受け入れるかを決めるものです。信頼条件では静的なシークレットを保管・漏洩させる必要がなく、IdP がジョブごとに短命なトークンを発行するため、Shisho Cloud は一時的な認証情報しか扱いません。この点で、信頼条件は API キーより安全な方法です。 ## API キー {#api-key} OIDC 対応環境以外でボット認証を行う場合、API Key を使用して `shishoctl` から Shisho Cloud にアクセスできます。 APIキーはボットに紐づく概念です。そのため、ボットを未だ作成していない場合は、まずボットを作成しましょう。具体的な手順は以下です。 1. [ボット一覧](https://cloud.shisho.dev/*/settings/bots) ページにアクセスする 2. 「ボットの追加」ボタンから、新しいボットを作成する ![ボット作成画面](/docs/ja/_md-assets/d6e927005e-bot-creation.png) 作成できたら、以下の手順でAPIキーが発行できます。 1. [ボット一覧](https://cloud.shisho.dev/*/settings/bots) ページにアクセスする。 2. 作成したボットの名前をクリックし、個別ページを開く。 3. APIキータブで、「APIキーの作成」を押下し、ボットの API キーを新規作成する。 ![API キー作成画面](/docs/ja/_md-assets/411cecba16-api-key-creation.png) :::warning 重要 API キーは作成時に一度しか表示されません。あとからの再確認は不可能なので、作成時に控え、安全な場所に保存してください。 ::: 以下のコマンドで API キーを使って認証してください: ```shell shishoctl auth signin:bot \ --bot \ --api-key-json "$(cat api-key.json)" ``` なお、`api-key.json` ファイルは、以下のような JSON 形式で作成する必要があります。 ```json { "api_key": "shisho_apikey_..." } ``` または API Key を直接指定することもできます: ```shell shishoctl auth signin:bot \ --bot \ --api-key-json '{"api_key":"shisho_apikey_..."}' ``` :::info Bot ID は `BT`から始まるIDで、[ボット作成画面](https://cloud.shisho.dev/*/settings/bots)で作成後、ボットの詳細ページURLにて確認できます。 https://cloud.shisho.dev/{ORGANIZATION_ID}/settings/bots/{BOT_ID} ::: :::warning セキュリティのベストプラクティス一般的な SaaS の API キーと同様に、ボットの API キーが漏れると、Shisho Cloud 上のデータが侵害される可能性があります。安全に扱うため、以下に留意ください。 - API キーを外部公開しない。特に、GitHub 等の公開リポジトリにコミットしない。 - 非公開領域に API キーを保管する場合も、極力安全な場所を利用する。例えば、GitHub リポジトリ内に直接含めるよりは、GitHub Actions のシークレット管理機能を利用する。 - 不要になった API キーは速やかに削除する。 ::: ## GitHub Actions OIDC {#github-actions-oidc} GitHub Actions 上で実行されるジョブに対しては、GitHub がジョブごとに発行する OIDC の ID トークンを使って Shisho Cloud への認証を行うため、リポジトリに永続的なシークレットを保管する必要がありません。Shisho Cloud はこのトークンを、特定のボットに紐づく短命な認証情報と交換します。これは [GitHub 自身が提供する OIDC ベースのクラウド連携](https://github.blog/changelog/2021-10-27-github-actions-secure-cloud-deployments-with-openid-connect/) と同様の仕組みです。 GitHub Actions 用のボットに設定する信頼条件は、ジョブが実行される GitHub リポジトリの **Organization およびリポジトリ名** の一致を条件とします。信頼条件を保存すると、そのリポジトリに属するジョブは、そのボットとしてサインインできるようになります。ジョブからサインインするには、ID トークンを取得したうえで、以下のコマンドを実行してください。 ```shell shishoctl auth signin:bot \ --bot \ --expires-in-minutes 60 \ <<< "$ID_TOKEN" ``` コンソールでのボット・信頼条件の作成から GitHub Actions ワークフローの構築までの詳しい手順は、[検査ルールを Git リポジトリで管理する - GitHub](/docs/ja/g/getting-started/deploy-policies-with-git-repositories/github.md) を参照してください。 ## GitLab CI OIDC {#gitlab-ci-oidc} GitLab CI/CD 上で実行されるジョブに対しては、GitLab がジョブに発行する OIDC の `ID_TOKEN` を使って Shisho Cloud への認証を行うため、Shisho Cloud のアクセストークンを GitLab CI/CD のシークレットとして登録する必要はありません。 GitLab CI 用のボットに設定する信頼条件は、プロジェクトの **プロジェクトパス**（プロジェクトの URL のうち、最上位のグループ名から始まりプロジェクト名で終わる部分。例: `my-group/my-subgroup/my-project`）の一致を条件とします。信頼条件を保存すると、そのプロジェクトに属するジョブは、そのボットとしてサインインできるようになります。 :::warning GitLab では、グループ・サブグループ・プロジェクトの表示名と URL 上のパスが異なる場合があります。信頼条件を設定する際は、表示名ではなく、プロジェクトの URL に実際に使われているパスを確認してください。 ::: ジョブからサインインするには、ID トークンを取得したうえで、以下のコマンドを実行してください。 ```shell shishoctl auth signin:bot \ --bot ${SHISHOCLOUD_BOT_ID} \ --expires-in-minutes 60 \ <<< ${ID_TOKEN} ``` コンソールでのボット・信頼条件の作成から GitLab CI/CD ジョブの構築までの詳しい手順は、[検査ルールを Git リポジトリで管理する - GitLab](/docs/ja/g/getting-started/deploy-policies-with-git-repositories/gitlab.md) を参照してください。 ## カスタム OIDC {#custom-oidc} :::info カスタム OIDC プロバイダーのサポートは現在ベータ版です。仕様や挙動が予告なく変更される可能性があります。 ::: この方法は、以下のような場合におすすめです。 - Jenkins や Buildkite など、自前で運用する CI/CD から Shisho Cloud にアクセスしたい場合 - AWS IAM Roles Anywhere や GCP Workload Identity Federation など、他クラウドのワークロード ID 基盤から Shisho Cloud にアクセスしたい場合 - GitHub Actions や GitLab CI 以外にも、OIDC の ID トークンを発行できる IdP を使っている場合こうした環境でも、OIDC の ID トークンを発行できるものであれば、信頼条件をその発行者 (issuer) に対して直接設定できます。利用にあたっては、issuer が `https://` で提供されていて、OIDC Discovery のドキュメント (`/.well-known/openid-configuration`) を公開している必要があります。カスタム OIDC の信頼条件では、以下の項目を設定します。Issuer・Subject・Audience は必須、Claims は任意です。 - **Issuer** - ID トークンの発行者 (`iss` クレーム) を示す `https://` の URL。 - **Subject** - ID トークンの `sub` クレームに期待する値。完全一致の値か、`*` が任意の文字列にマッチする式 (例: `repo:acme/app:*`) のいずれかを指定する。`*` のみの式は指定できず、IdP の subject の形式が許す限り絞り込むことが望ましい。ワイルドカードを増やすほど、そのボットとしてサインインできる対象が広がる。 - **Audience** - ID トークンの `aud` クレームが含んでいなければならない値。カスタム OIDC の信頼条件ではこの指定が必須で (GitHub Actions / GitLab CI のスキーマとは異なる)、IdP 側で `https://sts.cloud.shisho.dev` を audience として発行するよう設定することを推奨する。こうすることで、Shisho Cloud 向けに発行したトークンが他のサービスへ再利用されるのを防げる。 - **Claims** (任意) - トークンのトップレベルの文字列クレームに対する追加条件を、最大 10 件まで指定できる。指定方法は Subject と同じで、完全一致の値か `*` を使った式のいずれかを使う。`iss` や `sub`、`aud` などの登録済みクレームはキーに使用できない。 :::info 上限カスタム OIDC の信頼条件は、1 組織につき **1 件**までです（組織内のすべてのボットを通じての合計）。GitHub Actions と GitLab CI の信頼条件に上限はありません。 2 件以上が必要な場合はサポートにご相談ください。ご契約プランによってはお応えできない場合があります。 ::: 例えば、あるセルフホスト IdP からの、タグ付きリリースかつ production 環境のデプロイのみを受け付ける信頼条件は、以下のような設定になります。 | 項目 | 値 | | -------- | --------------------------------------------------- | | Issuer | `https://idp.example.com` | | Subject | `repo:acme/app:*` | | Audience | `https://sts.cloud.shisho.dev` | | Claims | `environment` = `production`、`ref` = `refs/tags/*` | 信頼条件の保存後、CI 側のサインインの流れは GitHub Actions や GitLab CI の場合と同じです。IdP から ID トークンを取得し、以下のコマンドでサインインしてください。 ```shell shishoctl auth signin:bot \ --bot \ --expires-in-minutes 60 \ <<< "$ID_TOKEN" ``` :::warning セキュリティのベストプラクティス - **Subject** はできる限り絞り込む。ワイルドカードを追加するほど、そのボットとしてサインインできる対象が広がる。`*` のみの Subject は指定できない。 - IdP 側で **Audience** (`aud`) クレームを `https://sts.cloud.shisho.dev` に設定する。信頼条件はこの値の存在を必須としており、IdP 側で明示的に設定しておくことで、同じトークンが無関係なサービスに受理されるのを防げる。 - Subject のワイルドカードだけに頼らず、ブランチやタグ、環境名など IdP が `sub` に含めない情報は **Claims** の条件で絞り込む。 :::