OAuth

OAuth は現在、API の主要な認可プロトコルです。このトピックで説明する OAuth のバージョンは、OAuth 2.0 仕様で定義されています。

OAuth プロトコルを使用すると、アプリはアプリのエンドユーザーから許可を受けて、そのユーザーのために処理を行うことができます。そのためにアプリは、API プロバイダからアクセストークンを取得します。API プロバイダはアプリのエンドユーザーの認証情報を認証し、ユーザーがアプリを認可していることを確認した後、アプリに対してアクセストークンを発行します。保護されている API がアプリで使用されると、Apigee Edge はアクセストークンを検査し、トークンが有効で期限が切れていないことを確認します。API プロバイダは、アプリがアクセストークンを取得できるエンドポイントを公開する必要があります。

OAuth を簡単に使い始めることができるように、Apigee Edge では、ポリシーを使用して OAuth を構成、適用できます。その際、コードを書く必要はありません。このトピックでは、API を保護する方法、アクセストークンを取得する方法、保護されている API にアクセストークンでアクセスする方法を説明します。

組織のデフォルト OAuth 構成

便宜上、Apigee Edge 上のすべての組織には、クライアント認証情報権限付与タイプを実装する一連の OAuth 2.0 エンドポイントが事前構成されています。クライアント認証情報権限付与タイプは、アプリの認証情報と引き換えにアクセストークンを発行する手順を定義します。アプリの認証情報は単に、組織に登録されている各アプリに関して Apigee Edge が発行するコンシューマキーとシークレットのペアです。「クライアント認証情報」とは、コンシューマキーとシークレットのペア自体を指します。

Edge Developer Services を使用するアプリに対し認証情報を発行する方法については、アプリの登録とキーの管理をご覧ください。

したがって、API セキュリティスキームを API キー検証から OAuth クライアント認証情報に強化することは比較的簡単です。どちらのスキームも、同じコンシューマキーとシークレットを使用してクライアントアプリを検証します。異なる点として、クライアント認証情報の場合、アクセストークンを必要に応じて簡単に取り消すことができ、その際にアプリのコンシューマキーを取り消す必要がないので、追加の制御層が実現します。デフォルト OAuth エンドポイントを操作するには、組織内でアプリ用に生成されたコンシューマキーとシークレットを使用して、トークンエンドポイントからアクセストークンを取得できます（すでにコンシューマキーとシークレットを持つアプリ用にクライアント認証情報を有効にすることもできます）。

クライアント認証情報権限付与の詳細な仕様については、OAuth 2.0 の仕様をご覧ください。

ポリシーを使用した API の保護

アクセストークンを使用するには、実行時に OAuth アクセストークンを検証するよう API をあらかじめ構成しておく必要があります。そのためには、アクセストークンを検証するように API プロキシを構成します。つまりアプリは、いずれかの API を使用するリクエストを発行するたびに、有効なアクセストークンを API リクエストとともに提示する必要があります。提示されるアクセストークンの生成、保管、検証などの複雑な処理は、Apigee Edge により行われます。

OAuth 検証は、新しい API プロキシを作成する際、簡単に API に追加できます。新しい API プロキシを作成する際、[Add Features] を使用します。以下に示すとおり、[Secure with OAuth v2.0 Access Tokens] の横のラジオボタンを選択すると、OAuth 2.0 アクセストークンの検証を追加できます。このオプションを選択すると、新しく作成された API プロキシにポリシーが 2 つ接続されます。1 つはアクセストークンを検証するポリシー、もう 1 つは検証後のアクセストークンを削除するポリシーです。

また、[Secure with OAuth v2.0 Access Tokens] オプションを選択すると、[Publish API Product] チェックボックスが選択可能になり、自動的に選択されます。新しい API プロキシを作成するときにプロダクトを自動的に生成する場合は、このチェックボックスをオンにします。自動生成されるプロダクトは、新しい API プロキシに関連付けられた状態で作成されます。この新しい API を関連付ける既存のプロダクトがある場合は、不要なプロダクトが作成されないよう、このチェックボックスを必ずオフにしてください。プロダクトについて詳しくは、API プロダクトとはをご覧ください。

既存の API プロキシに関するアクセストークン検証を有効には、保護対象の API にタイプ OAuthV2 ポリシーを接続するだけです。OAuthV2 ポリシーは、オペレーションを指定することにより機能します。アクセストークンを検証する場合は、VerifyAccessToken というオペレーションを指定します（この他に OAuthV2 ポリシータイプでサポートされているオペレーションタイプは、GenerateAccessToken と GenerateRefreshToken です。これらのオペレーションについては、OAuth エンドポイントをセットアップする際に説明します）。

タイプ OAuthV2 の VerifyOAuthTokens ポリシー

アクセストークンを検証するポリシーの例を次に示します（設定内容については、その下の表で説明します）。

<OAuthV2 name="VerifyOAuthTokens">
  <Operation>VerifyAccessToken</Operation>
