トークン生成プロセスの自動化

SAML を Edge API で使用しているとき、OAuth2 アクセスを取得して SAML アサーションからのトークンをリフレッシュするために使用するプロセスを、パスコード フローと呼びます。パスコード フローでは、ブラウザを使用してワンタイム パスコードを取得し、それを使用して OAuth2 トークンを取得します。

ただし、ご使用の環境が、テストの自動化や継続的インテグレーション / 継続的デプロイ(CI / CD)といった一般的な開発タスクの自動化をサポートしている場合があります。SAML が有効なときにこれらのタスクを自動化するには、パスコードをブラウザからコピーして貼り付けることなく OAuth2 トークンを取得してリフレッシュできる方法が必要になります。

概要

Edge がサポートしている自動的トークン生成には 2 つの方法があります。どちらがご自分の環境に適しているかお選びください。

  • マシンユーザー:

    Edge は Edge SAML ゾーンでマシンユーザーをサポートしています。マシンユーザーは、パスコードを指定しなくても、OAuth2 トークンを取得できます。つまり、Edge Management API を使用することで、OAuth2 トークンを取得およびリフレッシュするプロセスを完全に自動化できます。

  • 長いトークン:

    長い OAuth2 アクセス トークンは、レギュラー アクセス トークンと同じく 1 時間有効です。しかし、リフレッシュ トークンが有効なのは、12 時間でなく、30 日間です。

    長いトークンは、レギュラー トークンとは別の OAuth クライアント タイプを使用します。つまり、長いトークン クライアント使用するために get_token を構成した後で、それを使用して OAuth2 トークンの取得やリフレッシュをしなければならないというわけです。一般に、この構成を行うのは自動化タスクを実行するマシンだけであるため、通常のユーザーは長いトークンを作成できません。

マシンユーザー

リクエスト時に、Apigee が SAML 組織のマシンユーザーを自動的に作成します。SAML を使用しない組織にはマシンユーザーを作成できません。

Apigee には、すべての組織で使用するマシンユーザーをひとつだけ作成させることも、組織ごとに別々のマシンユーザーを作成させることもできます。

マシンユーザーは、ご使用の SAML ID プロバイダではなく、Edge データストアに作成されて格納されます。したがって、マシンユーザーを管理する必要はありません。後で他のマシンユーザーを追加したり既存のマシンユーザーを削除したりしたい場合は、Apigee サポートに連絡する必要があります。

Apigee は新しいマシンユーザーを作成すると、それにメールアドレスとデフォルトのパスワードを割り当てます。マシンユーザーのメールアドレスは、以下の形式になります。

  • 特定の組織にマシンユーザーを作成する場合は machine_orgname@yourdomain.com
  • ゾーン全体にマシンユーザーをひとつだけ作成する場合は machine_zonename@yourdomain.com

マシンユーザーのメールアドレスはメールには使用しないため、自由に決めてかまいません。これらのアドレスには、特別な意味やプログラム的な意図はありません。マシンユーザーの範囲をわかりやすくするためだけに、この命名規則を使用しています。

マシンユーザーのパスワードをリセットする

Apigee によりマシンユーザーが作成された後で、デフォルトのパスワードを再設定する必要があります。その後で、マシンユーザーの OAuth2 トークンを取得できます。

マシンユーザーのパスワードを再設定するには、以下の手順を実行します。

  1. Apigee サポートに、特定の組織またはゾーンのマシンユーザーを作成するリクエストを送ります。

    Apigee からマシンユーザーのメールアドレスとパスワードが送られてきます。

  2. 以下の操作を実施してマシンユーザーのアクセス権限を更新します。
    1. Edge UI にログインします。
    2. マシンユーザーを組織に追加します。
    3. 必要な役割をマシンユーザーに割り当てます。

    詳細については、グローバル ユーザーを追加するをご覧ください。

  3. SAML トークン エンドポイントを呼び出して、マシンユーザーの JSON ウェブトークン(JWT)を取得します。以下に例を示します。
    curl -s -X POST https://zoneName.login.apigee.com/oauth/token \
        -H "Content-Type: application/x-www-form-urlencoded;charset=utf-8" \
        -H "accept: application/json;charset=utf-8" \
        -H "Authorization: Basic ZWRnZWNsaTplZGdlY2xpc2VjcmV0" \
        -d "grant_type=password&username=machine_user_email&password=machine_user_password"

    zoneName が SAML ゾーンで、machine_user_emailmachine_user_password は Apigee から送られてきたマシンユーザーのメールアドレスとパスワードです。承認のために、予約済みの OAuth2 クライアント資格情報 ZWRnZWNsaTplZGdlY2xpc2VjcmV0Authorization ヘッダーで渡します。

    SAML トークン エンドポイントから返された JWT トークンは OAuth2 アクセス トークンを含んでおり、以下の形式となります。

    {
          "access_token":"eyJhbGc...Au91CzslYg",
          "expires_in":43199,
          "scope":"scim.emails.read scim.me openid password.write approvals.me scim.ids.read oauth.approvals",
          "jti":"6f27ffac-3cde-4eb9-8341-5855333bbbf9"
        }
  4. JWT トークンをデコードして、マシンユーザーの user_id を取得します。デコードを行うために使用できるユーティリティが多数あります。たとえば、jwt を https://www.npmjs.com/package/jwt-cli からインストールできます。
  5. 以下の API 呼び出しを使用してマシンユーザーのパスワードを変更します。
    curl -s -X PUT https://zoneName.login.apigee.com/Users/user_id/password \
          -H "Content-Type:application/json" \
          -H "Accept:application/json" \
          -H "Authorization: Bearer ACCESS_TOKEN_FROM_JWT" \
          -d '{ "oldPassword" : "old_password", "password" : "new_password"}'

    ここで user_ID_from_JWT は JWT トークンから抽出した ID で、ACCESS_TOKEN_FROM_JWT は JWT から抽出したアクセス トークンです。

    この呼び出しは、以下の形式のメッセージを返します。

    {
        "status":"ok",
        "message":"password updated"
        }

