Mit SAML auf die Edge API zugreifen

Sie lesen gerade die Dokumentation zu Apigee Edge.
Zur Dokumentation zu Apigee X. info

SAML unterstützt eine Umgebung für die Einmalanmeldung (Single Sign-On, SSO). Wenn Sie SAML mit Edge verwenden, können Sie SSO für die Edge-Benutzeroberfläche und die Edge API sowie für alle anderen von Ihnen bereitgestellten Dienste unterstützen, die ebenfalls SAML unterstützen.

Voraussetzung: Sie müssen SAML aktivieren für mindestens eine Organisation, bevor Sie damit auf die Edge API zugreifen können.

Unterschiede zwischen SAML und OAuth2

Nachdem SAML eingerichtet wurde, ist die Verwendung sehr ähnlich wie die Verwendung von OAuth2 für den Zugriff auf die Edge API. Wenn Sie die Edge API aufrufen, fügen Sie Ihrer Anfrage ein OAuth2-Zugriffstoken in Ihrer Anfrage hinzu.

Der Hauptunterschied zwischen SAML und OAuth2 beim Zugriff auf die Edge API besteht darin, wie Sie Tokens erhalten. Bei SAML müssen Sie beim Abrufen Ihres Tokenpaars Folgendes angeben:

  1. Zonen:Nutzer von Edge für die Public Cloud müssen beim Abrufen von Tokens ihren Zonennamen angeben.
  2. Sicherheitscode: Fügen Sie beim Anfordern eines Zugriffstoken-/Aktualisierungstoken Paars einen Einmal-Sicherheitscode hinzu.

SAML verwendet dieselben Endpunkte für den Edge OAuth2-Dienst, wobei der entsprechende Zonennamen hinzugefügt wird.

Zum Abrufen von Zugriffstokens mit SAML können Sie eine der folgenden Methoden verwenden, die in diesem Abschnitt beschrieben werden:

Außerdem können Sie den Prozess zur Tokengenerierung für Maschinenutzer automatisieren, wie unter Prozess zur Tokengenerierung automatisieren beschrieben.

Zugriffstokens mit „get_token“ abrufen

Mit dem Dienstprogramm get_token können Sie Ihre Anmeldedaten gegen OAuth2-Zugriffs- und Aktualisierungstokens austauschen, die Sie mit SAML verwenden.

So rufen Sie ein Zugriffstoken mit „get_token“ ab :

  1. Legen Sie die Umgebungsvariable SSO_LOGIN_URL auf Ihre Anmelde-URL fest. Die Anmelde-URL hat das folgende Format: 
    https://zoneName.login.apigee.com

    Wenn Sie beispielsweise eine Zone mit dem Namen „acme“ haben, legen Sie SSO_LOGIN_URL auf „https://acme.login.apigee.com“ fest, wie im folgenden Beispiel gezeigt:

    export SSO_LOGIN_URL=https://acme.login.apigee.com
  2. Rufen Sie get_token auf, um das OAuth2-Zugriffstoken abzurufen: 
    get_token -u me@example.com

    Sie werden aufgefordert, die angezeigte URL aufzurufen, um einen Einmal-Sicherheitscode zu erhalten:

    Get passcode from https://acme.login.apigee.com/passcode
[Note:  Passcode can be used only time time and expires] Input passcode (no spaces) and then press ENTER:

    Wenn Sie sich vor Kurzem nicht über Ihren Identitätsanbieter angemeldet haben, werden Sie aufgefordert, sich anzumelden.

    Diese URL gibt einen Einmal-Sicherheitscode zurück, der so lange gültig ist, bis Sie die URL aktualisieren, um einen neuen Sicherheitscode zu erhalten, oder Sie den Sicherheitscode mit get_token verwenden, um ein Zugriffstoken zu generieren. Beispiel:

  3. Geben Sie den Sicherheitscode ein. Das Dienstprogramm get_token ruft die OAuth2-Tokens ab, gibt das Zugriffstoken in stdout aus und schreibt die Zugriffs- und Aktualisierungstokens in ~/.sso-cli.

  4. Rufen Sie die Edge API auf und übergeben Sie das Zugriffstoken im Authorization: Bearer Header, wie im folgenden Beispiel gezeigt: 
    curl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
  -H "Authorization: Bearer ACCESS_TOKEN"

    Der Wert des Zugriffstokens kann aus stdout kopiert werden.

    In diesem Beispiel werden Details zur angegebenen Organisation abgerufen. Eine vollständige Liste der Management API-Endpunkte finden Sie in der Apigee Edge API-Referenz.

Wenn Ihr Zugriffstoken abläuft, können Sie get_token noch einmal aufrufen, um ein neues Zugriffstoken zu erhalten. Beispiel:

get_token -u me@example.com

Sie werden erst dann nach einem neuen Sicherheitscode gefragt, wenn das Aktualisierungstoken abläuft.

Wenn das Aktualisierungstoken abläuft, fordert get_token Sie auf, einen neuen Sicherheitscode einzugeben. Sie müssen einen neuen Sicherheitscode generieren, bevor Sie ein neues OAuth2-Zugriffstoken generieren können.

Zugriffstokens mit dem Edge OAuth2-Dienst abrufen

