アクセス トークンと認可コードのリクエスト

このトピックでは、アクセス トークンと認可コードをリクエストする方法、OAuth 2.0 エンドポイントを構成する方法、サポートされる権限付与タイプごとにポリシーを構成する方法について説明します。

サンプルコード

なお、このトピックで説明するポリシーとエンドポイントは、GitHub の Apigee api-platform-samples リポジトリにある oauth-doc-examples プロジェクトで入手できます。サンプルコードをデプロイして、このトピックで説明するのと同じリクエストを試してみることができます。詳細は、プロジェクトの README をご覧ください。

アクセス トークンをリクエストする: 認可コード権限付与タイプ

このセクションでは、認可コード権限付与タイプフローを使用してアクセス トークンをリクエストする方法について説明します。OAuth 2.0 の権限付与タイプについては、OAuth 2.0 の概要をご覧ください。

サンプル リクエスト

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
   -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \
   -X POST 'https://docs-test.apigee.net/oauth/accesstoken' \
   -d 'code=I9dMGHAN&grant_type=authorization_code&redirect_uri=http://example-callback.com'

必須パラメータ

デフォルトでは、これらのパラメータを x-www-form-urlencoded とし、リクエスト本文で指定する必要があります(上記のサンプルを参照)。ただし、この /accesstoken エンドポイントに添付されている OAuthV2 ポリシーで <GrantType> 要素、<Code> 要素、<RedirectUri> 要素を構成することで、このデフォルト値を変更できます。詳細は、OAuthV2 ポリシーをご覧ください。

  • grant_type - authorization_code という値に設定する必要があります。
  • code - /authorize エンドポイントから受信した認可コード(任意の名前を付けることもできます)。認可コード権限付与タイプフローでアクセス トークンをリクエストするには、最初に認可コードを取得する必要があります。下記の認可コードをリクエストするをご覧ください。認可コード権限付与タイプの実装もご覧ください。
  • redirect_uri - このパラメータは、以前の認可コード リクエストに redirect_uri パラメータが含まれていた場合に指定する必要があります。redirect_uri パラメータが認可コード リクエストに含まれていなかった場合にこのパラメータを指定しないと、このポリシーはデベロッパー アプリを登録したときに指定したコールバック URL の値を使用します。

オプション パラメータ

  • state - レスポンスとともに返される文字列。一般に、クロスサイト リクエスト フォージェリ攻撃を防ぐために使用します。
  • scope - 作成されたトークンを使用できる API プロダクトのリストをフィルタリングできます。スコープの詳細については、OAuth2 スコープの操作をご覧ください。

認証

クライアント ID とクライアント シークレットを Basic 認証ヘッダー(Base64 でエンコードされたもの)またはフォーム パラメータ client_idclient_secret として渡す必要があります。これらの値は、登録済みのデベロッパー アプリから取得します。Basic 認証情報をエンコードするもご覧ください。

サンプル エンドポイント

ここでは、アクセス トークンを生成するためのエンドポイント構成のサンプルを示します。これにより実行される GenerateAccessToken ポリシーは、authorization_code 権限付与タイプをサポートするよう構成する必要があります。

...
       <Flow name="generate-access-token">
            <Description>Generate a token</Description>
            <Request>
                <Step>
                    <Name>GenerateAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition>
        </Flow>
...

サンプル ポリシー

これは基本的な GenerateAccessToken ポリシーで、authorization_code 権限付与タイプを受け入れるよう構成されています。このポリシーを使用して構成できる任意の構成要素については、OAuthV2 ポリシーをご覧ください。

<OAuthV2 name="GenerateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>1800000</ExpiresIn>
    <RefreshTokenExpiresIn>86400000</RefreshTokenExpiresIn>
    <SupportedGrantTypes>
      <GrantType>authorization_code</GrantType>
    </SupportedGrantTypes>
    <GenerateResponse enabled="true"/>
</OAuthV2>

戻り値

<GenerateResponse> を有効にすると、ポリシーは、以下のとおりアクセス トークンを含む JSON レスポンスを返します。authorization_code 権限付与タイプでは、アクセス トークンとリフレッシュ トークンが作成されるため、レスポンスは次のようになります。

