概要
APIキーを使用すると、プログラムからCaseBenderにアクセスできます。自分のアカウントと現在の組織で利用可能なキーを管理するには、設定 → アカウント → APIキーを開きます。 このページでは、次の機能を利用できます。- 検索およびステータスまたは階層による絞り込み
- マスクされたキー識別子
- ステータス、階層、最終使用日時、リクエスト数
- 使用状況の統計
- ローテーション、一時停止、失効、削除などのライフサイクル操作
前提条件
- ロールで書き込み操作とAPIキー管理が許可されている必要があります。
- 利用できるスコープはロールに応じて絞り込まれます。
- キーの作成、失効、削除には、ステップアップ認証が必要な場合があります。
- 組織で追加の認証ポリシーとアクセスポリシーが適用される場合があります。
APIキーを作成する
1
APIキーを開く
設定 → アカウント → APIキーに移動します。
2
作成を開始する
APIキーを作成を選択します。
3
キーを説明する
ワークロード、所有者、目的を識別できる明確な名前と、任意の説明を入力します。
4
階層を選択する
ワークロードで想定されるリクエスト量に適した階層を選択します。利用可能な階層はBasicからUnlimitedまでです。
5
有効期限を設定する
必要に応じて、有効期限までの日数を入力します。本番環境の認証情報には、ポリシーに準拠した短い有効期間を推奨します。
6
スコープを選択する
1つ以上のスコープを選択します。ワークロードがロールで利用可能なすべてのスコープを正当に必要とする場合にのみ、すべて選択を使用してください。
7
作成して認証する
キーを作成を選択し、求められた場合はステップアップ認証を完了します。
8
認証情報を保存する
APIキーを保存に表示された完全なキーを承認済みのシークレットマネージャーにコピーしてから、完了を選択します。
スコープを選択する
スコープでは、cases:readやorganizations:*のようなリソースとアクションのパターンを使用します。スコープのカテゴリには、ケース、アラート、タスク、ユーザー、チーム、組織、設定、APIキー管理などがあります。
最小権限の原則に従ってください。
- レポート作成と検索のワークロードには、読み取り専用スコープを使用します。
- 統合で変更操作を実行する場合にのみ、書き込みスコープを付与します。
- 単一目的の統合では、ワイルドカードスコープと管理スコープを避けます。
- 関係のないサービスや環境には、別々のキーを作成します。
- 統合を変更するたびに、必要なスコープを確認します。
階層を選択する
階層は、キーに意図されたサービスクラスを記録します。利用可能な階層は次のとおりです。- Basic
- Standard
- Professional
- Enterprise
- Unlimited
APIリクエストを認証する
対応している単一キー用ヘッダーのいずれかで、完全なキーを使用します。推奨：Bearerトークン
代替：X-Api-Key
キーは環境変数またはシークレット注入機構に保存してください。実際のキーをシェル履歴やソースコードに直接貼り付けないでください。
キーのステータスを理解する
- Activeのキーは、スコープとポリシーのチェックを条件としてリクエストを認証できます。
- Suspendedのキーは一時的に無効で、再度有効にできます。
- Revokedのキーは永久に無効です。
- Expiredのキーは、設定された有効期限を過ぎています。
使用状況の統計を表示する
キーのアクションメニューを開き、統計を表示を選択すると、次の項目を確認できます。- リクエスト総数
- 成功したリクエスト数
- 失敗したリクエスト数
- 平均応答時間
- 上位のエンドポイント
キーをローテーションする
ローテーションでは、現在のシークレットを新しいものに置き換えます。1
利用側を準備する
キーを使用するサービスをすぐに更新でき、ロールバック計画があることを確認します。
2
ローテーションする
キーのアクションメニューを開き、キーをローテーションを選択します。
3
新しいキーを保存する
新しく表示された認証情報をシークレットマネージャーにコピーします。
4
更新して検証する
キーを使用するワークロードを更新し、必要に応じて再起動または再デプロイして、スコープ内のテストリクエストを送信します。
キーを一時停止または再有効化する
調査または計画メンテナンス中にキーを一時的に停止するには、一時停止を使用します。認証情報とその利用側が信頼できることを確認した後にのみ、再有効化を使用してください。 元に戻せる封じ込め操作が必要な場合は、削除よりも一時停止が適しています。キーを失効させる
認証情報が侵害された、信頼できなくなった、または永久に廃止する場合は、失効を使用します。失効にはステップアップ認証が必要な場合があり、元に戻すことはできません。 失効後は、次を実施します。- すべての利用側からシークレットを削除します。
- 使用状況の統計とセキュリティテレメトリーを確認します。
- 想定外のリクエストを調査します。
- ワークロードが引き続き認可されている場合にのみ、別の置換キーを作成します。
キーを削除する
削除すると、キーレコードと直接の管理表示がなくなります。ステップアップ認証が必要な場合があります。セキュリティに関する推奨事項
- 指名された担当者とワークロード所有者を割り当てます。
- 本番、ステージング、開発には別々のキーを使用します。
- 認証情報ポリシーに沿った有効期限を設定します。
- 漏えいが疑われる場合は直ちにローテーションします。
- 失敗したリクエストと想定外のエンドポイントを監視します。
- 未使用のキーを有効なまま残さず、失効させます。
- メールやコラボレーションツールでキーを送信しないでください。
トラブルシューティング
キーの作成が拒否される
名前を入力し、1つ以上のスコープを選択して、ロールに書き込みアクセス権があることを確認し、ステップアップ認証の要求があれば完了してください。APIリクエストで401が返される
完全かつ有効なキーがBearerトークンまたはX-Api-Keyとして指定されていることを確認し、有効期限切れ、一時停止、失効のいずれにも該当しないことを確認してください。