Implementazione del tipo di concessione del codice di autorizzazione

Stai visualizzando la documentazione di Apigee Edge.
Consulta la documentazione di Apigee X. info

Il codice di autorizzazione è uno dei tipi di concessione OAuth 2.0 più utilizzati. Il flusso del codice di autorizzazione è una configurazione "OAUTH a tre vie". In questa configurazione, l'utente si autentica con il server delle risorse e concede all'app il consenso per accedere alle sue 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 di autorizzazione OAuth 2.0 e spiega come implementare questo flusso su Apigee Edge.

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 attendibile con il fornitore dell'API. Ad esempio, gli sviluppatori che si registrano ai programmi API pubblici in genere non sono attendibili. Con questo tipo di concessione, le credenziali dell'utente sul server delle 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 Edge nel repository api-platform-samples su GitHub. Consulta l'esempio oauth-advancednella directory api-platform-samples/sample-proxies. Per maggiori dettagli sull'esempio, consulta il file README.

Diagramma di flusso

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

Suggerimento:per visualizzare una versione più grande di questo diagramma, fai clic con il tasto destro del mouse e aprilo in una nuova scheda oppure salvalo e aprilo in un visualizzatore di immagini.

Passaggi del flusso del codice di autorizzazione

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

Prerequisito: l'app client deve essere registrata con Apigee Edge per ottenere le chiavi ID client e client secret. Per maggiori dettagli, consulta la sezione Registrazione delle 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 Edge, che convalida l'ID client e, se è valido, reindirizza il browser dell'utente a una pagina di accesso in cui l'utente inserirà 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

L'utente ora visualizza una pagina di accesso in cui gli viene chiesto di inserire le proprie credenziali di accesso. Se l'accesso va a buon fine, passiamo al passaggio successivo.

3. L'utente dà il consenso

In questo passaggio, l'utente dà il consenso all'app per accedere alle sue risorse. Il modulo di consenso in genere include selezioni di ambito, in cui l'utente può scegliere cosa è consentito all'app sul server delle risorse. Ad esempio, l'utente può concedere l'autorizzazione di sola lettura o l'autorizzazione all'app di aggiornare le risorse.

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

Se l'accesso e il consenso vanno a buon fine, l'app di accesso invia i dati all'endpoint /authorizationcode di Apigee Edge. I dati includono l'URI di reindirizzamento, l'ID client, l'ambito, eventuali informazioni specifiche dell'utente che vuole includere e un'indicazione che l'accesso è andato a buon fine.

5. Apigee Edge genera un codice di autorizzazione

Quando Edge riceve la richiesta POST dall'app di accesso sul suo endpoint /authorizationcode, si verificano due eventi. Innanzitutto, Edge determina che l'accesso è riuscito (controllando i parametri o le intestazioni della richiesta per un indicatore di successo). Successivamente, Edge verifica che l'URI di reindirizzamento inviato dall'app di accesso corrisponda all'URI di reindirizzamento specificato al momento della registrazione dell'app con Apigee Edge. Se è tutto a posto, Edge genera un codice di autorizzazione.

{redirect_uri}?code={authorization_code}&state={some_string}

6. Il client recupera il codice di autorizzazione e richiede un token di accesso da Edge

Ora, con un codice di autorizzazione valido, il client può richiedere un token di accesso a Edge. A questo scopo, invia tramite POST le chiavi ID client e client secret (ottenute al momento della registrazione dell'app su Edge), il codice di autorizzazione, il tipo di concessione e l'ambito. Se includi l'ID client e le chiavi segrete, Apigee Edge 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'

7. Il client riceve un token di accesso

Se tutto va a buon fine, Edge 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 dato il consenso all'app per accedere alle sue risorse.

8. Il client chiama l'API protetta

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

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

Configurazione di flussi e policy

In qualità di server di autorizzazione, Edge deve elaborare una serie di richieste OAuth: per i token di accesso, i codici di autorizzazione, i token di aggiornamento, i reindirizzamenti della pagina di accesso e così via. Esistono due passaggi fondamentali per configurare questi endpoint:

  • Creazione di flussi personalizzati
  • Aggiunta e configurazione di policy OAuthV2

Configurazione del flusso personalizzata

In genere, questo flusso di tipo concessione viene configurato in modo che ogni passaggio o "tratta" del flusso sia definito da un flusso nel proxy Apigee Edge. Ogni flusso ha un endpoint e un criterio che esegue l'attività specifica di 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, l'endpoint /oauth/authorizationcode ha una policy associata chiamata GenerateAuthCode (che è una policy OAuthV2 con l'operazione GenerateAuthorizationCode specificata).

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

Vedi anche l'implementazione di esempio 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>

Configura i flussi con le policy

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

Reindirizzamento dell'accesso

Questo è il percorso /oauth/authorize. La policy allegata è responsabile del reindirizzamento dell'utente a un'app di accesso, in cui l'utente finale può autenticarsi e autorizzare in modo sicuro l'app client ad accedere alle proprie risorse protette senza rivelare il proprio nome utente e la propria password all'app client. Puoi farlo con una policy di callout del servizio, JavaScript, Node.js o altri mezzi.

La chiamata API per eseguire la richiesta è una GET e richiede i parametri di query 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 un codice di autorizzazione

Questo è il percorso /oauth/authorizationcode. Utilizza la policy 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 è una richiesta POST e richiede che client_id, response_type, redirect_uri e, facoltativamente, scope e state vengano passati nel corpo della richiesta come parametri del modulo, come mostrato in questo esempio:

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

Ottieni token di accesso

Questo criterio è associato al percorso /oauth/accesstoken. Utilizza la policy OAuthV2 con l'operazione GenerateAccessToken specificata. In questo caso, il parametro grant_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 token di accesso è una richiesta POST e deve includere il codice di autorizzazione, client_id, client_secret, grant_type=authorization_code e, facoltativamente, scope. Ad esempio:

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

Questo è solo un riepilogo di base. Un esempio di produzione include molte altre norme per la creazione di URL, l'esecuzione di trasformazioni e altre attività. Per un progetto completo e funzionante, consulta l'esempio su GitHub.

Allegare la policy di verifica del token di accesso

Collega una policy VerifyAccessToken (policy OAuthV2 con l'operazione VerifyAccessToken specificata) all'inizio di qualsiasi flusso che accede a un'API protetta, in modo che venga eseguita ogni volta che arriva una richiesta di risorse protette. Controlli per assicurarsi che ogni richiesta abbia un token di accesso valido. In caso contrario, viene restituito un errore. Per i passaggi di base, consulta Verifica dei 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>

Chiamare l'API protetta

Per chiamare un'API protetta con la sicurezza OAuth 2.0, devi presentare un token di accesso valido. Il pattern corretto prevede l'inclusione del token in un'intestazione Authorization, come segue: Nota che il token di accesso è anche chiamato "token bearer". 

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

Vedi anche Invio di un token di accesso.