</OAuthV2>

ポリシー設定

名前	説明	デフォルト	要否
`OAuthV2`	ポリシータイプ
`name`	ポリシー名。API プロキシエンドポイント構成でこれが参照されます。	なし	○
`Operation`	OAuthV2 ポリシーで実行されるオペレーション。VerifyAccessToken を指定するとポリシーが構成されます。こうしてアクセストークンに対するリクエストを検査し、アクセストークンが有効かつ期限内で、リクエストされた API リソース（URI）の使用が承認されることを検証します（この検査を行うために、ポリシーは、アプリでの使用が承認されている API プロダクトを読み取ります）。	なし	○

このポリシーを管理 UI で作成するには、[APIs] > [API Proxies] に移動します。

API プロキシのリストから [weatherapi] を選択します。

weatherapi の [Overview] で [Develop] ビューを選択します。

プルダウンメニューから [New Policy] > [OAuth v2.0] を選択します。

OAuth v2.0 ポリシーを選択すると、[New Policy] 構成メニューが表示されます。

ポリシーにわかりやすい名前を付け、ポリシーの接続設定として [Attach Policy]、[Flow PreFlow]、[Request] を選択します。

[Add] を選択すると、ポリシーが作成され、weatherapi のリクエスト PreFlow に接続されます。

ポリシーを追加すると、以下のリクエスト PreFlow の構成が [Designer] ペインに表示されます。

テキストエディタまたは IDE を使ってローカルで作業している場合は、保護する API プロキシのリクエスト PreFlow にポリシーを次のように接続します。

<PreFlow>
  <Request>
    <Step><Name>VerifyOAuthTokens</Name></Step>
  </Request>
</PreFlow>

リクエスト PreFlow にポリシーを接続すると、すべてのリクエストメッセージにこのポリシーが常に適用されるようになります。

これで、OAuth 2.0 クライアント認証情報を使用して API を保護しました。次に、アクセストークンを取得する方法と、それを使用してセキュア API にアクセスする方法を説明します。

アクセストークンを使用した保護リソースへのアクセス

これで OAuth 2.0 により weatherapi が保護されたため、アプリはこの API を使用するためにアクセストークンを提示する必要があります。保護されたリソースにアクセスするために、アプリは次のようにリクエスト内でアクセストークンを「Authorization」HTTP ヘッダーとして提示します。

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

API には OAuthV2 ポリシーが接続されているので、Apigee Edge は提示されたアクセストークンが有効であることを検証した後、API にアクセス権限を付与し、リクエストの送信元アプリに天候レポートを返します。

では、アプリはどんな方法でアクセストークンを取得するのでしょうか？次のセクションではこの点について説明します。

アクセストークン用にクライアント認証情報を交換する方法

アプリは、コンシューマキーとシークレットのペアをトークンエンドポイントに提示することでアクセストークンを取得します。トークンエンドポイントは oauth という API プロキシに構成されます。そのため、アプリは oauth API プロキシによって公開された API を呼び出してアクセストークンを取得する必要があります。アクセストークンを取得した後、アクセストークンが期限切れになるか取り消されるまで、アプリは weatherapi を繰り返し呼び出すことができます。

次に、アプリデベロッパーの作業に視点を移しましょう。アプリデベロッパーは、weatherapi を呼び出すためにアプリのアクセストークンを取得する必要があります。まず、コンシューマキーとシークレットのペア（API キーまたはアプリキーとも呼ばれます）を取得します。

Apigee Edge 上の組織にアプリを登録することで、コンシューマキーとシークレットを取得できます。

組織内のすべてのアプリは、Apigee Edge 管理 UI で確認できます。

組織に登録されているアプリのリストが表示されます。

（アプリが表示されない場合は、アプリの登録と API キーの管理というトピックでアプリの登録方法を確認してください）。

リストからアプリを選択すると、そのアプリの詳細なプロファイルが表示されます。

選択したアプリの詳細ビューで、[Consumer Key] フィールドと [Consumer Secret] フィールドの値を書き留めます。この 2 つの値は、OAuth アクセストークンの取得に使用するクライアント認証情報です。

$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apps \
-u myname:mypass

この呼び出しは、アプリ ID 別のアプリのリストを返します。

[ "da496fae-2a04-4a5c-b2d0-709278a6f9db", "50e3e831-175b-4a05-8fb6-05a54701af6e" ]

特定のアプリのプロファイルを取得するには、そのアプリのアプリ ID に対する単純な GET 呼び出しを行います。

$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apps/{app_id} \
-u myname:mypass

例:

$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apps/da496fae-2a04-4a5c-b2d0-709278a6f9db \
-u myname:mypass

この API 呼び出しにより、指定したアプリのプロファイルが返されます。たとえば、weatherapp のアプリプロファイルには次の JSON 表現があります。

