Edge 管理 API での SAML の使用

Edge for Private Cloud v4.18.05

Basic 認証は、Edge 管理 API を呼び出す際の認証方法の 1 つです。たとえば、組織に関する情報にアクセスするには、次の cURL リクエストを Edge 管理 API に送信します。

curl -u userName:pWord https://ms_IP_DNS:8080/v1/organizations/orgName

この例では、cURL -u オプションを使用して Basic 認証の認証情報を渡しています。別の方法として、OAuth2 トークンを Bearer ヘッダーに含めて渡し、Edge 管理 API を呼び出すこともできます。次に例を示します。

curl -H "Authorization: Bearer access_token" https://ms_IP_DNS:8080/v1/organizations/orgName

SAML を有効にした後は、オプションで Basic 認証を無効にできます。Basic 認証を無効にすると、Basic 認証をサポートする Edge 管理 API 呼び出しに依存するすべてのスクリプト(Maven スクリプト、シェル スクリプト、apigeetool など)は機能しなくなります。Basic 認証を使用して Bearer ヘッダーで OAuth2 アクセス トークンを渡す API 呼び出しとスクリプトをすべて更新する必要があります。

get_token を使用してトークンを取得、更新する

get_token ユーティリティは、Basic 認証の認証情報とパスコードを、OAuth2 アクセス トークンおよびリフレッシュ トークンと交換します。get_token ユーティリティは認証情報を受け入れて、有効なアクセス トークンを出力します。トークンを更新できる場合は、更新して出力します。リフレッシュ トークンが期限切れになると、ユーザー認証情報の入力を求めるプロンプトを出します。

get_token ユーティリティはトークンをディスク上に保管して、必要に応じてすぐに使用できるようにします。また、有効なアクセス トークンを stdout に出力します。そこから Postman を使用することも、トークンを環境変数に埋め込んで curl で使用することもできます。

get_token を使用して OAuth2 アクセス トークンを取得し、Edge 管理 API を呼び出す方法を説明します。

  1. sso-cli バンドルをダウンロードします。
    curl http://edge_sso_IP_DNS:9099/resources/scripts/sso-cli/ssocli-bundle.zip -o "ssocli-bundle.zip"

    edge_sso_IP_DNS は、Edge SSO モジュールをホストしているマシンの IP アドレスまたは DNS 名です。Edge SSO 上で TLS を構成した場合は、https と正しい TLS ポート番号を使用してください。

  2. ssocli-bundle.zip バンドルを解凍します。
    unzip ssocli-bundle.zip
  3. get_token/usr/local/bin 内にインストールします。
    > ./install 別の場所を指定するには、-b オプションを使用します(> ./install -b path)。
  4. SSO_LOGIN_URL 環境変数を、次の形式のログイン URL に設定します。
    export SSO_LOGIN_URL="http://edge_sso_IP_DNS:9099"

    edge_sso_IP_DNS は、Edge SSO モジュールをホストしているマシンの IP アドレスまたは DNS 名です。Edge SSO 上で TLS を構成した場合は、https と正しい TLS ポート番号を使用してください。
  5. ブラウザで、次の URL にアクセスしてワンタイム パスコードを取得します。
    http://edge_sso_IP_DNS:9099/passcode

    Edge SSO 上で TLS を構成した場合は、https と正しい TLS ポート番号を使用してください。

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

    この URL からワンタイム パスコードが返されます。このパスコードは、この URL を更新して新しいパスコードを取得するまで有効です。また、get_token でこのパスコードを使用すると、アクセス トークンを生成できます。
  6. 次のように get_token を呼び出して OAuth2 アクセス トークンを取得します。
    > get_token -u emailAddress

    emailAddress は、Edge ユーザーのメールアドレスです。次のように、ステップ 3 で取得したワンタイム パスコードを入力するよう求められます。
    One Time Code ( Get one at https://edge_sso_IP.com/passcode )
    SAML が有効にされている場合はパスコードを入力します。そうでなければ、Enter キーを押します。


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

    コマンドラインでパスコードを入力するには、次の形式の get_token コマンドを使用することもできます。
    > get_token -u emailAddress -p passcode
  7. アクセス トークンを Bearer ヘッダーとして Edge 管理 API 呼び出しに渡します。
    > curl -H "Authorization: Bearer access_token" https://ms_IP:8080/v1/organizations/orgName

    初めて新しいアクセス トークンを取得した場合は、次に示すように、単一のコマンドでそのアクセス トークンを API 呼び出しに渡すことができます。
    > header=`get_token` && curl -H "Authorization: Bearer $header" https://ms_IP:8080/v1/o/orgName

    この形式のコマンドを使用する場合、リフレッシュ トークンが期限切れになるまで、アクセス トークンが期限切れになると自動的に更新されます。

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

管理 API を使用してトークンを取得、更新する

Edge 管理 API を使用してトークンを取得、更新する方法については、Apigee Edge 管理 API での OAuth2 セキュリティの使用で説明しています。Edge API 呼び出しを使用して、SAML アサーションからトークンを生成することもできます。

その場合、Apigee Edge 管理 API での OAuth2 セキュリティの使用で説明している API 呼び出しとの唯一の違いは、呼び出しの URL でゾーン名を参照する必要があるという点です。さらに、初期アクセス トークンを生成する場合は、上記の手順のステップ 3 で示されているように、パスコードを含める必要があります。

たとえば、初期アクセス トークンとリフレッシュ トークンを生成するには、次の 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://edge_sso_IP_DNS:9099/oauth/token -s /
      -d 'grant_type=password&response_type=token&passcode=passcode'
    

認可のため、用意していた OAuth2 クライアント資格情報を Authorization ヘッダーに含めて渡します。この呼び出しによってアクセス トークンとリフレッシュ トークンが画面に出力されます。

後でアクセス トークンをリフレッシュするには、リフレッシュ トークンを含めた以下の呼び出しを使用します。

    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://edge_sso_IP_DNS:9099/oauth/token /
    -d 'grant_type=refresh_token&refresh_token=refreshToken'