アプリケーション API アクセスの管理

開発者が 1 つ以上の Verify 機能を使用するアプリケーションを構築する場合、アプリケーションには適切な Verify API を呼び出す資格がなければなりません。 社内アプリケーションを アプリケーション API クライアント として API アクセス に登録して、固有のクライアント ID と秘密鍵を割り当てます。

始める前に

  • このタスクを完了するには管理者権限が必要です。
  • 管理者として IBM® Security Verify 管理コンソールにログインします。
注意：適切な権限を持つユーザーだけがクライアント・シークレットを見ることができます。 詳細については、エンタイトルメントのセキュリティ・アップデートを参照のこと。

このタスクについて

アプリケーションへの API アクセス権限は、アプリケーションの作成時に付与することも、後で編集オプションを使用して付与することもできます。 アプリケーション用に API クライアントを作成できます。各 API クライアントは、異なる API アクセス資格のセットを所有できます。

また、IP フィルターを実装することで、トークンの発行および使用を特定の IP アドレス範囲に制限したり、特定の IP アドレス範囲を除外したりすることもできます。

OIDC アプリケーションの場合、SSO クライアントの API アクセス資格も構成できます。 これらのトークンは、アプリケーションにログインするユーザーが Verifyで実行する資格を持つアクションを実行するように制限されます。

