エンドユーザー ID、アプリ ID、またはこの両方による OAuth 2.0 アクセス トークンの取得と取り消しを有効にする

このセクションでは、エンドユーザー ID、アプリ ID、またはこの両方を基準に OAuth 2.0 アクセス トークンを取得、無効化できるようにする方法を説明します。エンドユーザー ID 機能を使用するには、このトピックで説明する特殊なセットアップが必要です。ここでのエンドユーザーとは、API を呼び出すアプリのユーザーを意味します。

エンドユーザー ID アクセスを有効にすべき場合

アクセス トークンにユーザー ID を格納すると便利な場合もあります。ただし、エンドユーザー ID アクセス機能は、ユースケースでこの機能を使用する正当な理由がある場合に限って有効にしてください。次に例を示します。

  • ユーザーがウェブサイトまたはアプリで認可済みのサードパーティ アプリを確認して、そのアプリに対するアクセス権を無効にできるようにする場合。
  • 認可済みユーザーが特定のデベロッパー アプリに関連付けられたアクセス トークンのすべてを無効にできるようにする場合。

OAuth アクセス トークンの概要

OAuth アクセス トークンには、アプリ ID が自動的に追加されます。したがって、以下に説明するように組織に対してトークンへのアクセスを有効にした後は、アプリ ID を基準にアクセス トークンを無効化できます。

OAuth 2.0 アクセス トークンをエンドユーザー ID を基準に取得して無効化するには、アクセス トークン内にエンドユーザー ID がなければなりません。以下の手順で、エンドユーザー ID を既存のトークンに追加する方法を説明します。

デフォルトでは、Edge は次に示す形式で OAuth 2.0 アクセス トークンを生成します。

    {
     "issued_at" : "1421847736581",
     "application_name" : "a68d01f8-b15c-4be3-b800-ceae8c456f5a",
     "scope" : "READ",
     "status" : "approved",
     "api_product_list" : "[PremiumWeatherAPI]",
     "expires_in" : "3599", //--in seconds
     "developer.email" : "tesla@weathersample.com",
     "organization_id" : "0",
     "token_type" : "BearerToken",
     "client_id" : "k3nJyFJIA3p62DWOkLO6OJNi87GYXFmP",
     "access_token" : "7S22UqXGJDTuUADGzJzjXzXSaGJL",
     "organization_name" : "myorg",
     "refresh_token_expires_in" : "0", //--in seconds
     "refresh_count" : "0"
    }
    

次の点にご注意ください。

  • application_name フィールドには、そのトークンに関連付けられているアプリの UUID が格納されます。アプリ ID による OAuth 2.0 アクセス トークンの取得と無効化を有効にする場合は、このアプリ ID を使用します。
  • access_token フィールドには、OAuth 2.0 アクセス トークンの値が格納されます。

デフォルトの OAuth アクセス トークンには、エンドユーザー ID を格納するフィールドがありません。エンドユーザー ID を基準に OAuth 2.0 アクセス トークンを取得、無効化できるようにするには、以下の手順で説明するように、OAuth 2.0 ポリシーを構成してトークンにユーザー ID を組み込む必要があります。アプリ ID のみを基準に OAuth 2.0 アクセス トークンを取得して無効化する場合は、エンドユーザー ID によるアクセスを有効にする必要はありません。

トークン作成エンドポイントにエンドユーザー ID を渡します。エンドユーザー ID をクエリ パラメータまたはフォーム パラメータとして渡すことも、(このトピックの後のほうで説明するように)ヘッダー内に含めて渡すこともできます。Edge を構成してトークンにエンドユーザー ID を組み込んだ後は、次に示すように、エンドユーザー ID が app_enduser フィールドとしてトークンに組み込まれます。

    {
     "issued_at" : "1421847736581",
     "application_name" : "a68d01f8-b15c-4be3-b800-ceae8c456f5a",
     "scope" : "READ",
     "app_enduser" : "6ZG094fgnjNf02EK",
     "status" : "approved",
     "api_product_list" : "[PremiumWeatherAPI]",
     "expires_in" : "3599", //--in seconds
     "developer.email" : "tesla@weathersample.com",
     "organization_id" : "0",
     "token_type" : "BearerToken",
     "client_id" : "k3nJyFJIA3p62DWOkLO6OJNi87GYXFmP",
     "access_token" : "7S22UqXGJDTuUADGzJzjXzXSaGJL",
     "organization_name" : "myorg",
     "refresh_token_expires_in" : "0", //--in seconds
     "refresh_count" : "0"
    }
    

API 呼び出しによって取得と無効化を行う方法については、次の Smart Docs をご覧ください。

ユーザー ID とアプリ ID で OAuth 2.0 トークンへのアクセスを有効にする

