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

Edge for Private Cloud v4.18.05

このドキュメントでは、エンドユーザー ID、アプリ ID、またはこの両方を使用して OAuth 2.0 アクセス トークンの取得と取り消しを可能にする方法を説明します。

OAuth アクセス トークンには、アプリ ID が自動的に追加されます。したがって、以下の手順を使用して組織のトークン アクセスを有効にした後は、アプリ ID を使用してトークンにアクセスできます。

エンドユーザー ID を使用して OAuth 2.0 アクセス トークンの取得と取り消しを行うには、エンドユーザー 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",
      "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",
      "refresh_count" : "0"
    }
    

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

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

エンドユーザー ID による OAuth 2.0 アクセス トークンの取得と取り消しを有効にするには、以下の手順の説明に沿ってユーザー ID をトークンに含めるように OAuth 2.0 ポリシーを構成します。

エンドユーザー ID は、デベロッパーのメールアドレスではなく、Edge がデベロッパー ID として使用する文字列です。デベロッパーの ID は、Get Developer API 呼び出しを使用してデベロッパーのメールアドレスから決定します。

エンドユーザー ID がトークンに含まれるように Edge を構成すると、次のように 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",
      "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",
      "refresh_count" : "0"
    }
    

ユーザー ID とアプリ ID によって OAuth 2.0 アクセス トークンの取得と取り消しを行う API

ユーザー ID、アプリ ID またはその両方を使用して OAuth トークンにアクセスするには、次の API を使用します。

トークン アクセスを有効化する手順

エンドユーザー ID とアプリ ID による OAuth 2.0 アクセス トークンの取得と取り消しを有効にするには、以下の手順を使用します。

ステップ 1: 組織のトークン アクセス サポートを有効にする

トークン アクセスは組織ごとに個別に有効にする必要があります。エンドユーザー ID やアプリ ID による OAuth 2.0 アクセス トークンの取得と取り消しを有効にする組織ごとに、以下の PUT API を呼び出します。

次の呼び出しを行うユーザーには、組織の役割 orgadmin または opsadmin が必要です。values は組織固有の値に置き換えます。

curl -H "Content-type:text/xml" -X POST \
      https://management_server_IP;:8080/v1/organizations/org_name \
      -d '<Organization name="org_name">
          <Properties>
            <Property name="features.isOAuthRevokeEnabled">true</Property>
            <Property name="features.isOAuth2TokenSearchEnabled">true</Property>
          </Properties>
        </Organization>' \
      -u USER_EMAIL:PASSWORD

ステップ 2: 組織の opsadmin の役割に権限を設定する

ユーザー ID またはアプリ ID に基づいて OAuth 2.0 トークンの取得(HTTP GET)と取り消し(HTTP PUT)を行う権限は、組織内の orgadminopsadmin の役割のみに付与してください。アクセスを制御するには、組織の /oauth2 リソースに対する get と put の権限を設定します。このリソースの URL の形式は次のとおりです。

https://management_server_IP:8080/v1/organizations/org_name/oauth2

orgadmin の役割には必要な権限があらかじめ付与されている必要があります。/oauth2 リソースに対する opsadmin 役割の権限は、次のようになります。

<ResourcePermission path="/oauth2">
      <Permissions>
        <Permission>get</Permission>
        <Permission>put</Permission>
      </Permissions>
    </ResourcePermission>

単一リソースに対する権限を取得する API 呼び出しを使用すると、/oauth2 リソースに対する権限が付与された役割を確認できます。

レスポンスに基づいて、役割にリソースに対する権限を追加する API 呼び出しとリソースに対する権限を削除する API 呼び出しを使用して、/oauth2 リソースの権限に必要な調整を加えることができます。

/oauth2 リソースに対する getput の権限を opsadmin の役割に付与するには、次の curl コマンドを使用します。values は組織固有の値に置き換えます。

curl -X POST -H 'Content-type:application/xml' \
      http://management_server_IP:8080/v1/organizations/org_name/userroles/opsadmin/permissions \
      -d '<ResourcePermission path="/oauth2">
          <Permissions>
            <Permission>get</Permission>
            <Permission>put</Permission>
          </Permissions>
        </ResourcePermission>' \
      -u USEREMAIL:PASSWORD
    

orgadminopsadmin 以外の役割から、/oauth2 リソースに対する getput の権限を取り消すには、次の curl コマンドを使用します。values は組織固有の値に置き換えます。

curl -X DELETE -H 'Content-type:application/xml' \
      http://management_server_IP:8080/v1/organizations/org_name/userroles/roles/permissions \
      -d '<ResourcePermission path="/oauth2">
          <Permissions></Permissions>
        </ResourcePermission>' \
       -u USEREMAIL:PASSWORD
    

ステップ 3: oauth_max_search_limit プロパティを設定する

/opt/apigee/customer/application/management-server.properties ファイルの conf_keymanagement_oauth_max_search_limit プロパティが 100 に設定されていることを確認します。

conf_keymanagement_oauth_max_search_limit = 100

このファイルが存在しない場合は作成します。

このプロパティは、トークンをフェッチするときに使用されるページサイズを設定します。Apigee では値に 100 をおすすめしていますが、適切と思われる値に設定できます。

新規インストールでは、このプロパティがあらかじめ 100 に設定されています。このプロパティの値を変更する必要がある場合は、以下のコマンドを使用して Management Server と Message Processor を再起動します。

/opt/apigee/apigee-service/bin/apigee-service edge-management-server restart
    /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

ステップ 4: エンドユーザー ID を含めるトークンを生成するように OAuth 2.0 ポリシーを構成する

トークンにエンドユーザー ID が含まれるように、アクセス トークンの生成に使用される OAuth 2.0 ポリシーを構成します。アクセス トークンにエンドユーザー ID を含めることで、ID によるトークンの取得と取り消しが可能になります。

アクセス トークンにエンドユーザー ID が含まれるようにポリシーを構成するには、アクセス トークンを作成するリクエストにエンドユーザー ID を含め、そのエンドユーザー ID が格納される入力変数を指定する必要があります。

次の GenerateAccessTokenClient という名前の OAuth 2.0 ポリシーは、OAuth 2.0 アクセス トークンを生成します。エンドユーザー ID を格納する変数を指定する <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=k3nJyFJIA3p62TKIkLO6OJNXFmP&client_secret=gk5K5lIp943AY4'

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

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