Accedere all'API Edge con SAML

Stai visualizzando la documentazione di Apigee Edge.
Vai alla documentazione di Apigee X.
informazioni

SAML supporta un ambiente Single Sign-On (SSO). Utilizzando SAML con Edge, puoi supportare il servizio SSO per l'API e la UI di Edge, oltre a qualsiasi altro servizio da te fornito e che supporti SAML.

Prerequisito: devi abilitare SAML per almeno un'organizzazione prima di poterlo utilizzare per accedere all'API Edge.

Differenze tra SAML e OAuth2

Una volta configurato, il protocollo SAML è molto simile all'utilizzo del protocollo OAuth2 per accedere all'API Edge. Quando chiami l'API Edge, includi nella richiesta un token di accesso OAuth2.

La differenza principale tra SAML e OAuth2 durante l'accesso all'API Edge consiste nel modo in cui ricevi i token. Con SAML, devi includere quanto segue quando ricevi la coppia di token:

  1. Zone:gli utenti di Edge per cloud pubblico devono fare riferimento al nome della propria zona quando ricevono i token.
  2. Passcode: includi un passcode monouso quando richiedi una coppia di token di accesso/aggiornamento.

SAML utilizza gli stessi endpoint sul servizio Edge OAuth2, con l'aggiunta del nome della zona appropriato.

Per ottenere token di accesso con SAML, puoi utilizzare uno dei seguenti metodi, descritti in questa sezione:

Inoltre, puoi automatizzare il processo di generazione dei token per gli utenti delle macchine, come descritto in Automatizzare il processo di generazione dei token.

Ottenere token di accesso con get_token

Puoi utilizzare l'utilità get_token per scambiare le tue credenziali per i token di accesso e aggiornamento OAuth2 che utilizzi con SAML.

Per ottenere un token di accesso con get_token:

  1. Imposta la variabile di ambiente SSO_LOGIN_URL sul tuo URL di accesso. L'URL di accesso ha il seguente formato:
    https://zoneName.login.apigee.com

    Ad esempio, per una zona denominata "acme", imposta SSO_LOGIN_URL su "https://acme.login.apigee.com", come illustrato nell'esempio seguente:

    export SSO_LOGIN_URL=https://acme.login.apigee.com
  2. Chiama get_token per ottenere il token di accesso OAuth2:
    get_token -u me@example.com

    Viene richiesto di visitare l'URL visualizzato per ottenere un passcode monouso:

    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:

    Se non hai eseguito l'accesso di recente tramite il tuo provider di identità, ti verrà chiesto di accedere.

    Questo URL restituisce un passcode una-tantum che rimane valido finché non aggiorni l'URL per ottenere un nuovo passcode oppure utilizzi il passcode con get_token per generare un token di accesso. Ad esempio:

  3. Inserisci il passcode. L'utilità get_token ottiene i token OAuth2, stampa il token di accesso su stdout e scrive i token di accesso e di aggiornamento in ~/.sso-cli.

  4. Chiama l'API Edge e passa il token di accesso nell'intestazione Authorization: Bearer, come illustrato nell'esempio seguente:
    curl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
      -H "Authorization: Bearer ACCESS_TOKEN"

    Il valore del token di accesso può essere copiato da stdout.

    Questo esempio restituisce i dettagli sull'organizzazione specificata. Per un elenco completo degli endpoint API di gestione, consulta il riferimento per le API Apigee Edge.

Quando il token di accesso scade, puoi chiamare di nuovo get_token per ottenere un nuovo token di accesso. Ad esempio:

get_token -u me@example.com

Non ti verrà chiesto un nuovo passcode fino alla scadenza del token di aggiornamento.

Alla scadenza del token di aggiornamento, get_token ti chiede un nuovo passcode. Devi generare un nuovo passcode prima di poter generare un nuovo token di accesso OAuth2.

Ottenere token di accesso con il servizio Edge OAuth2

Puoi utilizzare il servizio Edge OAuth2 per ottenere i token di accesso da utilizzare con SAML. Per autenticarti con l'API Edge, utilizza un passcode nella richiesta iniziale per ottenere una coppia di token di accesso/aggiornamento e di nuovo per ottenere una coppia di token aggiornata.

Per ottenere una coppia di token con l'API Edge:

  1. Da un browser, vai al seguente URL per ottenere un passcode monouso:
    https://zoneName.login.apigee.com/passcode

    Ad esempio, per una zona denominata "acme", vai al seguente URL:

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

    Se non hai eseguito l'accesso di recente tramite il tuo provider di identità, ti verrà chiesto di accedere.

    Questo URL restituisce un passcode monouso che funge da credenziali per ricevere i token e rimane valido finché non aggiorni l'URL per ottenere un nuovo passcode oppure puoi utilizzare il passcode con get_token per generare un token di accesso. Ad esempio:

  2. Invia una richiesta all'API Edge, come illustrato nell'esempio seguente:
    curl https://zoneName.login.apigee.com/oauth/token \
          -s \
          -H "Accept: application/json" \
          -d 'grant_type=password&response_type=token&passcode=passcode'

    passcode funge da credenziale per l'autorizzazione.

    Dove:

    • L'intestazione Authorization è "Base ZWRnZWNsaTplZGdlY2xpc2VjcmV0" (utilizza questo valore esatto).
    • Il tipo di richiesta è POST.
    • Il corpo della richiesta contiene quanto segue:
      • grant_type è "password".
      • response_type è "token".
      • passcode, dove passcode è il passcode restituito nel passaggio precedente.

    La chiamata stampa i token di accesso e di aggiornamento sullo schermo.

Per aggiornare il token di accesso:

Invia una richiesta a https://zoneName.login.apigee.com/oauth/token, come illustrato nell'esempio seguente:

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

Dove:

  • Il corpo della richiesta contiene quanto segue:
    • grant_type è "refresh_token".
    • refresh_token è il valore del token di aggiornamento.
  • L'intestazione Authorization è "Base ZWRnZWNsaTplZGdlY2xpc2VjcmV0" (utilizza questo valore esatto).
  • Il tipo di richiesta è POST.

Accedere all'API Edge con SAML

Puoi utilizzare strumenti come curl o la comodità di Apigee acurl per accedere all'API Edge.

Con curl, chiami l'API Edge e passi il token di accesso nell'intestazione Authorization: Bearer, come illustrato nell'esempio seguente:

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

Con acurl, non è necessario specificare l'intestazione Authorization. Ad esempio:

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

Questi esempi chiamano un endpoint dell'API Edge che riceve dettagli sull'organizzazione specificata. Per un elenco completo degli endpoint dell'API Edge, consulta il riferimento per le API Apigee Edge.

Per ulteriori metodi di chiamata all'API, ad esempio per assicurarti che il token rimanga aggiornato, consulta Accedere all'API Edge con OAuth2.

Utenti di macchine nelle zone SAML

Puoi utilizzare le utilità acurl e get_token per creare script dell'accesso automatico alle API Edge per gli utenti delle macchine nelle zone SAML. L'esempio seguente mostra come utilizzare get_token per richiedere un token di accesso e quindi aggiungere il valore del token a una chiamata curl:

  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/...'

Nell'esempio precedente, l'impostazione del valore -m su una stringa vuota impedirà a un utente della macchina di richiedere un codice MFA. L'uso del flag --force-basic-auth sostituirà la richiesta standard di un passcode attivata dalle richieste con zone SAML.

In alternativa, puoi combinare la richiesta del token e la chiamata curl utilizzando l'utilità acurl. Ad esempio:

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