{
    "issued_at": "1420262924658",
    "scope": "READ",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "refresh_token_issued_at": "1420262924658",
    "status": "approved",
    "refresh_token_status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "tesla@weathersample.com",
    "organization_id": "0",
    "token_type": "BearerToken",
    "refresh_token": "fYACGW7OCPtCNDEnRSnqFlEgogboFPMm",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "2l4IQtZXbn5WBJdL6EF7uenOWRsi",
    "organization_name": "docs",
    "refresh_token_expires_in": "86399", //--in seconds
    "refresh_count": "0"
}

<GenerateResponse> が false に設定されている場合、このポリシーはレスポンスを返しません。代わりに、以下のフロー変数のセットにアクセス トークン付与に関するデータを入力します。

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token
oauthv2accesstoken.{policy-name}.refresh_token_expires_in //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token_issued_at
oauthv2accesstoken.{policy-name}.refresh_token_status

例:

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token
oauthv2accesstoken.GenerateAccessToken.refresh_token_expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token_issued_at
oauthv2accesstoken.GenerateAccessToken.refresh_token_status

アクセス トークンをリクエストする: クライアント認証情報権限付与タイプ

このセクションでは、クライアント認証情報権限付与タイプフローを使用してアクセス トークンをリクエストする方法について説明します。OAuth 2.0 の権限付与タイプについては、OAuth 2.0 の概要をご覧ください。

サンプル リクエスト

次の呼び出しで Basic 認証ヘッダーをエンコードする方法については、Basic 認証情報をエンコードするをご覧ください。

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic c3FIOG9vSGV4VHoAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \
  -X POST 'https://docs-test.apigee.net/oauth/accesstoken' \
  -d 'grant_type=client_credentials'

必須パラメータ

デフォルトでは、必須の grant_type パラメータを x-www-form-urlencoded とし、リクエスト本文で指定する必要があります(上記のサンプルを参照)。ただし、この /accesstoken エンドポイントに添付されている OAuthV2 ポリシーで <GrantType> 要素を構成することで、このデフォルト値を変更できます。たとえば、パラメータをクエリ パラメータで渡すことが可能です。詳細は、OAuthV2 ポリシーをご覧ください。

  • grant_type - client_credentials という値に設定する必要があります。

オプション パラメータ

  • state - レスポンスとともに返される文字列。一般に、クロスサイト リクエスト フォージェリ攻撃を防ぐために使用します。
  • scope - 作成されたトークンを使用できる API プロダクトのリストをフィルタリングできます。スコープの詳細については、OAuth2 スコープの操作をご覧ください。

認証

クライアント ID とクライアント シークレットを Basic 認証ヘッダー(Base64 でエンコードされたもの)またはフォーム パラメータ client_idclient_secret として渡す必要があります。これらの値は、リクエストに関連付けられた登録済みデベロッパー アプリから取得します。Basic 認証情報をエンコードするもご覧ください。

サンプル エンドポイント

ここでは、アクセス トークンを生成するためのエンドポイント構成のサンプルを示します。これにより実行される GenerateAccessToken ポリシーは、client_credentials 権限付与タイプをサポートするよう構成されている必要があります。

...
       <Flow name="generate-access-token">
            <Request>
                <Step>
                    <Name>GenerateAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition>
        </Flow>
...

サンプル ポリシー

これは基本的な GenerateAccessToken ポリシーであり、client_credentials 権限付与タイプを受け入れるよう構成されています。このポリシーを使用して構成できる任意の構成要素については、OAuthV2 ポリシーをご覧ください。

<OAuthV2 name="GenerateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>1800000</ExpiresIn> <!-- 30 minutes -->
    <SupportedGrantTypes>
      <GrantType>client_credentials</GrantType>
    </SupportedGrantTypes>
    <GenerateResponse enabled="true"/>
</OAuthV2>

戻り値

<GenerateResponse> が有効な場合、このポリシーは JSON レスポンスを返します。なお、権限付与タイプが client_credentials の場合、更新トークンはサポートされません。アクセス トークンだけが作成されます。例:

