Oracle Cloud Infrastructureドキュメント

My Services APIでのアクセス・トークン認可の使用

重要

My ServicesダッシュボードおよびAPIは非推奨です。

このトピックでは、Oracle Cloud My Services APIでのアクセス・トークン認可の設定および使用方法について説明します。アクセス・トークン認可によって、開発者はプログラムのエンドポイント(API)にアクセスして、クラウド・アカウントの情報(資格、インスタンス、測定データなど)を取得できます。

アクセス・トークンについて

アクセス・トークンには、開発者がクラウド・アカウントの情報にアクセスするのに必要な情報が含まれています。開発者は、APIコールの実行時にトークンを表示します。使用可能なアクションおよびエンドポイントは、トークンの生成時に選択するスコープ(権限)によって異なります。アクセス・トークンは約1時間有効です。

リフレッシュ・トークンを使用すると、開発者は管理者に連絡することなく新しいアクセス・トークンを生成できます。リフレッシュ・トークンは約1年間有効です。

プロセスの概要

管理者の設定ステップ:

  1. 開発者に付与する特定の権限を持つIdentity Cloud Serviceクライアント・アプリケーションを作成します。
  2. 目的の開発者用に必要な権限を含むアクセス・トークンを生成します。
  3. アクセス・トークンと必要な情報を開発者に提供します。
  4. アクセス・トークンを検証するようにIdentity Cloud Serviceを構成します。

開発者がトークンを使用するステップ:

  1. My Services APIエンドポイントに対するリクエストを発行します。認可パラメータのアクセス・トークンを含めます。
  2. アクセス・トークンが期限切れになった場合、権限が終了するまでは、管理者を介さずにアクセス・トークンをリフレッシュします。

トークン検証を設定するための管理者タスク

開発者がアクセス・トークンを使用してアクセスできるようにするには、次のタスクを実行します。

IDCSクライアント・アプリケーションの作成
  1. 管理者としてIdentity Cloud Servicesにサインインし、管理コンソールに移動します。サインインにサポートが必要な場合は、「Oracle Identity Cloud Serviceへのアクセス方法」を参照してください。
  2. 「アプリケーション」タイルをクリックします。アプリケーションのリストが表示されます。
  3. 「+」(追加)をクリックし、新規アプリケーションを作成します。
  4. アプリケーションのタイプとして「機密アプリケーション」をクリックします。
  5. 「App Details」セクションで、「Name」および「Description」を入力します。機密情報を入力しないでください。
  6. 「次」をクリックします。

  7. 「クライアント」セクション:

    1. 「このアプリケーションをクライアントとして今すぐ構成します」を選択します。
    2. 「認可」の「許可される権限付与タイプ」で、次のオプションを選択します:
      • JWTアサーション
      • リフレッシュ・トークン

  8. 「トークン発行ポリシー」の「リソース」で、「スコープの追加」をクリックします。

  9. 「スコープの選択」ダイアログで、「CloudPortalResourceApp」を選択し、矢印をクリックしてリソースのスコープを選択します。

  10. アクセス・トークンを提供する開発者に付与する各認可の横にあるボックスを選択します。(権限は別のステップで割り当てます。)

  11. 「追加」をクリックし、ダイアログを閉じます。選択内容が表示されます。

  12. 「次」をクリックします。

  13. 「リソース」セクションで、デフォルトをそのまま使用して「次」をクリックします。
  14. 「Web層ポリシー」セクションで、デフォルトをそのまま使用して「次」をクリックします。

  15. 「認可」セクションで、「終了」をクリックします。

    「アプリケーションが追加されました」という通知に、アプリケーションの新しいクライアントIDおよびクライアント・シークレットが表示されます。

    重要

    クライアントIDとクライアント・シークレットをコピーして安全な場所に格納し、「閉じる」をクリックします。クライアントIDとクライアント・シークレットは、先ほど作成したアプリケーションに固有の資格証明です。これらの資格証明は後で必要になります。
  16. 作成プロセスを完了するには、ページの上部にある「アクティブ化」をクリックします。
アクセス・トークンの生成

  1. 前のタスクで作成したIDCSアプリケーションに移動し、「詳細」タブを選択します。

  2. 「アクセス・トークンの生成」をクリックします。

  3. 「トークンの生成」ダイアログで、「カスタマイズされたスコープ」を選択し、「その他のAPIの呼出し」を選択します。

  4. このアクセス・トークンを受け取る開発者に付与するスコープを選択します。

    ノート

    最低限必要な権限のみを付与することをお薦めします。

  5. 「リフレッシュ・トークンを含める」を選択します。

  6. 「トークンのダウンロード」をクリックします。ブラウザにより、トークン・ファイル(.tok)のダウンロードが要求されます。トークン・ファイルには、アクセス・トークンとリフレッシュ・トークンが含まれています。

  7. このファイルを開発者に渡します。
開発者へのアクセス情報の送信

