Questa pagina è stata tradotta dall'API Cloud Translation.

Implementazione del tipo di concessione del codice di autorizzazione

Questa pagina si applica a Apigee e Apigee ibrido.

Visualizza la documentazione di Apigee Edge.

Il codice di autorizzazione è uno dei tipi di autorizzazione OAuth 2.0 più comunemente utilizzati. Il flusso del codice di autorizzazione è una configurazione OAuth a tre vie. In questa configurazione, l'utente si autentica con il server di risorse e concede all'app il consenso per accedere alle risorse protette senza divulgare nome utente/password all'app client.

Informazioni su questo argomento

Questo argomento offre una descrizione generale e una panoramica del flusso del tipo di concessione dell'autorizzazione OAuth 2.0 e illustra come implementarlo su Apigee.

Video

Guarda un breve video per scoprire come utilizzare il tipo di concessione dell'autorizzazione OAuth 2.0 per proteggere le tue API.

Casi d'uso

Questo tipo di concessione è destinato alle app scritte da sviluppatori di terze parti che non hanno un rapporto commerciale affidabile con il fornitore di API. Ad esempio, in genere non dovrebbero essere considerati attendibili gli sviluppatori che si registrano a programmi API pubblici. Con questo tipo di concessione, le credenziali dell'utente sul server di risorse non vengono mai condivise con l'app.

Esempio di codice

Puoi trovare un'implementazione di esempio completa e funzionante del tipo di concessione del codice di autorizzazione su Apigee nel repository api-platform-samples su GitHub. Visualizza l'esempio oauth-advanced nella directory api-platform-samples/sample-proxies. Consulta il file README per i dettagli sull'esempio.

Diagramma di flusso

Il seguente diagramma di flusso illustra il flusso OAuth del codice di autorizzazione con Apigee che funge da server di autorizzazione.

Il flusso OAuth del codice di autorizzazione.

Passaggi nel flusso del codice di autorizzazione

Ecco un riepilogo dei passaggi necessari per implementare il tipo di concessione del codice di autorizzazione in cui Apigee funge da server di autorizzazione. Ricorda che la chiave di questo flusso è che il client non vede mai le credenziali dell'utente sul server di risorse.

Prerequisito: l'app client deve essere registrata con Apigee per ottenere l'ID client e le chiavi client secret. Per maggiori dettagli, consulta la sezione Registrazione di app client.

1. L'utente avvia il flusso

Quando l'app deve accedere alle risorse protette dell'utente da un server di risorse (ad esempio, l'elenco dei contatti su un sito di social media), invia una chiamata API ad Apigee, che convalida l'ID client e, se è valido, reindirizza il browser dell'utente a una pagina di accesso in cui l'utente dovrà inserire le proprie credenziali. La chiamata API include le informazioni che l'app client ha ottenuto al momento della registrazione: l'ID client e l'URI di reindirizzamento.

2. L'utente inserisce le credenziali

A questo punto, l'utente vede una pagina di accesso in cui gli viene chiesto di inserire le credenziali di accesso. Se l'accesso riesce, andiamo al passaggio successivo.

Pagina di accesso ad Apigee con i campi Indirizzo email e Password.

3. L'utente dà il consenso

In questo passaggio, l'utente concede all'app il consenso per accedere alle proprie risorse. In genere il modulo di consenso include selezioni degli ambiti in cui l'utente può scegliere le azioni consentite all'app sul server di risorse. Ad esempio, l'utente potrebbe concedere all'app un'autorizzazione di sola lettura o un'autorizzazione per aggiornare le risorse.

Pagina del consenso in cui l'app di esempio richiede l'autorizzazione per ordinare con i pulsanti Consenti e Rifiuta.

4. L'app di accesso invia una richiesta ad Apigee

Se l'accesso e il consenso hanno esito positivo, l'app di accesso POSTA i dati nell'endpoint /Authorizationcode di Apigee. I dati includono URI di reindirizzamento, ID client, ambito, eventuali informazioni specifiche dell'utente da includere e un'indicazione dell'esito positivo dell'accesso.

5. Apigee genera un codice di autorizzazione

Quando Apigee riceve una richiesta GET dall'app di accesso sul suo endpoint /Authorizationcode, si verificano due cose. Innanzitutto, Apigee determina che l'accesso è riuscito (controllando lo stato HTTP o altri mezzi). In seguito, Apigee controlla che l'URI di reindirizzamento inviato dall'app di accesso corrisponda all'URI di reindirizzamento specificato al momento della registrazione dell'app con Apigee. Se è tutto a posto, Apigee genera un codice di autorizzazione. Ad esempio:

http://myorg-test.apigee.net/oauth/authorizationcode?client_id={consumer_key}&response_type=code&redirect_uri={redirect_uri}&scope=scope1%20scope2&state={some_string}

6. Apigee restituisce il codice di autorizzazione al client

Apigee invia al client un reindirizzamento 302 con il codice di autorizzazione collegato come parametro di query.

7. Il client recupera il codice di autorizzazione e richiede un codice di accesso ad Apigee

Ora, con un codice di autorizzazione valido, il client può richiedere un token di accesso ad Apigee. Per farlo, pubblica l'ID client, le chiavi client secret (ottenute al momento della registrazione dell'app su Apigee), il tipo di concessione e l'ambito. Includendo l'ID client e le chiavi secret, Apigee può verificare che l'app client sia quella registrata. Ad esempio:

$ curl https://{org_name}-test.apigee.net/my_oauth_proxy/accesstoken?code=Xyz123&grant_type=authorization_code -X POST -d 'client_id=bBGAQrXgivA9lKu7NMPyoYpKNhGar6K&client_secret=hAr4GngA9vAyvI4'

8. Il client riceve un token di accesso

Se tutto va a buon fine, Apigee restituisce un token di accesso al client. Il token di accesso avrà una scadenza e sarà valido solo per l'ambito specificato dall'utente quando ha concesso all'app il consenso ad accedere alle sue risorse.

9. Il client chiama l'API protetta

Ora, con un codice di accesso valido, il client può effettuare chiamate all'API protetta. In questo scenario, le richieste vengono effettuate ad Apigee (il proxy) e Apigee è responsabile della convalida del token di accesso prima di passare la chiamata API al server di risorse di destinazione. I token di accesso vengono passati in un'intestazione Autorizzazione. Ad esempio:

$ curl -H "Authorization: Bearer ylSkZIjbdWybfs4fUQe9BqP0LH5Z" http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282

Configurazione di flussi e criteri

In qualità di server di autorizzazione, Apigee deve elaborare una serie di richieste OAuth: per token di accesso, codici di autorizzazione, token di aggiornamento, reindirizzamenti alle pagine di accesso e così via. La configurazione di questi endpoint richiede due passaggi fondamentali:

Creazione di flussi personalizzati
Aggiunta e configurazione dei criteri OAuthV2

Configurazione del flusso personalizzato

