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

SAML ではシングルサインオン（SSO）環境がサポートされます。Edge で SAML を使用することで、Edge UI と API での SSO をサポートできるだけでなく、お客様が提供する他のサービスで SAML がサポートされていれば、それらのサービスでも SSO を使用できます。

前提条件: SAML を使用して Management API にアクセスするには、まず 1 つ以上の組織で SAML を有効にする必要があります。

SAML と OAuth2 の違い

SAML を設定すると、SAML を使用して OAuth2 を使用する場合と同様の方法で Management API にアクセスできます。Management API を呼び出すときに、リクエストに OAuth2 アクセストークンを含めます。

Management API にアクセスするときの SAML と OAuth2 の大きな違いは、トークンの取得方法です。SAML では、パスコードとトークンを取得するときに次の情報を含める必要があります。

ゾーン: トークンを取得する際にゾーン名を参照します。
初期パスコード: （初期アクセストークンの取得時に）ワンタイムパスコードを含めます。

Management API 呼び出し用のエンドポイントは、SAML と OAuth2 のどちらも同じです。

SAML でアクセストークンを取得する場合は、get_token ユーティリティと Management API のどちらかを使用できます。この 2 つのアプローチについては、この後のセクションでそれぞれ説明します。

get_token を使用してアクセストークンを取得する

get_token ユーティリティを使用すると、OAuth2 アクセス用の認証情報と SAML で使用するリフレッシュトークンを交換できます。

注

このセクションの例では、curl を使用して API リクエストを行います。Apigee のユーティリティである acurl を使用することも検討してください。このユーティリティは curl をラップするための使いやすいラッパーです。 acurl はアクセストークンを渡し、トークンの有効期限が切れたときにリフレッシュします。

get_token を使用してアクセストークンを取得する手順は次のとおりです。

SSO_LOGIN_URL 環境変数をログイン URL に設定します。このログイン URL は次の形式で指定します。
```
https://zoneName.login.apigee.com
```
たとえば、ゾーンが「acme」という名前であれば、次の例のように SSO_LOGIN_URL を「https://acme.login.apigee.net」に設定します。
```
export SSO_LOGIN_URL=https://acme.login.apigee.com
```
ブラウザで次の URL にアクセスしてワンタイムパスコードを取得します。
```
https://zoneName.login.apigee.com/passcode
```
たとえば、ゾーンが「acme」という名であれば、次の URL にアクセスします。
```
https://acme.login.apigee.com/passcode
```
現在 ID プロバイダによってログインしていない場合は、ログインするように求められます。

この URL からワンタイムパスコードが返されます。このパスコードは、この URL を更新して新しいパスコードを取得するまで有効です。また、get_token を指定してこのパスコードを使用すると、アクセストークンを生成できます。
get_token を呼び出して OAuth2 アクセストークンを取得します。
```
get_token
```
前の手順で取得したワンタイムパスコードの入力が求められます。
```
One Time Code ( Get one at https://acme.login.apigee.com/passcode )
    Enter the passcode if SAML is enabled or press ENTER:
```
パスコードを入力してください。get_token ユーティリティによって OAuth2 アクセストークンが取得され、そのトークンが stdout に出力され、アクセストークンとリフレッシュトークンが ~/.sso-cli に書き込まれます。
Management API を呼び出し、アクセストークンを Authorization: Bearer ヘッダーに入れて渡します。次の例をご覧ください。
```
curl -H "Authorization: Bearer ACCESS_TOKEN"
      https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval
```
~/.sso-cli のアクセストークンの値を使用しています。

この例では、特定の組織に関する詳細を取得します。Management API エンドポイントの一覧については、Apigee Management API リファレンスをご覧ください。

アクセストークンが期限切れになったら、get_token をもう一度呼び出して新しいアクセストークンを取得します。リフレッシュトークンが期限切れになるまでは、新しいパスコードの入力は求められません。

リフレッシュトークンが期限切れになると、get_token によって新しいパスコードの入力が求められます。先に新しいパスコードを生成してからでないと、新しい OAuth アクセストークンは生成できません。

Management API を使用してアクセストークンを取得する

Management API を使用して、SAML で使用するアクセストークンを取得できます。Management API の認証を受けるには、初期リクエストでパスコードを使用してアクセストークンを取得し、再びリフレッシュトークンを取得します。

Management API を使用してアクセストークンを取得する手順は次のとおりです。

ブラウザで次の URL にアクセスしてワンタイムパスコードを取得します。
```
https://zoneName.login.apigee.com/passcode
```
たとえば、ゾーンが「acme」という名であれば、次の URL にアクセスします。
```
https://acme.login.apigee.com/passcode
```
パスコードは基本的に、トークンを取得するための認証情報の働きをします。

現在 ID プロバイダによってログインしていない場合は、ログインするように求められます。

この URL からワンタイムパスコードが返されます。このパスコードは、この URL を更新して新しいパスコードを取得するまで有効です。また、get_token を指定してこのパスコードを使用すると、アクセストークンを生成できます。
次の例のように、Management API にリクエストを送信します。
```
curl -H "Content-Type: application/x-www-form-urlencoded;charset=utf-8" \
          -H "accept: application/json;charset=utf-8" \
          -H "Authorization: Basic ZWRnZWNsaTplZGdlY2xpc2VjcmV0" -X POST \
          https://zoneName.login.apigee.com/oauth/token -s \
          -d 'grant_type=password&response_type=token&passcode=passcode'
```
パスコードは認可を受けるための認証情報の働きをします。

ここで
- リクエスト本文には次の情報が含まれます。
  - grant_type は「password」です。
  - response_type は「token」です。
- passcode は、前のステップで取得したパスコードです。
- Authorization ヘッダーは「Basic ZWRnZWNsaTplZGdlY2xpc2VjcmV0」です（この値をこのまま使用してください）。
- リクエストタイプは POST です。
この呼び出しによってアクセストークンとリフレッシュトークンが画面に出力されます。

アクセストークンをリフレッシュする手順は次のとおりです。

ブラウザで次の URL にアクセスしてワンタイムパスコードを取得します。
```
https://zoneName.login.apigee.com/passcode
```
たとえば、ゾーンが「acme」という名であれば、次の URL にアクセスします。
```
https://acme.login.apigee.com/passcode
```
パスコードは基本的に、トークンを取得するための認証情報の働きをします。
次の例のように、リクエストを https://zoneName.login.apigee.com/oauth/token に送信します。
```
curl -H "Content-Type:application/x-www-form-urlencoded;charset=utf-8" \
      -H "Accept: application/json;charset=utf-8" \
      -H "Authorization: Basic ZWRnZWNsaTplZGdlY2xpc2VjcmV0" -X POST \
      https://zoneName.login.apigee.com/oauth/token \
      -d 'grant_type=refresh_token&refresh_token=REFRESH_TOKEN'
```
ここで
- リクエスト本文には次の情報が含まれます。
  - grant_type は「refresh_token」です。
  - refresh_token はリフレッシュトークンの値です（get_token を使用した場合、リフレッシュトークンは ~/.sso-cli にあります）。
- Authorization ヘッダーは「Basic ZWRnZWNsaTplZGdlY2xpc2VjcmV0」です（この値をこのまま使用してください）。
- リクエストタイプは POST です。