マシンユーザーのパスワードを変更したら、マシンユーザーの認証情報をパスコードの代わりに渡すことで、Edge API を使用して OAuth2 トークンを取得してリフレッシュできます。

マシンユーザーの OAuth2 トークンを取得する

マシンユーザーの OAuth2 トークンを取得する手順は次のとおりです。

  1. 次の例で示すように SAML トークン エンドポイントを呼び出して、初期アクセス トークンとリフレッシュ トークンを生成します。
    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&username=machine_user_email&password=new_password'

    承認のために、予約済みの OAuth2 クライアント資格情報 ZWRnZWNsaTplZGdlY2xpc2VjcmV0Authorization ヘッダーで渡します。呼び出しはアクセス トークンとリフレッシュ トークンを stdout に出力します。

  2. アクセス トークンを Edge Management API 呼び出しに Bearer ヘッダーとして渡します。
    curl -H "Authorization: Bearer ACCESS_TOKEN" \
          https://api.enterprise.apigee.com/v1/organizations/orgName
  3. アクセス トークンの期限が切れたら、リフレッシュするため、次の例で示すように、リフレッシュ トークンを SAML トークン エンドポイントに送信します。
    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'

長いトークン

SAML アサーションから長い OAuth2 トークンを作成した場合、OAuth2 アクセス トークンは 1 時間有効ですが、リフレッシュ トークンは、通常の 12 時間でなく、30 日間有効となります。

アカウントに対して長いトークンを有効にする

長いトークンは、使用する前に、アカウントに対して有効にしておく必要があります。

長いトークンを有効にするには、次の手順を実行します。

  1. Apigee サポートに連絡して、アカウントに対して長いトークンを有効にします。

    Apigee から OAuth2 クライアント ID とシークレットが、次の形式で送られてきます。

    clientcli:clientclisecret
  2. clientcli:clientclisecret を Base64 エンコードします。これは、base64 などのユーティリティで行います。
  3. Base64 エンコードした clientcli:clientclisecret を使用して、長いトークンを生成します。

長いリフレッシュ トークンを使用する

アクセス トークンを作成およびリフレッシュするために使用するプロセスは、上で示したように Edge Management API のトークンを作成するために使用するプロセスと同じですが、以下の違いがあります。

  • get_token を使用してアクセス トークンとリフレッシュ トークンを取得する場合は、長いトークン クライアントに CLIENT_AUTH 環境変数を設定する必要があります。
    export CLIENT_AUTH=Base64EncodedClientIDAndSecret
  • Management API を使用してアクセス トークンとリフレッシュ トークンを取得すると、OAuth2 トークンを生成またはリフレッシュするときに Base64 エンコードしたクライアント ID とシークレットを基本認証ヘッダーとして渡す必要があります。
    -H "Authorization: Basic Base64EncodedClientIDAndSecret"

長いリフレッシュ トークンを get_token で取得して使用する手順は次のとおりです。

  1. Apigee から受け取ったクライアント ID とシークレットを Base64 エンコードします。
  2. get_token が使用する SSO_LOGIN_URL を、次のように設定します。
    export SSO_LOGIN_URL=https://zoneName.login.apigee.com
  3. Base64 エンコードしたクライアント ID とシークレットに CLIENT_AUTH 環境変数を設定します。
    export CLIENT_AUTH=amVua4guc2NsaTpqZW5raW5zY2xpc2VjcmV0
  4. ブラウザで次の URL にアクセスしてワンタイム パスコードを取得します。
    https://zoneName.login.apigee.com/passcode
  5. get_token を呼び出して OAuth2 アクセス トークンを取得します。
    get_token

    前の手順で取得したワンタイム パスコードを入力するよう求められます。

  6. パスコードを入力します。

    get_token ユーティリティは OAuth2 アクセス トークンを取得し、stdout に出力して、このトークンと長いリフレッシュ トークンを ~/.sso-cli に書き込みます。

  7. アクセス トークンを Edge Management API 呼び出しに Bearer ヘッダーとして渡します。たとえば、次のようになります。
    curl -H "Authorization: Bearer ACCESS_TOKEN" \
          https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval

以下の API 呼び出しを使用して、初期アクセス トークンとリフレッシュ トークンを生成できます。

curl -H "Content-Type: application/x-www-form-urlencoded;charset=utf-8" \
      -H "accept: application/json;charset=utf-8" \
      -H "Authorization: Basic amVua4guc2NsaTpqZW5raW5zY2xpc2VjcmV0" -X POST \
      https://zoneName.login.apigee.com/oauth/token -s \
      -d 'grant_type=password&response_type=token&passcode=passcode'

Base64 エンコードしたクライアント ID とシークレットの文字列を Basic ヘッダーとして渡します。呼び出しはアクセス トークンとリフレッシュ トークンを stdout に出力します。

後でアクセス トークンをリフレッシュするには、前の呼び出しから生成されたリフレッシュ トークンを含む以下の呼び出しを使用します。

curl -H "Content-Type:application/x-www-form-urlencoded;charset=utf-8" \
      -H "Accept: application/json;charset=utf-8" \
      -H "Authorization: Basic amVua4guc2NsaTpqZW5raW5zY2xpc2VjcmV0" -X POST \
      https://zoneName.login.apigee.com/oauth/token \
      -d 'grant_type=refresh_token&refresh_token=REFRESH_TOKEN'