In genere configuri questo flusso del tipo di autorizzazione in modo che ogni passaggio o gamba del flusso sia definito da un flusso nel proxy Apigee. Ogni flusso ha un endpoint e un criterio che esegue l'attività specifica per OAuth richiesta, ad esempio la generazione di un codice di autorizzazione o di un token di accesso. Ad esempio, come mostrato nel codice XML di seguito, all'endpoint /oauth/authorizationcode è associato un criterio denominato CreateAuthCode (che è un criterio OAuthV2 per cui è specificata l'operazione GenerateAuthorizationCode).

Il modo più semplice per mostrare la configurazione del flusso è con un esempio XML. Consulta i commenti in linea per informazioni su ciascun flusso. Questo è un esempio: i nomi di flussi e percorsi possono essere configurati come preferisci. Consulta anche Configurazione di endpoint e criteri OAuth per una rapida panoramica dei passaggi necessari per creare un flusso personalizzato come questo.

Vedi anche l'esempio di implementazione su GitHub.

<Flows>
  <Flow name="RedirectToLoginApp">
         <!-- 
         Publish this URI to developers to use for their 'login' link 
         -->
    <Condition>proxy.pathsuffix == "/oauth/authorize"</Condition>
    <Request>
        <Step><Name>RedirectToLoginPage</Name></Step>
    </Request>
  </Flow>
  <Flow name="GetAuthCode">
         <!-- 
         Call this URL from your Login app after you authenticate the user.
         The policy will automatically return the auth code in the response to the 
         redirect_uri registered by the calling app 
         -->
    <Condition>proxy.pathsuffix == "/oauth/authorizationcode"</Condition>
    <Request>
        <Step><Name>GenerateAuthCode</Name></Step>
    </Request>
  </Flow>
  <Flow name="GetAccessToken">
         <!-- This policy flow is triggered when the URI path suffix
         matches /oauth/accesstoken. Publish this URL to app developers 
         to use when obtaining an access token using an auth code   
         -->
    <Condition>proxy.pathsuffix == "/oauth/accesstoken"</Condition>
    <Request>
        <Step><Name>GenerateAccessToken</Name></Step>
    </Request>
  </Flow>
</Flows>

Configurare i flussi con i criteri

A ogni endpoint è associato un criterio. Vediamo alcuni esempi di norme. Consulta anche Configurazione di endpoint e criteri OAuth per una rapida panoramica dei passaggi necessari per aggiungere i criteri OAuthV2 agli endpoint del proxy.

Questo è il percorso /oauth/authorize. Il criterio allegato è responsabile del reindirizzamento dell'utente a un'app di accesso, in cui l'utente finale può autenticare e autorizzare in sicurezza l'app client ad accedere alle risorse protette senza divulgare il nome utente e la password all'app client. Puoi farlo con un criterio di callout del servizio, JavaScript o altri mezzi.

La chiamata API per eseguire la richiesta è GET e richiede i parametri di ricerca client_id, response_type, Redirect_uri, scope e state.

$ curl http://myorg-test.apigee.net/oauth/authorize?client_id={consumer_key}&response_type=code&redirect_uri={redirect_uri}&scope=scope1%20scope2&state={some_string}

Richiedi codice di autorizzazione

Questo è il percorso /oauth/authorizationcode. Utilizza il criterio OAuthV2 con l'operazione generateAuthorizationCode specificata.

<OAuthV2 async="false" continueOnError="false" enabled="true" name="GetAuthCode">
    <DisplayName>GetAuthCode</DisplayName>
    <Operation>GenerateAuthorizationCode</Operation>
    <ExpiresIn>600000</ExpiresIn>
    <GenerateResponse/>
</OAuthV2>

La chiamata API per ottenere il codice di autorizzazione è GET e richiede i parametri di ricerca client_id, response_type e, facoltativamente, ambito e stato, come mostrato in questo esempio:

$curl http://myorg-test.apigee.net/oauth/authorizationcode?client_id={consumer_key}&response_type=code&scope=scope1%20scope2&state={some_string}

Richiedi token di accesso

Questo criterio è collegato al percorso /oauth/accesstoken. Utilizza il criterio OAuthV2 con l'operazione generateAccessCode specificata. In questo caso, il parametro allow_type è previsto come parametro di query:

<OAuthV2 name="GetAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>360000000</ExpiresIn> 
    <SupportedGrantTypes> 
        <GrantType>authorization_code</GrantType> 
    </SupportedGrantTypes> 
    <GrantType>request.queryparam.grant_type</GrantType> 
    <GenerateResponse/> 
</OAuthV2>

La chiamata API per ottenere il codice di accesso è un POST e deve includere client_id, client_secret, allow_type=authenticate_code e, facoltativamente, l'ambito. Ad esempio:

$ curl https://{org_name}-test.apigee.net/oauth/accesstoken?grant_type=authorization_code -X POST -d 'client_id=bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K&client_secret=hAr4Gn0gA9vAyvI4'

Questo è solo un riepilogo di base. Un esempio di produzione include molti altri criteri per creare URL, eseguire trasformazioni ed eseguire altre attività. Fai riferimento all'esempio su GitHub per un progetto completo e funzionante.

Collegamento del criterio di verifica del token di accesso in corso...

Collega un criterio VerifyAccessToken (criterio OAuthV2 con l'operazione VerifyAccessToken specificata) all'inizio di qualsiasi flusso che accede a un'API protetta, in modo che venga eseguito ogni volta che arriva una richiesta per una risorsa protetta. Apigee controlla che ogni richiesta abbia un token di accesso valido. In caso contrario, viene restituito un errore. Per i passaggi di base, vedi Verificare i token di accesso.

<OAuthV2 async="false" continueOnError="false" enabled="true" name="VerifyAccessToken">
    <DisplayName>VerifyAccessToken</DisplayName>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>VerifyAccessToken</Operation>
    <SupportedGrantTypes/>
    <GenerateResponse enabled="true"/>
    <Tokens/>
</OAuthV2>

Chiamata all'API protetta

Per chiamare un'API protetta con la sicurezza OAuth 2.0, devi presentare un token di accesso valido. Il pattern corretto consiste nell'includere il token in un'intestazione Autorizzazione, come segue: Tieni presente che il token di accesso è anche indicato come token di connessione.

$ curl -H "Authorization: Bearer UAj2yiGAcMZGxfN2DhcUbl9v8WsR" \
  http://myorg-test.apigee.net/v0/weather/forecastrss?w=12797282

Vedi anche Invio di un token di accesso.