自動タスクでの SAML の使用

Edge for Private Cloud v4.18.01

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

ただし、開発環境で、テストの自動化や継続的インテグレーション/継続的デプロイ（CI/CD）などの一般的な開発タスクの自動化をサポートしている場合があります。SAML が有効なときにこれらのタスクを自動化するには、OAuth2 トークンを取得および更新する際にパスコードをブラウザからコピーして貼り付けずに済む方法が必要となります。

Edge では、マシンユーザーを使用したトークンの自動生成がサポートされます。マシンユーザーは、パスコードを指定しなくても、OAuth2 トークンを取得できます。つまり、Edge Management API を使用することで、OAuth2 トークンを取得して更新するプロセスを完全に自動化できます。

マシンユーザーを作成する

apigee-ssoadminapi.sh ユーティリティを使用して、SAML 組織のマシンユーザーを作成します。詳細については、apigee-ssoadminapi.sh の使用をご覧ください。すべての組織で使用するマシンユーザーを 1 つだけ作成することも、組織ごとに別々のマシンユーザーを作成することもできます。

マシンユーザーは、ご使用の SAML ID プロバイダではなく、Edge データストアに作成されて格納されます。したがって、Edge UI と Edge Management API を使用してマシンユーザーを管理する必要はありません。

マシンユーザーを作成するとき、メールアドレスとパスワードを指定する必要があります。マシンユーザーを作成したら、それを 1 つ以上の組織に割り当てます。

マシンユーザーを作成するには:

1. 次の apigee-ssoadminapi.sh コマンドを使用して、マシンユーザーを作成します。
   > apigee-ssoadminapi.sh saml machineuser add --admin SSO_ADMIN_NAME --secret SSO_ADMIN_SECRET --host edge_sso_IP_or_DNS -u machine_user_email -p machine_user_password
   
   次のようにします。
   • SSO_ADMIN_NAME は、Edge SSO モジュールの構成に使用する構成ファイル内の SSO_ADMIN_NAME プロパティで定義された管理者のユーザー名です。デフォルトは ssoadmin です。
   • SSO_ADMIN_SECRET は、構成ファイルの SSO_ADMIN_SECRET プロパティで指定された管理者パスワードです。
     
     この例では、apigee-sso モジュールは --port にデフォルト値の 9099、--ssl に http を使用するため、--port と --ssl の値を省略できます。インストールでこれらのデフォルトを使用しない場合は、適切なものを指定します。
2. Edge UI にログインしてマシンユーザーのメールアドレスを組織に追加し、マシンユーザーに必要なロールを割り当てます。詳細については、グローバル ユーザーの追加をご覧ください。

マシンユーザー トークンを取得して更新する

Edge API を使用して、マシンユーザーの認証情報をパスコードの代わりに渡すことで、OAuth2 トークンを取得して更新します。

マシンユーザーの OAuth2 トークンを取得するには、次のようにします。

1. 初期アクセス トークンと更新トークンを生成するには、次の 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 /
   http://edge_sso_IP_DNS:9099/oauth/token -s /
   -d 'grant_type=password&username=m_user_email&password=m_user_password '
   この呼び出しによってアクセス トークンと更新トークンが画面に出力されます。後で使用するためにトークンを保存します。
2. アクセス トークンを Bearer ヘッダーとして Edge Management API 呼び出しに渡します。
   > curl -H "Authorization: Bearer access_token" http://ms_IP_DNS:8080/v1/organizations/orgName
   
   ここで、orgName はマシンユーザーを含む組織の名前です。
3. 後でアクセス トークンを更新するには、更新トークンを含む次の呼び出しを使用します。
   > 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 /
   http://edge_sso_IP_DNS:9099/oauth/token /
   -d 'grant_type=refresh_token&refresh_token=refreshToken'
   

Edge Management API を使用してマシンユーザーを作成する

apigee-ssoadminapi.sh ユーティリティを使用する代わりに、Edge Management API を使用してマシンユーザーを作成できます。マシンユーザーを作成するには:

1. 次の cURL コマンドを使用して、ssoadmin ユーザーのトークン（apigee-sso の管理者アカウントのユーザー名）を取得します。
   > curl "http://edge_sso_IP_DNS:9099/oauth/token" -i -X POST /
   -H 'Accept: application/json' / -H 'Content-Type: application/x-www-form-urlencoded' /
   -d "response_type=token" -d "grant_type=client_credentials" /
   --data-urlencode "client_secret=SSO_ADMIN_SECRET" /
   --data-urlencode "client_id=ssoadmin"
   
   ここで、SSO_ADMIN_SECRET は、構成ファイルの SSO_ADMIN_SECRET プロパティで指定されているように、apigee-sso をインストールするときに設定した管理者パスワードです。
   
   このコマンドは、次回の呼び出しに必要なトークンを表示します。
2. 次の cURL コマンドを使用して、前の手順で受け取ったトークンを渡してマシンユーザーを作成します。
   > curl "http://edge_sso_IP_DNS:9099/Users" -i -X POST /
   -H "Accept: application/json" -H "Content-Type: application/json" /
   -d '{"userName" : "machine_user_email", "name" : {"formatted":"DevOps", "familyName" : "last_name", "givenName" : "first_name"}, "emails" : [ {"value" : "machine_user_email", "primary" : true } ], "active" : true, "verified" : true, "password" : "machine_user_password" }' /
   -H "Authorization: Bearer token"
   
   マシンユーザーのパスワードは、後の手順で必要になります。
3. Edge UI にログインしてマシンユーザーのメールアドレスを組織に追加し、マシンユーザーに必要なロールを割り当てます。詳細については、グローバル ユーザーの追加をご覧ください。