認証コード付与タイプの実装

このページは Apigee と Apigee ハイブリッドに適用されます。

Apigee Edge のドキュメントを表示する。

認証コードは、最もよく使用される OAuth 2.0 権限付与タイプの 1 つです。認証コードフローは 3-legged OAuth 構成です。この構成では、ユーザーはリソースサーバーで自分自身を認証して、保護されたリソースにアクセスする許可をアプリに与えます。クライアントアプリにユーザー名 / パスワードを提供する必要はありません。

このトピックについて

このトピックでは、OAuth 2.0 認証権限付与タイプのフローの一般的な説明と概要を示し、Apigee でこのフローを実装する方法について説明します。

動画

OAuth 2.0 認証権限付与タイプを使用して API を保護する方法については、こちらの短い動画をご覧ください。

ユースケース

この権限付与タイプは、API プロバイダと信頼できるビジネス関係を築いていないサードパーティデベロッパーが作成したアプリに使用します。たとえば、パブリック API プログラムに登録しているデベロッパーは、一般的には信頼しないようにする必要があります。この権限付与タイプでは、リソースサーバー上のユーザー認証情報がアプリと共有されることはありません。

コードサンプル

Apigee 上で機能する認証コード権限付与タイプの完全な実装サンプルは、GitHub の api-platform-samples リポジトリにあります。api-platform-samples/sample-proxies ディレクトリの oauth-advanced サンプルをご覧ください。サンプルの詳細については、README ファイルをご覧ください。

フロー図

次のフロー図は、Apigee が認可サーバーとして機能する認証コードの OAuth フローを示しています。

認証コードの OAuth フロー。

認証コードフローの手順

以下に、Apigee が認可サーバーとして機能する認証コード権限付与タイプを実装するために必要な手順の概要を示します。このフローの鍵となるのは、クライアントがリソースサーバー上のユーザー認証情報を見ることはないということです。

前提条件: クライアントアプリを Apigee に登録して、クライアント ID とクライアントシークレットキーを取得する必要があります。詳細については、クライアントアプリの登録をご覧ください。

1. ユーザーがフローを開始する

アプリがリソースサーバーからユーザーの保護されたリソース（ソーシャルメディアサイトの連絡先リストなど）にアクセスする必要がある場合、アプリは、API 呼び出しを Apigee に送信し、Apigee がクライアント ID を検証します。クライアント ID が有効な場合は、ユーザーのブラウザがログインページにリダイレクトされて、そこでユーザーが認証情報を入力します。API 呼び出しには、クライアントアプリの登録時に取得した情報（クライアント ID とリダイレクト URI）が含まれています。

2. ユーザーが認証情報を入力する

ログインページが表示され、ログイン認証情報の入力を求められます。ログインに成功したら、次のステップに進みます。

[Email address] フィールドと [Password] フィールドが表示された Apigee のログインページ

3. ユーザーが同意する

このステップで、ユーザーは自分のリソースにアプリがアクセスすることに同意します。通常、同意フォームにはスコープの選択が含まれており、リソースサーバーでアプリに許可する操作を選択できます。たとえば、読み取り専用の権限や、アプリがリソースを更新する権限を与えることができます。

サンプルアプリが [Allow] ボタンと [Deny] ボタンでオーダーをリクエストする同意ページ。

4. ログインアプリが Apigee にリクエストを送信する

ログインと同意が完了すると、ログインアプリは Apigee の /authorizationcode エンドポイントにデータを POST します。データには、リダイレクト URI、クライアント ID、スコープ、ユーザー固有の情報、ログインに成功したことを示す情報が含まれます。

5. Apigee が認証コードを生成する

Apigee が /authorizationcode エンドポイント上のログインアプリから GET リクエストを受け取ると、次の 2 つのことが発生します。まず、Apigee はログインが成功したと判断します（HTTP ステータスの確認やその他の手段から判断します）。次に、Apigee はログインアプリから送信されたリダイレクト URI が、Apigee へのアプリ登録時に指定されたリダイレクト URI と一致していることを確認します。すべて問題なければ、Apigee が認証コードを生成します。次に例を示します。

http://myorg-test.apigee.net/oauth/authorizationcode?client_id={consumer_key}&response_type=code&redirect_uri={redirect_uri}&scope=scope1%20scope2&state={some_string}