{
  "accessType" : "read",
  "apiProducts" : [ ],
  "appFamily" : "default",
  "appId" : "da496fae-2a04-4a5c-b2d0-709278a6f9db",
  "attributes" : [ ],
  "callbackUrl" : "http://weatherapp.com",
  "createdAt" : 1380290158713,
  "createdBy" : "noreply_admin@apigee.com",
  "credentials" : [ {
    "apiProducts" : [ {
      "apiproduct" : "PremiumWeatherAPI",
      "status" : "approved"
    } ],
    "attributes" : [ ],
    "consumerKey" : "bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K",
    "consumerSecret" : "hAr4Gn0gA9vAyvI4",
    "expiresAt" : -1,
    "issuedAt" : 1380290161417,
    "scopes" : [ ],
    "status" : "approved"
  } ],
  "developerId" : "5w95xGkpnjzJDBT4",
  "lastModifiedAt" : 1380290158713,
  "lastModifiedBy" : "noreply_admin@apigee.com",
  "name" : "weatherapp",
  "scopes" : [ ],
  "status" : "approved"
}

consumerKey と consumerSecret の値を書き留めます。この認証情報を使用してアクセストークンを取得するには、次に示すように、HTTP リクエストで基本認証の認証情報としてこの認証情報を指定します。リクエストのクエリパラメータとして権限付与タイプが提示されます（変数 {org_name} の値を Apigee Edge 上の組織の名前を反映するように必ず変更してください）。

アクセストークン取得リクエストの作成

次のリクエストでは、client_id を consumerKey の値に置き換えます。関連する consumerSecret の値を client_secret に置き換えます。

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

API Services は、コンシューマキーとシークレットを検証し、このアプリ用のアクセストークンを含むレスポンスを生成します。

{
  "issued_at" : "1380892555397",
  "application_name" : "957aa73f-25c2-4ead-8021-adc01f0d2c6b",
  "scope" : "",
  "status" : "approved",
  "api_product_list" : "[oauth-test]",
  "expires_in" : "3599",
  "developer.email" : "tesla@weathersample.com",
  "organization_id" : "0",
  "client_id" : "bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K",
  "access_token" : "ylSkZIjbdWybfs4fUQe9BqP0LH5Z",
  "organization_name" : "rqa",
  "refresh_token_expires_in" : "0",
  "refresh_count" : "0"
}

上記のレスポンス内の access_token の値を書き留めます。これは、保護対象リソースへの実行時アクセス権限を得るためにアプリが使用するアクセストークンです。このアプリのアクセストークンは ylSkZIjbdWybfs4fUQe9BqP0LH5Z です。

これで、保護された API へのアクセスに使用できる有効なアクセストークン ylSkZIjbdWybfs4fUQe9BqP0LH5Z が取得されました。

デフォルトの OAuth 構成の操作

Apigee Edge における各組織（無料トライアル版の組織を含む）は、OAuth トークンエンドポイント付きでプロビジョニングされています。エンドポイントは、oauth という API プロキシのポリシーを使用して事前構成されています。Apigee Edge でアカウントを作成するとすぐに、トークンエンドポイントの使用を開始できます。

デフォルト OAuth エンドポイントは、次のエンドポイント URI を公開します。

/oauth/client_credential/accesstoken

この URI は、アクセストークンを取得する必要のあるデベロッパーに公開します。アプリデベロッパーは、アプリを構成する際、アプリがこのエンドポイントを呼び出し、コンシューマキーとシークレットのペアを提示して、アクセストークンを取得するようにします。

デフォルトのクライアント認証情報トークンエンドポイントは、次の URL でネットワーク上に公開されます。

https://{org_name}-{env_name}.apigee.net/oauth/client_credential/accesstoken

たとえば組織名が「apimakers」の場合、URL は次のようになります。

https://apimakers-test.apigee.net/oauth/client_credential/accesstoken

これは、アクセストークンを取得するためにデベロッパーが呼び出す URL です。

ヒント: デフォルトでは、すぐに使用できる OAuth エンドポイントがテスト環境にのみデプロイされます。本番環境で使用する前に、oauth という API プロキシを prod に明示的にデプロイする必要があります。

3-legged OAuth 構成

3-legged OAuth 構成（認可コード、暗黙的権限付与タイプ、パスワード権限付与タイプ）では、API プロバイダがアプリのエンドユーザーを認証する必要があります。組織によってユーザーの認証方法が異なるので、ユーザーストアと OAuth を統合するには、なんらかのポリシーカスタマイズまたはコードが必要になります。たとえば、すべてのユーザーが Active Directory、LDAP、その他のユーザーストアに保存されている場合があります。3-legged OAuth を機能させるには、ユーザーストアに対する検査を、全体的な OAuth フローの中に統合する必要があります。

OAuth 1.0a

OAuth 1.0a ポリシーの詳細については、OAuth v1.0a ポリシーをご覧ください。

ヘルプ

サポートについては、Apigee カスタマーサポートをご覧ください。