OAuth2 を使用して Management API にアクセスする

Apigee Edge では、OAuth2 トークンで認証された Management API 呼び出しを行うことができます。OAuth2 のサポートは、Cloud アカウントについては Edge 上でデフォルトで有効になっています。Apigee Edge for Public Cloud を使用している場合、最初に SAML を設定しなければ、OAuth2 を使用できません。

OAuth2 の仕組み（Apigee Management API を使用）

Apigee の Management API を呼び出す場合、ユーザーが本人であることを確認するための認証が必要です。ユーザーを認証するには、API にアクセスするリクエストと一緒に OAuth2 アクセストークンを送信する必要があります。

たとえば、Edge 上の組織に関する詳細情報を取得する場合は、次のような URL にリクエストを送信します。

https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval

しかし、ユーザーが誰であるかを伝えずに、リクエストを送信することはできません。そうでなければ、組織の詳細情報を誰でも表示できることになります。

ここで OAuth2 が必要となります。ユーザーを認証するために、ユーザーにこのリクエストでアクセストークンも送信してもらう必要があります。アクセストークンによってユーザーが識別されるため、組織の詳細情報を表示することが許可されたユーザーであることを確認できます。

幸いなことに、Edge OAuth2 サービスに認証情報を送信することによってトークンを取得できます。このサービスはアクセストークンとリフレッシュトークンで応答します。

OAuth2 のフロー: 最初のリクエスト

次の図は、Management API に初めてアクセスしたときの OAuth2 のフローを示しています。

図 1 に示すように、Management API への最初のリクエストを行うと、次のようになります。

アクセストークンをリクエストします。この操作は、Management API、acurl、または get_token で行うことができます。次に例を示します。

get_token
    Enter username:
    ahamilton@apigee.com
    Enter the password for user 'ahamilton@apigee.com'
    mypassw0rd
    Enter the six-digit code if 'ahamilton@apigee.com' is MFA enabled or press ENTER:
    123456

Edge OAuth2 サービスはアクセストークンで応答し、stdout に出力します。次に例を示します。

    Dy42bGciOiJSUzI1NiJ9.eyJqdGkiOiJhM2YwNjA5ZC1lZTIxLTQ1YjAtOGQyMi04MTQ0MTYxNjNhNTMiLCJz
    AJpdGUiLCJhcHByb3ZhbHMubWUiLCJvYXV0aC5hcHByb3ZhbHMiXSwiY2xpZW50X2lkIjoiZWRnZWNsaSIsIm
    NjbGkiLCJhenAiOiJlZGdlY2xpIiwiZ3JhbnRfdHlwZSI6InBhc3N3b3JkIiwidXNlcl9pZCI6IjJkMWU3NDI
    GzQyMC1kYzgxLTQzMDQtOTM4ZS1hOGNmNmVlODZhNzkiLCJzY29wZSI6WyJzY2ltLm1lIiwib3BlbmlkIiwic
    ENC05MzhlLWE4Y2Y2ZWU4NmE3OSIsIm9yaWdpbiI6InVzZXJncmlkIiwidXNlcl9uYW1lIjoiZGFuZ2VyNDI0
    RI6ImUyNTM2NWQyIiwiaWF0IjoxNTI4OTE2NDA5LCJleHAiOjE1Mjg5MTgyMDksImlzcyI6Imh0dHBzOi8vbG
    420iLCJlbWFpbCI6ImRhbmdlcjQyNDJAeWFob28uY29tIiwiYXV0aF90aW1lIjoxNTI4OTE2NDA5LCJhbCI6M
    2lLmNvbSIsInppZCI6InVhYSIsImF1ZCI6WyJlZGdlY2xpIiwic2NpbSIsIm9wZW5pZCIsInBhc3N3b3JkIiw

acurl および get_token ユーティリティは、アクセストークンとリフレッシュトークンを ~/.sso-cli にサイレントに保存します（リフレッシュトークンは stdout に書き込まれません）。トークンを取得するために Management API を使用する場合は、後で使用するためにトークンを保存する必要があります。

アクセストークンと一緒にリクエストを Management API に送信します。acurl はトークンを自動的に付加します。次に例を示します。
```
acurl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval
```
別の HTTP クライアントを使用する場合は、必ずアクセストークンを追加してください。次に例を示します。
```
curl -v https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
      -H "Authorization: Bearer ACCESS_TOKEN"
```
Management API はリクエストを実行し、通常はデータを含むレスポンスを返します。

OAuth2 のフロー: 後続のリクエスト

その後のリクエストでは、トークン用の認証情報を交換する必要はありません。ユーザーがすでに持っているアクセストークンが期限切れになっていなければ、認証情報を交換する代わりにアクセストークンを含めるだけでかまいません。

図 2 に示すように、すでにアクセストークンを持っている場合は次のようになります。

アクセストークンと一緒にリクエストを Management API に送信します。acurl はトークンを自動的に付加します。他のツールを使用する場合は、トークンを手動で追加する必要があります。
Management API はリクエストを実行し、通常はデータを含むレスポンスを返します。

OAuth2 のフロー: アクセストークンが期限切れになったとき

アクセストークンが期限切れになると（30 分後）、リフレッシュトークンを使用して新しいアクセストークンを取得できます。

図 3 に示すように、アクセストークンが期限切れになった場合は次のようになります。