{
    "issued_at": "1420260525643",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "scope": "READ",
    "status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "tesla@weathersample.com",
    "organization_id": "0",
    "token_type": "BearerToken",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "XkhU2DFnMGIVL2hvsRHLM00hRWav",
    "organization_name": "docs"
}

<GenerateResponse> が false に設定されている場合、このポリシーはレスポンスを返しません。代わりに、以下のフロー変数のセットにアクセス トークン付与に関するデータを入力します。

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in //--in seconds

例:

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in     //--in seconds

アクセス トークンをリクエストする: パスワード権限付与タイプ

このセクションでは、リソース所有者パスワード認証情報(password)権限付与タイプフローを使用して、アクセス トークンをリクエストする方法について説明します。OAuth 2.0 の権限付与タイプについては、OAuth 2.0 の概要をご覧ください。

実装方法を説明する 4 分間の動画を含め、パスワード権限付与タイプの詳細については、パスワード権限付与タイプを実装するをご覧ください。

サンプル リクエスト

次の呼び出しで Basic 認証ヘッダーをエンコードする方法については、Basic 認証情報をエンコードするをご覧ください。

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAySVg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \
  -X POST https://docs-test.apigee.net/oauth/token \
  -d 'grant_type=password&username=the-user-name&password=the-users-password'

必須パラメータ

デフォルトでは、これらのパラメータを x-www-form-urlencoded とし、リクエスト本文で指定する必要があります(上記のサンプルを参照)。ただし、この /token エンドポイントに添付されている OAuthV2 ポリシーで <GrantType> 要素、<Username> 要素、<Password> 要素を構成することで、このデフォルト値を変更できます。詳細は、OAuthV2 ポリシーをご覧ください。

ユーザー認証情報は、通常は LDAP または JavaScript ポリシーを使用して格納された認証情報に照らして検証されます。

  • grant_type - 値 password に設定する必要があります。
  • username - リソース所有者のユーザー名。
  • password - リソース所有者のパスワード。

オプション パラメータ

  • state - レスポンスとともに返される文字列。一般に、クロスサイト リクエスト フォージェリ攻撃を防ぐために使用します。
  • scope - 作成されたトークンを使用できる API プロダクトのリストをフィルタリングできます。スコープの詳細については、OAuth2 スコープの操作をご覧ください。

認証

クライアント ID とクライアント シークレットを Basic 認証ヘッダー(Base64 でエンコードされたもの)またはフォーム パラメータ client_idclient_secret として渡す必要があります。これらの値は、リクエストに関連付けられた登録済みデベロッパー アプリから取得します。Basic 認証情報をエンコードするもご覧ください。

サンプル エンドポイント

ここでは、アクセス トークンを生成するためのエンドポイント構成のサンプルを示します。これにより実行される GenerateAccessToken ポリシーは、パスワード権限付与タイプをサポートするよう構成されている必要があります。

...
       <Flow name="generate-access-token">
            <Request>
                <Step>
                    <Name>GenerateAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition>
        </Flow>
...

サンプル ポリシー

これは基本的な GenerateAccessToken ポリシーであり、パスワード権限付与タイプを受け入れるよう構成されています。このポリシーを使用して構成できる任意の構成要素については、OAuthV2 ポリシーをご覧ください。

<OAuthV2 name="GenerateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>1800000</ExpiresIn> <!-- 30 minutes -->
    <RefreshTokenExpiresIn>28800000</RefreshTokenExpiresIn> <!-- 8 hours -->
    <SupportedGrantTypes>
      <GrantType>password</GrantType>
    </SupportedGrantTypes>
    <GenerateResponse enabled="true"/>
</OAuthV2>

戻り値

<GenerateResponse> が有効な場合、このポリシーは JSON レスポンスを返します。パスワード権限付与タイプを使用すると、アクセス トークンとリフレッシュ トークンの両方が作成されます。次に例を示します。

