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 では、パスコードとトークンを取得するときに次の情報を含める必要があります。

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

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

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

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

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

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

  1. 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
  2. ブラウザで次の URL にアクセスしてワンタイム パスコードを取得します。
    https://zoneName.login.apigee.com/passcode

    たとえば、ゾーンが「acme」という名であれば、次の URL にアクセスします。

    https://acme.login.apigee.com/passcode

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

    この URL からワンタイム パスコードが返されます。このパスコードは、この URL を更新して新しいパスコードを取得するまで有効です。また、get_token を指定してこのパスコードを使用すると、アクセス トークンを生成できます。

  3. 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 に書き込まれます。

  4. 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 を使用してアクセス トークンを取得する手順は次のとおりです。

  1. ブラウザで次の URL にアクセスしてワンタイム パスコードを取得します。
    https://zoneName.login.apigee.com/passcode

    たとえば、ゾーンが「acme」という名であれば、次の URL にアクセスします。

    https://acme.login.apigee.com/passcode

    パスコードは基本的に、トークンを取得するための認証情報の働きをします。

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

    この URL からワンタイム パスコードが返されます。このパスコードは、この URL を更新して新しいパスコードを取得するまで有効です。また、get_token を指定してこのパスコードを使用すると、アクセス トークンを生成できます。

  2. 次の例のように、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 です。

    この呼び出しによってアクセス トークンとリフレッシュ トークンが画面に出力されます。

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

  1. ブラウザで次の URL にアクセスしてワンタイム パスコードを取得します。
    https://zoneName.login.apigee.com/passcode

    たとえば、ゾーンが「acme」という名であれば、次の URL にアクセスします。

    https://acme.login.apigee.com/passcode

    パスコードは基本的に、トークンを取得するための認証情報の働きをします。

  2. 次の例のように、リクエストを 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 です。

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

curl や、使いやすい Apigee のユーティリティである acurl といったツールを使用して、Management API にアクセスできます。

curl を使用する場合、Management API を呼び出し、アクセス トークンを Authorization: Bearer ヘッダーに入れて渡します。次の例をご覧ください。

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

acurl を使用する場合は、Authorization を呼び出してトークンをローカルに保存していれば、get_token ヘッダーを指定する必要はありません。次に例を示します。

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

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

API を呼び出すための上記以外の方法(トークンを最新に保つ方法を含む)については、OAuth2 を使用して Management API にアクセスするをご覧ください。