Questa pagina si applica ad Apigee e Apigee hybrid.
Visualizza la documentazione di
Apigee Edge.
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 fornisce una descrizione generale e una panoramica del flusso del tipo di concessione dell'autorizzazione OAuth 2.0 e illustra come implementare questo flusso 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 attendibile con il fornitore dell'API. Ad esempio, in genere non è consigliabile considerare attendibili gli sviluppatori che si registrano per i programmi API pubbliche. 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 nel repository api-platform-samples
su GitHub. Consulta l'esempio oauth-advanced nella directory api-platform-samples/sample-proxies. Per informazioni dettagliate sul sample, consulta il file
README.
Diagramma di flusso
Il seguente diagramma di flusso illustra il flusso OAuth del codice di autorizzazione con Apigee come server di autorizzazione.
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 funge da server di autorizzazione. Ricorda che la chiave di questo flusso è che il client non visualizza mai le credenziali dell'utente sul server di risorse.
Prerequisito: l'app client deve essere registrata in Apigee per ottenere le chiavi dell'ID client e del client secret. Per maggiori dettagli, consulta 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 contatti su un sito di social media), invia una chiamata API ad Apigee, che convalida l'ID del client e, se è valido, reindirizza il browser dell'utente a una pagina di accesso in cui inserire le credenziali. La chiamata API include le informazioni ottenute dall'app client al momento della registrazione: l'ID client e l'URI di reindirizzamento.
2. L'utente inserisce le credenziali
L'utente ora vede una pagina di accesso in cui gli viene chiesto di inserire le credenziali di accesso. Se l'accesso è andato a buon fine, vai al passaggio successivo.
3. L'utente dà il consenso
In questo passaggio, l'utente concede all'app il consenso per accedere alle sue risorse. Il modulo del consenso solitamente include le selezioni dell'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 per consentire all'app di aggiornare le risorse.
4. L'app di accesso invia una richiesta Apigee
Se l'accesso e il consenso vanno a buon fine, l'app di accesso invia i dati tramite POST all'endpoint /authorizationcode di Apigee. I dati includono l'URI di reindirizzamento, l'ID cliente, l'ambito, eventuali informazioni specifiche dell'utente che si desidera includere e un'indicazione che indica che l'accesso è andato a buon fine.
5. Apigee genera un codice di autorizzazione
Quando Apigee riceve una richiesta GET dall'app di accesso sul proprio endpoint /authorizationcode, si verificano due cose. Innanzitutto, Apigee determina che l'accesso è andato a buon fine (controllando lo stato HTTP o con altri mezzi). Successivamente, Apigee verifica che l'URI di reindirizzamento inviato dall'app di accesso sia uguale all'URI di reindirizzamento specificato quando l'app è stata registrata in 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 un reindirizzamento 302 con il codice di autenticazione allegato come parametro di query al client.
7. Il client recupera il codice di autorizzazione e richiede un codice di accesso ad Apigee
Ora, con un codice di autenticazione valido, il client può richiedere un token di accesso da Apigee. A tal fine, invia tramite POST le chiavi ID client e client secret (ottenuti durante la registrazione dell'app su Apigee), il tipo di concessione e l'ambito. Se includi le chiavi client secret e ID client, 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 dato il consenso all'app per 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 inviate ad Apigee (il proxy) e Apigee è responsabile della convalida del token di accesso prima di inoltrare la chiamata API al server di risorse di destinazione. I token di accesso vengono passati in un'intestazione Authorization. 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 autenticazione, token di aggiornamento, reindirizzamenti alla pagina di accesso e così via. Esistono due passaggi fondamentali per configurare questi endpoint:
- Creazione di flussi personalizzati
- Aggiunta e configurazione dei criteri OAuthV2
Configurazione del flusso personalizzato
In genere, configuri questo tipo di flusso di concessione in modo che ogni passaggio o tappa del flusso sia definito da un flusso nel proxy Apigee. 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 un criterio associato chiamato GenerateAuthCode (che è un criterio OAuthV2 con l'operazione GenerateAuthorizationCode specificata).
Il modo più semplice per mostrare la configurazione del flusso è utilizzare un esempio XML. Consulta i commenti in riga per informazioni su ogni 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 breve panoramica dei passaggi necessari per creare un flusso personalizzato come questo.
Consulta 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>
Configurare i flussi con i criteri
A ogni endpoint è associato un criterio. Vediamo alcuni esempi di norme. Consulta anche Configurare endpoint e criteri OAuth per una breve panoramica dei passaggi necessari per aggiungere i criteri OAuth 2.0 agli endpoint proxy.
Reindirizzamento all'accesso
Questo è il percorso /oauth/authorize
. Il criterio allegato è responsabile del reindirizzamento dell'utente a un'app di accesso, in cui l'utente finale può autenticarsi e autorizzare in sicurezza l'app client ad accedere alle sue 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 effettuare la richiesta è 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 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 è una richiesta GET e richiede i parametri di query client_id, response_type e, facoltativamente, scope e state, 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}
Ottenere il token di accesso
Questo criterio è associato al percorso /oauth/accesstoken
. Utilizza il criterio OAuthV2 con l'operazione GenerateAccessCode 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 codice di accesso è un POST e deve includere 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 '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à. Consulta l'esempio su GitHub per un progetto completo e funzionante.
Attacco del criterio di verifica del token di accesso
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 viene inviata una richiesta per una risorsa protetta. Apigee verifica che ogni richiesta abbia un token di accesso valido. In caso contrario, viene restituito un errore. Per i passaggi di base, consulta 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 dell'API protetta
Per chiamare un'API protetta con la sicurezza OAuth 2.0, devi presentare un token di accesso valido. Il pattern corretto è includere il token in un'intestazione Authorization, come segue: tieni presente che il token di accesso è indicato anche come 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.