6. Apigee がクライアントに認証コードを返送する

Apigee は、クエリパラメータとしてアタッチされた認証コードとともにクライアントに 302 リダイレクトを送信します。

7. クライアントが認証コードを取得し、Apigee にアクセスコードをリクエストする

クライアントは、有効な認証コードを使用して Apigee にアクセストークンをリクエストできます。クライアント ID とクライアントシークレットキー（アプリが Apigee に登録されたときに取得されたもの）、権限付与タイプ、スコープを POST してリクエストします。クライアント ID とシークレットキーを含めることで、Apigee はクライアントアプリが登録済みのものであることを確認できます。次に例を示します。

$ curl https://{org_name}-test.apigee.net/my_oauth_proxy/accesstoken?code=Xyz123&grant_type=authorization_code -X POST -d 'client_id=bBGAQrXgivA9lKu7NMPyoYpKNhGar6K&client_secret=hAr4GngA9vAyvI4'

8. クライアントがアクセストークンを受け取る

すべてが正常に完了すると、Apigee はアクセストークンをクライアントに返します。アクセストークンには有効期限があり、ユーザーがアプリにリソースへのアクセスを許可したときに指定したスコープでのみ有効です。

9. 保護された API をクライアントが呼び出す

ここで、有効なアクセスコードを使って、クライアントは保護された API を呼び出すことができます。このシナリオでは、Apigee（プロキシ）にリクエストが行われ、Apigee はターゲットリソースサーバーに API 呼び出しを渡す前にアクセストークンを検証します。アクセストークンは認証ヘッダーで渡されます。次に例を示します。

$ curl -H "Authorization: Bearer ylSkZIjbdWybfs4fUQe9BqP0LH5Z" http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282

フローとポリシーを構成する

Apigee は、認可サーバーとしてアクセストークン、認証コード、更新トークン、ログインページのリダイレクトなど、多数の OAuth リクエストを処理する必要があります。これらのエンドポイントを構成する基本的な手順は次の 2 つです。

カスタムフローの作成
OAuthV2 ポリシーの追加と構成

カスタムフローの構成

通常、この権限付与タイプのフローでは、フローの各ステップまたは区間が Apigee プロキシのフローによって定義されるように構成します。各フローには、認証コードやアクセストークンの生成など OAuth 固有のタスクを実行するエンドポイントとポリシーがあります。たとえば、以下の XML に示すように、/oauth/authorizationcode エンドポイントには GenerateAuthCode という関連ポリシー（GenerateAuthorizationCode オペレーションが指定されている OAuthV2 ポリシー）があります。

フロー構成を表示する最も簡単な方法は、XML の例を使用することです。各フローの詳細については、インラインコメントをご覧ください。これは一例です。必要に応じてフローとパスの名前を構成できます。このようなカスタムフローを作成するために必要な手順の概要については、OAuth のエンドポイントとポリシーの構成をご覧ください。

GitHub の実装例もご覧ください。

<Flows>
  <Flow name="RedirectToLoginApp">
         <!-- 
         Publish this URI to developers to use for their 'login' link 
         -->
    <Condition>proxy.pathsuffix == "/oauth/authorize"</Condition>
    <Request>
        <Step><Name>RedirectToLoginPage</Name></Step>
    </Request>
  </Flow>
  <Flow name="GetAuthCode">
         <!-- 
         Call this URL from your Login app after you authenticate the user.
         The policy will automatically return the auth code in the response to the 
         redirect_uri registered by the calling app 
         -->
    <Condition>proxy.pathsuffix == "/oauth/authorizationcode"</Condition>
    <Request>
        <Step><Name>GenerateAuthCode</Name></Step>
    </Request>
  </Flow>
  <Flow name="GetAccessToken">
         <!-- This policy flow is triggered when the URI path suffix
         matches /oauth/accesstoken. Publish this URL to app developers 
         to use when obtaining an access token using an auth code   
         -->
    <Condition>proxy.pathsuffix == "/oauth/accesstoken"</Condition>
    <Request>
        <Step><Name>GenerateAccessToken</Name></Step>
    </Request>
  </Flow>
</Flows>

ポリシーでフローを構成する