Management API にリクエストを送信しますが、アクセストークンは期限切れになっています。
Management API は、リクエストを認可されていないものとして拒否します。
Edge OAuth2 サービスにリフレッシュトークンを送信します。acurl を使用している場合、この操作は自動的に行われます。
Edge OAuth2 サービスは新しいアクセストークンで応答します。
新しいアクセストークンと一緒にリクエストを Management API に送信します。
Management API はリクエストを実行し、通常はデータを含むレスポンスを返します。

トークンを取得する

Management API に送信できるアクセストークンを取得するには、curl などのユーティリティに加えて次の Apigee ユーティリティを使用できます。

get_token ユーティリティ: Apigee 認証情報をアクセストークンおよびリフレッシュトークンと交換します。
acurl ユーティリティ: Apigee 認証情報をトークンと交換し、リクエストにアクセストークンを渡し、アクセストークンが期限切れになったときにアクセストークンを自動的に更新する curl ラッパー。
Management API のトークンエンドポイント: Management API への呼び出しを介して、Apigee 認証情報をアクセストークンおよびリフレッシュトークンと交換します。

これらのユーティリティはすべて、Apigee アカウントの認証情報（メールアドレスとパスワード）をアクセストークンと交換します。これらのトークンは 30 分間有効です。

また、これらのユーティリティは、リフレッシュトークンを送信します。リフレッシュトークンは、アクセストークンが期限切れになったときに新しいアクセストークンと交換するために使用できます。リフレッシュトークンは 24 時間有効です。したがって、24.5 時間後は新しいトークンための認証情報を再度送信する必要があります。

OAuth2 を使用して Management API にアクセスする

Management API にアクセスするには、API エンドポイントにリクエストを送信し、アクセストークンを含めます。この操作は、curl などのコマンドラインユーティリティ、Postman などのブラウザベースの UI、acurl のような Apigee ユーティリティなどの任意の HTTP クライアントで行うことができます。

acurl および curl をそれぞれ使用した Management API へのアクセスについては、以降のセクションで説明します。

acurl の使用

acurl を使用して Management API にアクセスするには、最初のリクエストにユーザーの認証情報を含める必要があります。Edge OAuth2 サービスは、アクセストークンとリフレッシュトークンで応答します。acurl はトークンをローカルに保存します。

その後のリクエストでは、acurl は ~/.sso-cli に保存されたトークンを使用するため、トークンが期限切れになるまで認証情報を再度含める必要はありません。

次の例は、「ahamilton-eval」という組織の詳細情報を取得する最初の acurl リクエストを示しています。

acurl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
      -u ahamilton@apigee.com
    Enter the password for user 'ahamilton@apigee.com'
    mypassw0rd
    {
      "createdAt" : 1491854501264,
      "createdBy" : "noreply_iops@apigee.com",
      "displayName" : "ahamilton",
      "environments" : [ "prod", "test" ],
      "lastModifiedAt" : 1491854501264,
      "lastModifiedBy" : "noreply_iops@apigee.com",
      "name" : "ahamilton",
      "properties" : {
        "property" : [ {
          "name" : "features.isSmbOrganization",
          "value" : "false"
        }, {
          "name" : "features.isCpsEnabled",
          "value" : "true"
        } ]
      },
      "type" : "trial"
    }

    acurl https://api.enterprise.apigee.com/v1/o/ahamilton-eval/apis/helloworld/revisions/1/policies

    [ "SOAP-Message-Validation-1", "Spike-Arrest-1", "XML-to-JSON-1" ]

この例では、組織の詳細情報を取得するだけでなく、「helloworld」という API プロキシ内のポリシーのリストを取得する 2 番目のリクエストも示しています。2 番目のリクエストでは、「組織（organization）」の短縮を表す「o」を URL に使用しています。

acurl は 2 番目のリクエストではアクセストークンを自動的に渡します（acurl が OAuth2 トークンを一度格納したら、ユーザー認証情報を渡す必要はありません）。トークンは ~/.sso-cli から取得されます。

詳細については、acurl を使用して Management API にアクセスするをご覧ください。

curl の使用

curl を使用して Management API にアクセスできます。これを行うには、まずアクセストークンとリフレッシュトークンを取得する必要があります。これらのトークンは、get_token や Management API などのユーティリティを使用して取得できます。

アクセストークンを正常に保存したら、次の例に示すように、Management API への呼び出しの Authorization ヘッダー内でそのトークンを渡します。

curl -v https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
      -H "Authorization: Bearer ACCESS_TOKEN"

トークンの有効期限

トークンの有効期間は次のとおりです。

アクセストークンの有効期間は 1,799 秒（約 30 分）
リフレッシュトークンの有効期間は 84,600 秒（約 24 時間）

アクセストークンが期限切れになったら、認証情報を再度送信しなくても、リフレッシュトークンを使用して新しいアクセストークンを取得できます。

アクセストークンを更新する方法は、使用しているツールによって異なります。

acurl: 何もする必要ありません。期限切れのアクセストークンが含まれているリクエストが送信されると、acurl はアクセストークンを自動的に更新します。
get_token: アクセストークンを更新するために get_token を呼び出します。
Management API: 以下を含むリクエストを送信します。
- リフレッシュトークン
- "refresh_token" に設定された grant_type フォームパラメータ

OAuth2 を使用して Management API にアクセスする

OAuth2 の仕組み（Apigee Management API を使用）

OAuth2 のフロー: 最初のリクエスト

OAuth2 のフロー: 後続のリクエスト

OAuth2 のフロー: アクセス トークンが期限切れになったとき

トークンを取得する

OAuth2 を使用して Management API にアクセスする

acurl の使用

curl の使用

トークンの有効期限

OAuth2 のフロー: アクセストークンが期限切れになったとき