Edge Management API で外部 IDP を使用する

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

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

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

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

認証のために外部 IDP を有効にした後は、必要に応じて Basic 認証を無効にできます。Basic 認証を無効にすると、Basic 認証をサポートする Edge Management API 呼び出しに依存するすべてのスクリプト（Maven、shell、apigeetool など）は機能しなくなります。そのため、Basic 認証を使用して Bearer ヘッダーで OAuth2 アクセス トークンを渡す API 呼び出しとスクリプトをすべて更新する必要があります。

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

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

get_token ユーティリティによりトークンはディスクに保存され、必要なときにすぐに使用できます。また、有効なアクセス トークンを stdout に出力します。そこから Postman などのブラウザ拡張機能を使用することも、トークンを環境変数に埋め込んで curl で使用することもできます。

OAuth2 アクセス トークンを取得して Edge Management 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 は Apigee SSO モジュールをホストするマシンの IP アドレスまたは DNS 名です。Apigee SSO で TLS を構成した場合は、https と正しい TLS ポート番号を使用します。

  2. 次の例のように、ssocli-bundle.zip バンドルを解凍します。 
    unzip ssocli-bundle.zip
  3. 次の例のように、/usr/local/bin に get_token をインストールします。 
    ./install -b path

    -b オプションは別の場所を指定します。

  4. SSO_LOGIN_URL 環境変数を、次の形式のログイン URL に設定します。
    export SSO_LOGIN_URL="http://edge_sso_IP_DNS:9099"

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

  5. （SAML のみ）ブラウザで次の URL にアクセスしてワンタイム パスコードを取得します。
    http://edge_sso_IP_DNS:9099/passcode

    Apigee SSO で TLS を構成した場合は、https と正しい TLS ポート番号を使用します。

    このリクエストは、その URL を更新して新しいパスコードを取得するか、get_token でパスコードを使用してアクセス トークンを生成するまで、有効なワンタイム パスコードを返します。

    パスコードを使用できるのは、SAML IDP で認証する場合のみです。LDAP IDP での認証には使用できません。

  6. 次の例のように、get_token を呼び出して OAuth2 アクセス トークンを取得します。 
    get_token -u emailAddress

    ここで emailAddress は、Edge ユーザーのメールアドレスです。

    （SAML のみ）次の例のように、メールアドレスに加えて、コマンドラインでもパスコードを入力します。

    get_token -u emailAddress -p passcode

    get_token ユーティリティが OAuth2 アクセス トークンを取得して画面に出力し、更新トークンとともに ~/.sso-cli に書き込みます。

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

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

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

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

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

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

認可のために、予約済みの OAuth2 クライアント認証情報を Authorization ヘッダーで渡します。この呼び出しによってアクセス トークンと更新トークンが画面に出力されます。

アクセス トークンを取得する

（LDAP）初期アクセス トークンと更新トークンを生成するには、次の 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'

（SAML）初期アクセス トークンと更新トークンを生成するには、次の 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'

SAML IDP を使用した認証には一時的なパスコードが必要ですが、LDAP IDP の認証には不要です。

アクセス トークンを更新する

後でアクセス トークンを更新するには、更新トークンを含む次の呼び出しを使用します。

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'