{
    "issued_at": "1420258685042",
    "scope": "READ",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "refresh_token_issued_at": "1420258685042",
    "status": "approved",
    "refresh_token_status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "tesla@weathersample.com",
    "organization_id": "0",
    "token_type": "BearerToken",
    "refresh_token": "IFl7jlijYuexu6XVSSjLMJq8SVXGOAAq",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "I6daIgMSiUgYX1K2qgQWPi37ztS6",
    "organization_name": "docs",
    "refresh_token_expires_in": "28799", //--in seconds
    "refresh_count": "0"
}

<GenerateResponse> が false に設定されている場合、このポリシーはレスポンスを返しません。代わりに、以下のフロー変数のセットにアクセス トークン付与に関するデータを入力します。

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in   //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token
oauthv2accesstoken.{policy-name}.refresh_token_expires_in  //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token_issued_at
oauthv2accesstoken.{policy-name}.refresh_token_status

例:

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token
oauthv2accesstoken.GenerateAccessToken.refresh_token_expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token_issued_at
oauthv2accesstoken.GenerateAccessToken.refresh_token_status

アクセス トークンをリクエストする: 暗黙的権限付与タイプ

このセクションでは、暗黙的権限付与タイプフローを使用してアクセス トークンをリクエストする方法について説明します。OAuth 2.0 の権限付与タイプについては、OAuth 2.0 の概要をご覧ください。

サンプル リクエスト

$ curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
  'https://docs-test.apigee.net/oauth/implicit?response_type=token&client_id=ABC123&redirect_uri=http://callback-example.com'

必須パラメータ

デフォルトでは、これらのパラメータをクエリ パラメータとする必要があります(上記のサンプルを参照)。ただし、この /token エンドポイントに添付されている OAuthV2 ポリシーで <ResponseType> 要素、<ClientId> 要素、<RedirectUri> 要素を構成することで、このデフォルト値を変更できます。詳細は、OAuthV2 ポリシーをご覧ください。

ユーザー認証情報は、通常は LDAP サービス コールアウトまたは JavaScript ポリシーを使用して格納された認証情報に照らして検証されます。

  • response_type - 値を token に設定する必要があります。
  • client_id - 登録されたデベロッパー アプリのクライアント ID。
  • redirect_uri - クライアントのデベロッパー アプリが登録されたときにコールバック URL が提供されなかった場合は、このパラメータを必ず指定してください。コールバック URL がクライアント登録時に指定された場合は、この値と比較され、完全一致しなければなりません。

オプション パラメータ

  • state - レスポンスとともに返される文字列。一般に、クロスサイト リクエスト フォージェリ攻撃を防ぐために使用します。
  • scope - 作成されたトークンを使用できる API プロダクトのリストをフィルタリングできます。スコープの詳細については、OAuth2 スコープの操作をご覧ください。

認証

暗黙的付与では Basic 認証を必要としません。ここで説明するように、クライアント ID をリクエスト パラメータとして渡す必要があります。

サンプル エンドポイント

ここでは、アクセス トークンを生成するためのエンドポイント構成のサンプルを示します。これにより GenerateAccessTokenImplicitGrant ポリシーが実行されます。

...
       <Flow name="generate-access-token-implicit">
            <Request>
                <Step>
                    <Name>GenerateAccessTokenImplicitGrant</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/implicit") and (request.verb = "POST")</Condition>
        </Flow>
...

サンプル ポリシー

これは基本的な GenerateAccessTokenImplicitGrant ポリシーで、暗黙的権限付与タイプフローでトークン リクエストを処理します。このポリシーを使用して構成できる任意の構成要素については、OAuthV2 ポリシーをご覧ください。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OAuthV2 name="GenerateAccessTokenImplicit">
    <DisplayName>GenerateAccessTokenImplicit</DisplayName>
    <Operation>GenerateAccessTokenImplicitGrant</Operation>
    <GenerateResponse enabled="true"/>
</OAuthV2>

戻り値

<GenerateResponse> が有効な場合、ポリシーはレスポンス ヘッダーで 302 Location リダイレクトを返します。このリダイレクトは、redirect_uri パラメータで指定された URL を指し、アクセス トークンとトークンの有効期限が付加されます。暗黙的付与タイプはリフレッシュ トークンをサポートしないことにご留意ください。例:

https://callback-example.com#expires_in=1799&access_token=In4dKm4ueoGZRbIYJhC9yZCmTFw5

<GenerateResponse> が false に設定されている場合、このポリシーはレスポンスを返しません。代わりに、以下のフロー変数のセットにアクセス トークン付与に関するデータを入力します。

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in  //--in seconds

例:

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in   //--in seconds

認可コードをリクエストする

認可コード権限付与タイプフローを使用している場合は、アクセス トークンをリクエストする前に認可コードを取得する必要があります。

サンプル リクエスト

$ curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
  'http://myorg-test.apigee.net/oauth/authorize?client_id={consumer_key}&response_type=code'

ここで、/oauth/authorize プロキシ エンドポイントで OAuthV2 GenerateAuthorizationCode ポリシーが添付されています(下記のサンプル エンドポイントをご覧ください)。

必須パラメータ

デフォルトでは、これらのパラメータをクエリ パラメータとする必要があります(上記のサンプルを参照)。ただし、この /authorize エンドポイントに添付されている OAuthV2 ポリシーで <ResponseType> 要素、<ClientId> 要素、<RedirectUri> 要素を構成することで、このデフォルト値を変更できます。詳細は、OAuthV2 ポリシーをご覧ください。

  • response_type - 値を code に設定する必要があります。
  • client_id - 登録されたデベロッパー アプリのクライアント ID。

オプション パラメータ

  • redirect_uri - コールバック URI 全体(一部ではなく)が登録済みのクライアント アプリで指定されている場合、このパラメータは任意です。コールバック URI 全体が指定されていない場合は必須です。コールバックは、作成した認可コードを Edge が送信する URL です。アプリの登録と API キーの管理をご覧ください。
  • state - レスポンスとともに返される文字列。一般に、クロスサイト リクエスト フォージェリ攻撃を防ぐために使用します。
  • scope - 作成されたトークンを使用できる API プロダクトのリストをフィルタリングできます。スコープの詳細については、OAuth2 スコープの操作をご覧ください。

認証

Basic 認証を必要としませんが、登録したクライアント アプリのクライアント ID をリクエストで入力しなければなりません。

サンプル エンドポイント

ここでは、認可コードを生成するためのエンドポイント構成のサンプルを示します。

<OAuthV2 name="GenerateAuthorizationCode">
  <Operation>GenerateAuthorizationCode</Operation>
    <!--
    ExpiresIn, in milliseconds. The ref is optional. The explicitly specified
    value is the default, when the variable reference cannot be resolved.
        60000 = 1 minute
       120000 = 2 minutes
    -->
  <ExpiresIn>60000</ExpiresIn>
  <GenerateResponse enabled="true"/>
</OAuthV2>

サンプル ポリシー

これは、基本的な GenerateAuthorizationCode ポリシーです。このポリシーを使用して構成できる任意の構成要素については、OAuthV2 ポリシーをご覧ください。

<OAuthV2 name="GenerateAuthorizationCode">
    <Operation>GenerateAuthorizationCode</Operation>
    <GenerateResponse enabled="true"/>
</OAuthV2>

戻り値

<GenerateResponse> が有効な場合、このポリシーは認可コードが添付された redirect_uri(コールバック URI)の場所に ?code クエリ パラメータを返します。302 ブラウザ リダイレクトを介して、レスポンスの Location ヘッダーの URL とともに送信されます(戻り値の例: ?code=123456)。

<GenerateResponse>false に設定されている場合、このポリシーはレスポンスを返しません。代わりに、以下のフロー変数のセットに認可コードに関するデータを入力します。

oauthv2authcode.{policy-name}.code
oauthv2authcode.{policy-name}.scope
oauthv2authcode.{policy-name}.redirect_uri
oauthv2authcode.{policy-name}.client_id

例:

oauthv2authcode.GenerateAuthorizationCode.code
oauthv2authcode.GenerateAuthorizationCode.scope
oauthv2authcode.GenerateAuthorizationCode.redirect_uri
oauthv2authcode.GenerateAuthorizationCode.client_id

アクセス トークンをリフレッシュする

リフレッシュ トークンとは、一般にアクセス トークンの有効期限が切れたり無効になったりした後で、アクセス トークンを取得するために使用する認証情報です。アクセス トークンを受け取ったときレスポンスでリフレッシュ トークンが返されます。

リフレッシュ トークンを使用して新しいアクセス トークンをリクエストするには、以下を参照してください。

サンプル リクエスト

次の呼び出しで Basic 認証ヘッダーをエンコードする方法については、Basic 認証情報をエンコードするをご覧ください。

$ curl -X POST \
  -H "Content-type: application/x-www-form-urlencoded" \
  -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \
  https://myorg-test.apigee.net/my_oauth_endpoint/refresh_accesstoken \
  -d 'grant_type=refresh_token&refresh_token=my-refresh-token'

必須パラメータ

  • grant_type - 値 refresh_token に設定する必要があります。
  • refresh_token - 更新したいアクセス トークンに関連付けられたリフレッシュ トークン。

デフォルトでは、上記の例に示すとおり、ポリシーがリクエスト本文で指定された x-www-form-urlencoded パラメータとしてこれらを検索します。これらの入力用の別の場所を構成するには、OAuthV2 ポリシーで <GrantType> 要素と <RefreshToken> 要素を使用します。詳細は、OAuthV2 ポリシーをご覧ください。

オプション パラメータ

  • state - レスポンスとともに返される文字列。一般に、クロスサイト リクエスト フォージェリ攻撃を防ぐために使用します。
  • scope - 作成されたトークンを使用できる API プロダクトのリストをフィルタリングできます。スコープの詳細については、OAuth2 スコープの操作をご覧ください。

認証

  • client_id
  • client_secret

クライアント ID とクライアント シークレットを Basic 認証ヘッダー(Base64 でエンコードされたもの)またはフォーム パラメータ client_idclient_secret として渡す必要があります。Basic 認証情報をエンコードするもご覧ください。

アクセス トークンをリフレッシュするとき、ユーザーの再認証はありません。

ここでは、リフレッシュ トークンを使用してアクセス トークンを生成するためのエンドポイント構成のサンプルを示します。これにより RefreshAccessToken ポリシーが実行されます。

 ...
       <Flow name="generate-refresh-token">
            <Request>
                <Step>
                    <Name>RefreshAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/refresh") and (request.verb = "POST")</Condition>
       </Flow>
...

サンプル ポリシー

これは基本的な RefreshAccessToken ポリシーであり、refresh_token 権限付与タイプを受け入れるよう構成されています。このポリシーを使用して構成できる任意の構成要素については、OAuthV2 ポリシーをご覧ください。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OAuthV2 name="RefreshAccessToken">
    <Operation>RefreshAccessToken</Operation>
    <GenerateResponse enabled="true"/>
    <ExpiresIn>1800000</ExpiresIn> <!-- 30 minutes -->
    <RefreshTokenExpiresIn>28800000</RefreshTokenExpiresIn> <!-- 8 hours -->
</OAuthV2>

戻り値

<GenerateResponse> を有効にすると、ポリシーは新しいアクセス トークンを含む JSON レスポンスを返します。refresh_token 権限付与タイプでは、アクセス トークンと新しいリフレッシュ トークンの両方を作成できます。例:

{
    "issued_at": "1420301470489",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "scope": "READ",
    "refresh_token_issued_at": "1420301470489",
    "status": "approved",
    "refresh_token_status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "tesla@weathersample.com",
    "token_type": "BearerToken",
    "refresh_token": "8fKDHLryAD9KFBsrpixlq3qPJnG2fdZ5",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "jmZ2Hqv3iNsABUtAAsfWR3QGNctw",
    "organization_name": "docs",
    "refresh_token_expires_in": "28799", //--in seconds
    "refresh_count": "2"
}

新しいリフレッシュ トークンが作成されると、元のトークンは有効でなくなります。