ユーザー ID とアプリ ID を基準に OAuth 2.0 トークンにアクセスできるようにする方法は、Edge がどのようにデプロイされているかによって異なります。

  • クラウドベースのデプロイ

    クラウドベースの Edge デプロイは、構成のほとんどを Apigee が処理することを意味します。お客様の担当となるのは、ユーザー ID をアクセス トークンに追加するために OAuth 2.0 ポリシーを構成することだけです。詳しくは、以下の手順をご覧ください。
  • Edge for Private Cloud デプロイ

    Apigee Edge for Private Cloud(オンプレミス)では、お客様がすべての構成を担当します。詳しくは、運用と構成をご覧ください。

クラウド内でのアクセスを有効にする

ステップ 1: この機能をサポートする組織を有効にする

この機能をサポート対象とする組織のそれぞれに対して、この機能を有効にする必要があります。

Apigee サポートに連絡して、組織を更新するよう依頼してください。

ステップ 2: oauth2 リソース権限を opsadmin と orgadmin の役割に付与する

エンドユーザー ID またはアプリ ID を基準に oauth2 リソースに対するアクセス トークンの取得(get)と無効化(put)の呼び出しを行う権限は、orgadminopsadmin の役割にのみ付与してください。

Get Permission for a Resource API 呼び出しを使用すると、oauth2 リソースに対する get 権限と put 権限が付与されている役割を確認できます。

権限を追加または削除する必要がある場合は、Apigee サポートに連絡して権限の更新を依頼してください。

ステップ 3: 既存の OAuth 2.0 アクセス トークンを Cassandra ノードにコピーする

Apigee サポートが行う内容: このタスクでは、影響を受ける組織内の既存の OAuth 2.0 アクセス トークンを Cassandra ノードにコピーして保管します。この手順は、Apigee Edge ポッドごとの Cassandra ノード上で行われます。これにより、(既存の、または新しく生成される)OAuth 2.0 アクセス トークンのすべてに対して、取得と取り消しの API 呼び出しを実行できるようになります。

ステップ 4: oauth_max_search_limit プロパティを Management Server と Message Processor に追加する

このタスクでは、Management Server と Message Processor の keymanagement.properties ファイルを更新し、プロパティ oauth_max_search_limit = 100 を含めます。このプロパティの値として推奨されるのは 100 ですが、必要に応じて任意の値を設定できます。

Apigee サポートに連絡して、この追加を行うよう依頼してください。

ステップ 5: エンドユーザー ID を組み込んだアクセス トークンを生成するように OAuth 2.0 ポリシーを構成する

このタスクでは、エンドユーザー ID を組み込んだアクセス トークンを生成するように OAuth 2.0 ポリシーを構成します。エンドユーザー ID をアクセス トークンに組み込むと、エンドユーザー ID を基準にアクセス トークンを取得、無効化できます。

エンドユーザー ID をアクセス トークンに組み込むようにポリシーを構成するには、エンドユーザー ID を格納する入力変数を指定する必要があります。この変数を指定するには、<AppEndUser> タグを使用します。

次の GenerateAccessTokenClient という名前の OAuth 2.0 ポリシーにより、OAuth 2.0 アクセス トークンが生成されます。タグ太字で示されているのが、追加された <AppEndUser> タグです。

    <OAuthV2 async="false" continueOnError="false" enabled="true" name="GenerateAccessTokenClient">
      <DisplayName>OAuth 2.0.0 1</DisplayName>
      <ExternalAuthorization>false</ExternalAuthorization>
      <Operation>GenerateAccessToken</Operation>
      <SupportedGrantTypes>
        <GrantType>client_credentials</GrantType>
      </SupportedGrantTypes>
      <GenerateResponse enabled="true"/>
      <GrantType>request.queryparam.grant_type</GrantType>
      <AppEndUser>request.header.appuserID</AppEndUser>
      <ExpiresIn>960000</ExpiresIn>
    </OAuthV2>
    

上記のポリシーにより、次の cURL コマンドを使用してアクセス トークンを appuserID ヘッダーとして渡すことで、OAuth 2.0 アクセス トークンを生成できます。

    curl -H "appuserID:6ZG094fgnjNf02EK" /
      https://myorg-test.apigee.net/oauth/client_credential/accesstoken?grant_type=client_credentials /
      -X POST /
      -d 'client_id=k3nJyFJIA3p62TKIkLO6OJNi87GYXFmP&client_secret=gk58jK5lIp943AY4'
    

この例では、appuserID がリクエスト ヘッダーとして渡されています。リクエストの一部として情報を渡すには、さまざまな方法があります。たとえば、次の方法を代わりに使用することもできます。

  • フォーム パラメータ変数 request.formparam.appuserID を使用する
  • エンドユーザー ID を提供するフロー変数を使用する