OAuth

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

OAuth プロトコルを使用すると、アプリアプリのエンドユーザーから許可を受けて、ユーザーのために処理を行うことができます。それを行うために、アプリは API プロバイダからアクセス トークン 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 により行われます。

新しい API プロキシを作成するときには、OAuth 検証を簡単に API に追加できます。新しい API プロキシを作成するときに、機能を追加できます。以下に示すように、OAuth 2.0 アクセス トークンの検証を追加するには、[Secure with OAuth v2.0 Access Tokens] の横にあるラジオボタンを選択します。このオプションを選択すると、新しく作成された 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 にアクセスする方法を説明します。

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

weatherapi が OAuth 2.0 で保護されるようになったので、アプリは 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 リクエストで基本認証の認証情報としてこの認証情報を指定します。リクエストのクエリ パラメータとして付与タイプが提示されます(Apigee Edge の実際の組織の名前を反映するよう、変数 {org_name} の値を必ず変更してください)。

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

次のリクエストで、client_id を実際の consumerKey の値に置き換えます。client_secret を、関連付けられている consumerSecret の値に置き換えます。

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