上記のレスポンスは、<GenerateResponse> が true に設定されている場合に返されます。<GenerateResponse> が false に設定されている場合、ポリシーはレスポンスを返しません。代わりに、以下のコンテキスト(フロー)変数のセットに、アクセス トークン付与に関するデータを入力します。

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in   //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token
oauthv2accesstoken.{policy-name}.refresh_token_expires_in  //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token_issued_at
oauthv2accesstoken.{policy-name}.refresh_token_status

例:

oauthv2accesstoken.RefreshAccessToken.access_token
oauthv2accesstoken.RefreshAccessToken.expires_in
oauthv2accesstoken.RefreshAccessToken.refresh_token
oauthv2accesstoken.RefreshAccessToken.refresh_token_expires_in
oauthv2accesstoken.RefreshAccessToken.refresh_token_issued_at
oauthv2accesstoken.RefreshAccessToken.refresh_token_status

Basic 認証情報をエンコードする

API 呼び出しでトークンまたは認可コードをリクエストする場合は、OAuth 2.0 仕様で client_id と client_secret の値を IETF RFC 2617 で説明のとおり HTTP 基本認証ヘッダーとして渡すことをおすすめします。これを行うには、2 つの値を結合してコロンで区切った結果を base64 エンコーディングする必要があります。

疑似コードの例:

result = Base64Encode(concat('ns4fQc14Zg4hKFCNaSzArVuwszX95X', ':', 'ZIjFyTsNgQNyxI'))

この例では、ns4fQc14Zg4hKFCNaSzArVuwszX95X が client_id で、ZIjFyTsNgQNyxI がクライアント シークレットです。

Base64 でエンコードされた値の計算に使用するプログラミング言語に関係なく、Base64 でエンコードされた結果は次のようになります。 bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJOg==

次に、トークン リクエストを以下のように行います。

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJOg==' \
  -X POST 'https://docs-test.apigee.net/oauth/accesstoken' \
  -d 'grant_type=client_credentials'

-u オプションを使用すると、curl ユーティリティによって実際に HTTP 基本ヘッダーが作成されます。以下は、上記と同等です。

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
  -u 'ns4fQc14Zg4hKFCNaSzArVuwszX95X:ZIjFyTsNgQNyxI' \
  -X POST 'https://docs-test.apigee.net/oauth/accesstoken' \
  -d 'grant_type=client_credentials'

他のプログラミング環境にも、base64 エンコード ヘッダーを自動的に生成する同様の近道があるかもしれません。

データベース内でトークンをハッシュする

データベースのセキュリティ侵害が発生した場合に OAuth のアクセス トークンとリフレッシュ トークンを保護するために、Edge 組織で自動トークン ハッシュを有効にできます。この機能を有効にすると、指定したアルゴリズムを使用して、新たに生成された OAuth のアクセス トークンとリフレッシュ トークンのハッシュされたバージョンが自動的に作成されます(既存のトークンをまとめてハッシュする方法については後述します)。API の呼び出しにはハッシュされていないトークンが使われ、Edge はそれらのトークンを、データベースにあるハッシュされたバージョンに対して検証します。

以下の組織レベルのプロパティは、OAuth トークンのハッシュを制御します。

features.isOAuthTokenHashingEnabled = true
features.OAuthTokenHashingAlgorithm = SHA1 | SHA256 | SHA384 | SHA512 | PLAIN

すでにハッシュされたトークンがあり、有効期限が切れるまで保持したい場合は、組織の中で以下の属性を設定します。ハッシュ アルゴリズムは既存のアルゴリズム(たとえば、Edge の以前のデフォルトである SHA1)を選びます。トークンがハッシュされていない場合は、PLAIN を使用します。

features.isOAuthTokenFallbackHashingEnabled = true
features.OAuthTokenFallbackHashingAlgorithm = SHA1 | SHA256 | SHA384 | SHA512 | PLAIN

Edge クラウドをご利用の場合は、Apigee サポートに連絡して、組織にこれらのプロパティを設定し、必要に応じて既存のトークンを一括でハッシュしてください。

関連トピック