Sie können den Edge OAuth2-Dienst verwenden, um Zugriffstokens abzurufen, die Sie mit SAML verwenden. Zur Authentifizierung bei der Edge API verwenden Sie einen Sicherheitscode in Ihrer ersten Anfrage, um ein Zugriffs-/Aktualisierungstoken-Paar zu erhalten, und noch einmal, um ein neues Tokenpaar zu erhalten.

So rufen Sie ein Tokenpaar mit der Edge API ab:

  1. Rufen Sie in einem Browser die folgende URL auf, um einen Einmal-Sicherheitscode zu erhalten: 
    https://zoneName.login.apigee.com/passcode

    Wenn Sie beispielsweise eine Zone mit dem Namen „acme“ haben, rufen Sie die folgende URL auf:

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

    Wenn Sie sich vor Kurzem nicht über Ihren Identitätsanbieter angemeldet haben, werden Sie aufgefordert, sich anzumelden.

    Diese URL gibt einen Einmal-Sicherheitscode zurück, der als Ihre Anmeldedaten zum Abrufen von Tokens dient und so lange gültig ist, bis Sie die URL aktualisieren, um einen neuen Sicherheitscode zu erhalten. Alternativ können Sie den Sicherheitscode mit get_token verwenden, um ein Zugriffstoken zu generieren. Beispiel:

  2. Senden Sie eine Anfrage an die Edge API, wie im folgenden Beispiel gezeigt: 
    curl https://zoneName.login.apigee.com/oauth/token \
      -s \
      -H "Accept: application/json" \
      -d 'grant_type=password&response_type=token&passcode=passcode'

    Der passcode dient als Ihre Anmeldedaten für die Autorisierung.

    Wobei:

    • Der Authorization Header ist "Basic ZWRnZWNsaTplZGdlY2xpc2VjcmV0" (verwenden Sie genau diesen Wert).
    • Der Anfragetyp ist POST.
    • Der Text der Anfrage enthält Folgendes:
      • grant_type ist „password“.
      • response_type ist „token“.
      • passcode, wobei „passcode“ der Sicherheitscode ist, der im vorherigen Schritt zurückgegeben wurde.

    Der Aufruf gibt die Zugriffs- und Aktualisierungstokens auf dem Bildschirm aus.

So aktualisieren Sie Ihr Zugriffstoken :

Senden Sie eine Anfrage an https://zoneName.login.apigee.com/oauth/token, wie im folgenden Beispiel gezeigt:

curl https://zoneName.login.apigee.com/oauth/token \
      -d 'grant_type=refresh_token&refresh_token=REFRESH_TOKEN'

Wobei:

  • Der Text der Anfrage enthält Folgendes:
    • grant_type ist „refresh_token“.
    • refresh_token ist der Wert des Aktualisierungstokens.
  • Der Authorization Header ist "Basic ZWRnZWNsaTplZGdlY2xpc2VjcmV0" (verwenden Sie genau diesen Wert).
  • Der Anfragetyp ist POST.

Mit SAML auf die Edge API zugreifen

Sie können Tools wie curl oder das Apigee-Dienstprogramm acurl verwenden, um auf die Edge API zuzugreifen.

Mit curl rufen Sie die Edge API auf und übergeben das Zugriffstoken im Authorization: Bearer Header, wie im folgenden Beispiel gezeigt:

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

Mit acurl müssen Sie den Header Authorization nicht angeben. Beispiel:

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

In diesen Beispielen wird ein Edge API-Endpunkt aufgerufen, der Details zur angegebenen Organisation abruft. Eine vollständige Liste der Edge API-Endpunkte finden Sie in der Apigee Edge API-Referenz.

Weitere Methoden zum Aufrufen der API, einschließlich Möglichkeiten, Ihr Token auf dem neuesten Stand zu halten , finden Sie unter Mit OAuth2 auf die Edge API zugreifen.

Maschinennutzer in SAML-Zonen

Mit den Dienstprogrammen acurl und get_token können Sie den automatisierten Zugriff auf die Edge APIs für Maschinenutzer in SAML-Zonen per Skript ausführen. Im folgenden Beispiel wird gezeigt, wie Sie mit get_token ein Zugriffstoken anfordern und dann den Tokenwert einem curl Aufruf hinzufügen:

  USER=me@example.com
  PASS=not-that-secret
  TOKEN=$(get_token -u $USER:$PASS -m '' --force-basic-auth)
  curl -H "Authorization: Bearer $TOKEN" 'https://api.enterprise.apigee.com/v1/organizations/...'

Wenn Sie im obigen Beispiel den Wert von -m auf einen leeren String setzen, werden Maschinenutzer nicht zur Eingabe eines MFA-Codes aufgefordert. Mit dem Flag --force-basic-auth wird die Standardaufforderung für einen Sicherheitscode überschrieben, die durch Anfragen mit SAML-Zonen ausgelöst wird.

Alternativ können Sie die Tokenanfrage und den curl Aufruf mit dem acurl Dienstprogramm kombinieren. Beispiel:

  USER=me@example.com
  PASS=not-that-secret
  acurl -u $USER:$PASS -m '' --force-basic-auth 'https://api.enterprise.apigee.com/v1/organizations/...'