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"
}

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

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

次のリクエストでは、client_idconsumerKey の値に置き換えます。関連する 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 です。

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 カスタマー サポートをご覧ください。