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

このトピックでは、アクセスコードと認可コードをリクエストする方法、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_id および client_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_id および client_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 であり、リクエスト本文に指定する必要があります(上のサンプルを参照)。しかし、この <GrantType> エンドポイントに添付される OAuthV2 ポリシーで <Username><Password>/token の各要素を構成することで、このデフォルトを変更できます。詳細は、OAuthV2 ポリシーをご覧ください。

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

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

オプション パラメータ

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

認証

クライアント ID とクライアント シークレットを、Basic 認証ヘッダー(Base64 エンコード)として、あるいはフォーム パラメータ client_id および client_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 - このパラメータは、クライアント デベロッパー アプリが登録されたときコールバック URI が指定されなかった場合に必須です。コールバック 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 ロケーション リダイレクトを返します。リダイレクトは 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'
    

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

必須パラメータ

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

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

オプション パラメータ

  • redirect_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> を有効にすると、ポリシーは ?code クエリ パラメータに認可コードを添付して、redirect_uri(コールバック URI)の場所に返します。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 パラメータとして探します。これらの入力の代わりの場所を構成するには、<GrantType> 要素と <RefreshToken> 要素を OAuthV2 ポリシーで使用します。詳細は、OAuthV2 ポリシーをご覧ください。

オプション パラメータ

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

認証

  • client_id
  • client_secret

クライアント ID とクライアント シークレットを、Basic 認証ヘッダー(Base64 エンコード)として、あるいはフォーム パラメータ client_id および client_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 の値を HTTP-Basic Authentication ヘッダーとして渡すことを推奨しています。詳しくは、IETF RFC 2617 で説明されています。これを行うには、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'
    

curl ユーティリティは、-u オプションを使用した場合に、実際に HTTP Basic ヘッダーを作成します。以下は、上記と同等です。

    $ 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 Cloud のお客様は、Apigee サポートに連絡して、これらのプロパティを組織で設定し、必要に応じて既存のトークンをまとめてハッシュできます。

関連トピック