手順

  1. 「API アクセス」を選択します。
  2. アプリケーション API クライアントを作成します。
    1. 「API クライアントの追加」を選択します。
    2. API クライアントについて、以下の情報を指定します。
      表 1. アプリケーション API クライアント
      情報 説明
      名前 API クライアントの名前を指定します。
      注: 使用できるのは、英数字と以下の特殊文字のみです。
      • -
      • .
      • _
      有効

      API クライアントが有効か無効かを示します。

      有効対応の API クライアントは、アクセス権限のある API を呼び出すことができます。

      無効無効なAPIクライアントは、アクセス権のあるAPIを含め、いかなるAPIも呼び出すことができない。
      注:
      • この設定が有効になるまでに最大で 1 分かかる場合があります。
      • API クライアントに既存の有効なアクセス・トークンがある場合、引き続き API を呼び出すことができます。 アクセス・トークンには、制限された有効期間があります。 トークンは 2 時間で期限が切れます。 アクセス・トークンの期限が切れると、API クライアントは API を呼び出せなくなります。
      クライアント ID

      API クライアントの固有 ID。

      この情報は、API クライアントの保存後に自動的に生成され、「API クライアント」リストに表示されます。
      クライアント秘密鍵

      API クライアントの ID を確認するために、クライアント ID と共に使用されます。

      この秘密鍵は、アプリケーションおよび許可サーバーのみが知っている必要があります。

      この情報は、API クライアントの保存後に自動的に生成されます。 API クライアントの詳細を表示します。
      クライアント認証方式 API クライアントのクライアント認証方式を示します。
      Verify は、以下のクライアント認証方式をサポートしています。
      • Default(デフォルトの選択)
      • Client secret basic
      • Client secret POST
      • Private key JWT
      • 相互 TLS
        注: カスタム・アプリケーションでは相互 TLS は使用できません。
      TLS クライアント認証属性 このオプションは、相互 TLS クライアント認証方式が選択されている場合にのみ表示されます。
      認証用認証属性。
      • サブジェクト DN
      • SAN DNS
      • SAN URI
      • SAN IP
      • SAN E メール・アドレス
      TLS クライアント認証属性値 このオプションは、相互 TLS クライアント認証方式が選択されている場合にのみ表示されます。

      認証用認証属性値。
      証明書にバインドされたアクセス・トークン
      注: 証明書バインド・アクセス・トークン は、カスタム・アプリケーションでは使用できません。
      		 生成トークンが認証にバインドされるかどうかを示します。 認証結合アクセストークンについては、Open ID Connect相互TLSクライアント認証と認証結合アクセストークンを参照してください。
      クライアント・アサーション JTI の検証 (Validate client assertion JTI) クライアント・アサーション JWT 内の JTI が単一使用に対して検証されるかどうかを示します。 このオプションは、クライアント秘密鍵 JWT クライアント認証方式または秘密鍵 JWT クライアント認証方式が選択されている場合にのみ表示されます。
      許可された署名検証鍵 (Allowed signature verification keys) クライアント・アサーション JWT の検証に使用できる署名検証鍵 ID。 このオプションは、秘密鍵 JWT クライアント認証方式が選択されている場合にのみ表示されます。
      注: 署名検査鍵は手動で指定できます。 複数の署名検査鍵を指定できます。
      JWKS URI 依拠当事者が公開鍵を JSON Web Key (JWK) 形式で公開する URI。 この URI は、JWT 署名の検証に使用されます。 システムは、到達不能または応答しない JWKS URI を拒否できます。 JWKSサイズが大きすぎる場合、システムはJWKS URIを拒否できます。 依拠当事者が JWKS URI を公開しない場合は、X509 証明書の形式で公開鍵をシステムに追加できます。 証明書の管理を参照してください。 パブリック証明書に関連付けられる「フレンドリー名」は、JWT の鍵 ID (kid) ヘッダーの値です。
  3. アクセス・トークンおよびリフレッシュ・トークンが盗まれた場合の無許可アクセスの時間を制限するために、これらのトークンの有効期限を構成します。

    アクセス・トークンは、保護リソースへのアクセスを許可するために使用されます。 アクセス・トークンの有効期限が切れると、許可は取り消されます。

    表 2. トークン設定
    フィールド 説明
    アクセス・トークン存続時間 (秒)

    アクセス・トークンの有効期限が切れるまでの時間の長さを秒単位で設定します。

    アクセス・トークンの有効期限を設定して、クライアント・アプリケーション で情報漏えいがあったときに、攻撃者が盗まれたトークンを使用してリソースにアクセスできる時間を制限します。

    指定できるのは正の整数のみです。

    デフォルト値は 7200 秒です。 許可される最小値は 1 秒で、最大値は 2147483647 秒です。
    アクセス・トークンの形式 アクセス・トークンが不透明なストリングとして生成されるかどうかを示します。DefaultJWT 形式で設定することができます。
  4. API クライアント ID とシークレットが安全に配布されるように IP フィルターを実装する場合は、以下の情報を指定します。
    表 3. IP フィルター設定
    フィールド 説明
    IP フィルターの有効化 (Enable IP filtering)

    IP フィルターが有効か無効かを示します。
    許可リスト。 拒否リスト

    フィルターのタイプ (リストが許可リストであるか拒否リストであるか) を示します。

    「IP フィルターの有効化 (Enable IP filtering)」が有効にされている場合は必須です。
    IP フィルター

    IP フィルターのリスト。

    「IP フィルターの有効化 (Enable IP filtering)」が有効にされている場合は必須です。

    IP フィルターは、単一の IP アドレス、 IP 範囲、または IP サブネット・マスクのいずれかの形式です。 IPv4 と IPv6 の両方がサポートされています。 例: 192.0.2.55, 192.0.2.55-192.0.2.61, 192.0.2.55/24, 2001:db8::1, 2001:db8::1-2001:db8::ff, 2001:db8:1234::/48。
  5. ID トークンおよび JWT 形式のアクセス・トークンの署名属性を指定します。 依拠当事者 は、署名を使用して、トークンに含まれているユーザー要求と、トークンに署名した OpenID Connect ID プロバイダー の整合性および認証性を検証します。
    注:

    署名オプションは、カスタム・アプリケーションでのみ使用可能です。

    表 4. 署名オプション
    フィールド 説明
    署名アルゴリズム

    Verify が ID トークン および JWT 形式のアクセス・トークンに署名するために使用するアルゴリズム。 このアルゴリズムは、依拠当事者が Verifyに登録したものと一致する必要があります。

    以下のハッシュ・アルゴリズムから選択して、署名を検証します。
    • HS256
    • HS384
    • HS512
    • RS256 (デフォルト値)
    • RS384
    • RS512
    注: クライアント・シークレットを生成しないことを選択した場合、HS アルゴリズムは表示されません。
    署名証明書

    このオプションは、いずれかの RS 署名アルゴリズムを選択した場合にのみ表示されます。

    この証明書は、シングル・サインオン時に ID トークンおよび JWT 形式のアクセス・トークンに署名するために使用します。

    デフォルトの選択は、「設定 」＞「 証明書 」＞「 個人証明書」で構成したデフォルトの個人証明書を指す。
  6. 「カスタム・スコープの制限」 チェック・ボックスを選択します。
    「カスタム・スコープの制限」を選択すると、フローの終わりにクライアントに付与されるスコープは、このセクションで指定されるスコープに制限されます。 付与するカスタム・スコープの名前と説明を入力します。 スコープ名は、依拠当事者/クライアントによって要求される OAuth2/OIDC スコープを指します。 説明は、スコープの分かりやすい説明です。 追加のスコープを付与する場合に選択します。
  7. アクセス権を付与する API を選択します。 詳しくは「アクセス権」を参照。
    「すべて選択」が「オフ」に設定されている場合は、クライアントにアクセス権を付与する API を選択します。 「すべて選択 (Select All)」が「オン」に設定されている場合、クライアントにはすべての API へのアクセス権が付与されます。 ただし、クライアントにアクセス権を付与しない API のチェック・ボックスをクリアできます。
    注:
    • API を呼び出す許可を最初は持たない API クライアントを作成できます。 後から編集して、固有の API アクセス権を付与できます。
    • サブスクリプション・プランに関連する API のみを選択できます。
    • OIDC アプリケーションの場合、アプリケーション名と同じクライアント名を持つデフォルト・クライアントが、そのアプリケーションの API クライアントのリストにあります。 アプリケーションが削除されない限り、または別のサインオン方式に切り替えない限り、これを削除することはできません。
  8. 「保存」を選択します。
    「クライアント ID」および「クライアント秘密鍵」が生成され、アプリケーション API クライアントが作成されます。
  9. API クライアントの詳細を表示します。
    • 検索フィールドをスクロールまたは使用して、API クライアントを見つけます。 検索項目と一致するすべてのクライアントが表示されます。
    • 情報を表示する API クライアントを選択します。 「API クライアントの詳細」 が表示されます。
    • APIクライアントにカーソルを合わせ、「編集アイコンが表示されたら選択する。 「API クライアントの編集」ダイアログ・ボックスが表示されます。
      以下のオプションを使用します。
      • クリップボードにコピー選択すると、クライアントIDまたはシークレットがクリップボードにコピーされます。
      • クライアント秘密鍵を表示するには、表示を選択します。
      • クライアント秘密鍵を非表示にするには、非表示を選択します。
  10. API クライアントを編集します。
    1. スクロールして、API クライアントを見つけます。
    2. APIクライアントにカーソルを合わせ、「編集アイコンが表示されたら選択する。
      「API クライアントの編集」ダイアログ・ボックスが表示されます。
    3. 情報を編集します。
      既存のアプリケーションを編集する場合は、次のクライアント秘密鍵オプションを使用できます。
      • クライアント秘密鍵を表示するには、表示を選択します。
      • クライアント秘密鍵を非表示にするには、非表示を選択します。
      • クライアントIDまたはシークレットをクリップボードにコピーするには、 コピー を選択します。
      • リスト を選択すると、ローテーションされたクライアントの秘密が表示されます。
        • リストから 1 つまたは複数のローテートされたクライアントシークレットを選択し、[ 削除] をクリックして削除します。
      • 新規クライアント・シークレットを生成するには、再生成を選択します。 クライアント秘密鍵が漏えいしたと思われる場合は、このオプションを使用します。 クライアント秘密鍵を再生成した場合は、アプリケーションのすべての OAuth クライアントにあるクライアント秘密鍵を更新する必要があります。
        • 現在の秘密を保持する ] のチェックボックスを選択すると、現在のクライアント秘密がローテートされたクライアント秘密のリストに追加されます。
        • 現在のシークレットを保持する ]チェックボックスが選択されている場合、クライアントシークレットの説明と有効期限（ブラウザのローカル時間）を選択します。 有効期限が選択されていない場合、 アプリケーション設定で設定されたテナントの「ローテーションされた秘密の有効期限」が適用されます。
        • ローテーションされたクライアント秘密はハッシュ化され、プレーンテキストでは取得できなくなりますが、選択された有効期限まで使用することができます。
        • 確認後、クライアント秘密は直ちにローテートされる。 新しいクライアントシークレットが画面に表示されます。
    4. 「保存」を選択します。
  11. API クライアントを削除します。
    1. スクロールして、API クライアントを見つけます。
    2. 以下のいずれかの操作を実行します。
      • API クライアントを選択します。 「詳細」ペインが表示されたら、「削除」を選択します。
      • 複数の API クライアントを削除するには、API クライアントの横にあるチェック・ボックスを選択してから、「削除」を選択します。
    3. 「削除」を選択します。
    4. 選択した API クライアントの削除を確定します。 API クライアントは、アプリケーションが保存されると永久に削除されます。