APIエンドポイントを呼び出すには、開発者は次が必要です:

  • 生成したトークン・ファイル。

  • トークン・ファイルの生成に使用したIDCSアプリケーションのクライアントIDおよびクライアント・シークレット。開発者がリフレッシュ・トークンから新しいアクセス・トークンを生成するには、クライアントIDとクライアント・シークレットが必要です。

  • APIのエンドポイント。

    • itas:myservicesスコープに関連するエンド・ポイント: https://itra.oraclecloud.com/itas/<tenant-IDCS-ID>/myservices/api/v1
    • itas:meteringスコープに関連するエンド・ポイント: https://itra.oraclecloud.com/metering/api/v1

前述の情報を必ず安全な方法で送信してください。この情報が危険にさらされたと思われる場合は、「開発者がアクセス・トークンをリフレッシュする機能の取消し」を参照してください。

アクセス・トークンを検証するためのIdentity Cloud Serviceの構成

Oracle Identity Cloud Serviceにログインせずに、クライアントがテナント署名証明書にアクセスするには:

  1. Oracle Identity Cloud Services管理コンソールにサインインします。サインインにサポートが必要な場合は、「Oracle Identity Cloud Serviceへのアクセス方法」を参照してください。
  2. ナビゲーション・メニューを開きます。「設定」で、「デフォルト設定」を選択します。
  3. 「署名証明書へのアクセス」トグル・ボタンをオンに設定します。

アクセス・トークンの使用

トークン・ファイルの拡張子は.tokです。ファイルには、アクセス・トークンとリフレッシュ・トークンが含まれています。コンテンツは次のようになります:

{"app_access_token":"eyJ4N...aabb...CpNwA","refresh_token":"AQID...9NCA="}

My Services APIでトークンを使用するには:

  1. トークン・ファイルを開きます。

  2. 有効なエンドポイントにリクエストを発行し、Authorizationパラメータにアクセス・トークンを挿入します。

    例:

    curl -X GET  https://itra.oraclecloud.com/itas/<tenant-IDCS-ID>/myservices/api/v1/serviceEntitlements   -H 'Authorization: Bearer eyJ4N...aabb...CpNwA'

リフレッシュ・トークンからの新しいアクセス・トークンのリクエスト

アクセス・トークンは約1時間有効です。トークンが無効になると、401レスポンス・コードと期限切れという内容のエラー・メッセージ(errorMessage)が表示されます。

リフレッシュ・トークンから、期間の短い新しいアクセス・トークンを生成できます。新しいトークンを生成するには、クライアントIDおよびクライアント・シークレットが必要です。生成できるのは、元のトークンと同じかそれを下回るアクセス権限(スコープ)のトークンのみです。

curlコマンドを使用した例:

curl -i -H 'Authorization: Basic <base64Encoded clientid:secret>' -H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8' --request POST https://<tenant-IDCS-ID>/oauth2/v1/token -d 'grant_type=refresh_token&refresh_token=<refresh-token>'

前の項のサンプル・トークン・ファイルを使用すると、<refresh-token>の値はAQID...9NCA=になります。

サンプルのレスポンス:

{ "access_token": "eyJraWQiO....2nqA", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "AQIDBAUn…VkxNCB7djF9NCA=" }
ノート

開発者が新しいアクセス・トークンとリフレッシュ・トークンを生成すると、前のリフレッシュ・トークンが無効になります。

開発者がアクセス・トークンをリフレッシュする機能の取消し

開発者がアクセス・トークンをリフレッシュする機能を取り消す必要がある場合は、トークンに新しいクライアント・シークレットを生成して既存のリフレッシュ・トークンを無効にするか、アプリケーションを非アクティブ化してアクセスを一時的に取り消します。

重要

いずれかのアクションを実行すると、現在のクライアント・シークレットまたはアプリケーションを使用しているすべての開発者の機能が終了または中断されます。複数の開発者のトークンを生成する場合は、複数のIDCSアプリケーションを作成して、開発者を相互に分離することを検討してください。

開発者がアクセス・トークンをリフレッシュする機能を終了するには

  1. 管理者としてIdentity Cloud Servicesにサインインし、管理コンソールに移動します。サインインにサポートが必要な場合は、「Oracle Identity Cloud Serviceへのアクセス方法」を参照してください。
  2. 「アプリケーション」タイルをクリックします。アプリケーションのリストが表示されます。
  3. トークンの生成に使用したアプリケーションをクリックして、詳細を表示します。
  4. 「構成」をクリックします。
  5. 「一般情報」で、「クライアント・シークレット」の横にある「再生成」をクリックし、新しいクライアント・シークレットを生成します。

開発者がリフレッシュ・トークンからアクセス・トークンを生成する機能をリストアするには、新しいアクセス・トークンを生成します。次に、新しいクライアント・シークレットとともに開発者にトークンを渡します。

開発者がアクセス・トークンをリフレッシュする機能を一時的に終了するには

  1. 管理者としてIdentity Cloud Servicesにサインインし、管理コンソールに移動します。サインインにサポートが必要な場合は、「Oracle Identity Cloud Serviceへのアクセス方法」を参照してください。
  2. 「アプリケーション」タイルをクリックします。アプリケーションのリストが表示されます。
  3. トークンの生成に使用したアプリケーションをクリックして、詳細を表示します。
  4. ページの右上隅で、「非アクティブ化」をクリックします。
  5. 要求されたら、「アプリケーションの非アクティブ化」をクリックします。

開発者が同じトークンを使用するように再度有効にするには、「アクティブ化」をクリックします。