各エンドポイントにはポリシーが関連付けられています。ポリシーの例を見てみましょう。OAuthV2 ポリシーをプロキシエンドポイントに追加するために必要な手順の概要については、OAuth エンドポイントとポリシーの構成もご覧ください。

これは /oauth/authorize パスです。接続されたポリシーによって、ユーザーはログインアプリにリダイレクトされます。ここで、エンドユーザーはクライアントアプリを安全に認証して、保護されたリソースへのアクセスを許可できます。クライアントアプリにユーザー名とパスワードを提供する必要はありません。この方法は、サービスコールアウトポリシー、JavaScript、その他の手段で実現できます。

リクエストを行うための API 呼び出しは GET であり、クエリパラメータの client_id、response_type、redirect_uri、scope、state が必要です。

$ curl http://myorg-test.apigee.net/oauth/authorize?client_id={consumer_key}&response_type=code&redirect_uri={redirect_uri}&scope=scope1%20scope2&state={some_string}

認証コードを取得する

これは /oauth/authorizationcode パスです。GenerateAuthorizationCode オペレーションが指定された OAuthV2 ポリシーが使用されています。

<OAuthV2 async="false" continueOnError="false" enabled="true" name="GetAuthCode">
    <DisplayName>GetAuthCode</DisplayName>
    <Operation>GenerateAuthorizationCode</Operation>
    <ExpiresIn>600000</ExpiresIn>
    <GenerateResponse/>
</OAuthV2>

認証コードを取得するための API 呼び出しは GET であり、次の例に示すようにクエリパラメータの client_id、response_type、必要に応じて scope、state が必要です。

$curl http://myorg-test.apigee.net/oauth/authorizationcode?client_id={consumer_key}&response_type=code&scope=scope1%20scope2&state={some_string}

アクセストークンを取得する

このポリシーは、/oauth/accesstoken パスに接続されています。GenerateAccessCode オペレーションが指定された OAuthV2 ポリシーが使用されています。この場合、grant_type パラメータはクエリパラメータとして想定されています。

<OAuthV2 name="GetAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>360000000</ExpiresIn> 
    <SupportedGrantTypes> 
        <GrantType>authorization_code</GrantType> 
    </SupportedGrantTypes> 
    <GrantType>request.queryparam.grant_type</GrantType> 
    <GenerateResponse/> 
</OAuthV2>

アクセスコードを取得するための API 呼び出しは POST であり、client_id、client_secret、grant_type=authorization_code、必要に応じて scope が含まれている必要があります。次に例を示します。

$ curl https://{org_name}-test.apigee.net/oauth/accesstoken?grant_type=authorization_code -X POST -d 'client_id=bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K&client_secret=hAr4Gn0gA9vAyvI4'

これは基本的な概要にすぎません。本番環境の例には、URL の構築、変換の実施、その他のタスクの実行に使用するポリシーが他にも多数含まれています。完全かつ実用的なプロジェクトについては、GitHub のサンプルをご覧ください。

アクセストークン検証ポリシーの接続

保護された API にアクセスするすべてのフローの先頭に VerifyAccessToken ポリシー（VerifyAccessToken オペレーションが指定されている OAuthV2 ポリシー）を接続し、保護されたリソースに対するリクエストが発生するたびに実行されるようにします。Apigee は、各リクエストに有効なアクセストークンがあることを確認します。ない場合は、エラーが返されます。基本的な手順については、アクセストークンの検証をご覧ください。

<OAuthV2 async="false" continueOnError="false" enabled="true" name="VerifyAccessToken">
    <DisplayName>VerifyAccessToken</DisplayName>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>VerifyAccessToken</Operation>
    <SupportedGrantTypes/>
    <GenerateResponse enabled="true"/>
    <Tokens/>
</OAuthV2>

保護された API の呼び出し

OAuth 2.0 セキュリティで保護された API を呼び出すには、有効なアクセストークンを提示する必要があります。正しいパターンでは、次のように認証ヘッダーにトークンを含めます。アクセストークンは署名なしトークンとも呼ばれます。

$ curl -H "Authorization: Bearer UAj2yiGAcMZGxfN2DhcUbl9v8WsR" \
  http://myorg-test.apigee.net/v0/weather/forecastrss?w=12797282

アクセストークンの送信もご覧ください。