Mit SAML auf die Edge API zugreifen

Sie sehen die Dokumentation zu Apigee Edge.
Zur Apigee X-Dokumentation weitere Informationen

SAML unterstützt eine Umgebung für die Einmalanmeldung (SSO). Wenn Sie SAML mit Edge verwenden, können Sie die SSO für die Edge-Benutzeroberfläche und -API zusätzlich zu allen anderen Diensten unterstützen, die Sie bereitstellen und die auch SAML unterstützen.

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

Unterschiede zwischen SAML und OAuth2

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

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

  1. Zonen: Edge für Nutzer von öffentlichen Clouds müssen beim Abrufen von Tokens auf ihren Zonennamen verweisen.
  2. Sicherheitscode: Geben Sie einen einmaligen Sicherheitscode an, wenn Sie ein Zugriffs-/Aktualisierungstoken-Paar anfordern.

SAML verwendet dieselben Endpunkte im Edge-OAuth2-Dienst, wobei der entsprechende Zonenname hinzugefügt wird.

Um Zugriffstokens mit SAML zu erhalten, können Sie eine der folgenden Methoden verwenden, die in diesem Abschnitt beschrieben werden:

Darüber hinaus können Sie das Generieren von Tokens für Computernutzer automatisieren, wie unter Tokengenerierungsprozess 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 Log-in-URL hat das folgende Format: 
    https://zoneName.login.apigee.com

    Legen Sie beispielsweise für eine Zone mit dem Namen „acme“ für SSO_LOGIN_URL „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 einmaligen 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 in letzter Zeit nicht bei Ihrem Identitätsanbieter angemeldet haben, werden Sie dazu aufgefordert.

    Diese URL gibt einen einmaligen Sicherheitscode zurück. Dieser bleibt gültig, bis Sie die URL aktualisieren, um einen neuen Sicherheitscode zu erhalten, oder Sie verwenden den Sicherheitscode mit get_token, um ein Zugriffstoken zu generieren. Beispiel:

  3. Geben Sie den Sicherheitscode ein. Das get_token-Dienstprogramm 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 Header Authorization: Bearer, 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 Verwaltungs-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 zur Eingabe eines neuen Sicherheitscodes aufgefordert, wenn das Aktualisierungstoken abgelaufen ist.

Wenn das Aktualisierungstoken abläuft, werden Sie von get_token zur Eingabe eines neuen Sicherheitscodes aufgefordert. Sie müssen einen neuen Sicherheitscode generieren, bevor Sie ein neues OAuth2-Zugriffstoken generieren können.

Zugriffstokens mit dem Edge-OAuth2-Dienst abrufen

Mit dem Edge-OAuth2-Dienst können Sie Zugriffstokens abrufen, die Sie mit SAML verwenden. Um sich bei der Edge API zu authentifizieren, verwenden Sie bei Ihrer ersten Anfrage einen Sicherheitscode, um ein Zugriffs-/Aktualisierungstoken-Paar abzurufen, und noch einmal, um ein neues Token-Paar zu erhalten.

So rufen Sie ein Tokenpaar mit der Edge API ab:

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

    Rufen Sie beispielsweise für eine Zone mit dem Namen "acme" die folgende URL auf:

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

    Wenn Sie sich in letzter Zeit nicht bei Ihrem Identitätsanbieter angemeldet haben, werden Sie dazu aufgefordert.

    Diese URL gibt einen einmaligen Sicherheitscode zurück, der als Anmeldedaten zum Abrufen von Tokens dient. Er bleibt gültig, 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'

    passcode dient als Anmeldedaten für die Autorisierung.

    Wobei:

    • Der Header Authorization ist „Basic ZWRnZWNsaTplZGdlY2xpc2VjcmV0“ (verwenden Sie genau diesen Wert).
    • Der Anfragetyp ist POST.
    • Der Anfragetext enthält Folgendes:
      • grant_type ist „Passwort“.
      • 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 das folgende Beispiel zeigt:

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

Wobei:

  • Der Anfragetext enthält Folgendes:
    • grant_type ist „refresh_token“.
    • refresh_token ist der Wert des Aktualisierungstokens.
  • Der Header Authorization 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-Convenience-Dienstprogramm acurl verwenden, um auf die Edge API zuzugreifen.

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

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

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

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

In diesen Beispielen wird ein Edge-API-Endpunkt aufgerufen, der Details über die angegebene 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, um sicherzustellen, dass Ihr Token aktuell bleibt, finden Sie unter Mit OAuth2 auf die Edge-API zugreifen.

Computernutzer in SAML-Zonen

Mit den Dienstprogrammen acurl und get_token können Sie für Computernutzer in SAML-Zonen Skripts für den automatischen Zugriff auf die Edge APIs erstellen. Das folgende Beispiel zeigt, 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 festlegen, wird ein Computernutzer 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 Dienstprogramm acurl 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/...'