Stai visualizzando la documentazione di Apigee Edge.
Vai alla
documentazione di Apigee X. informazioni
Con il tipo di concessione delle credenziali client, un'app invia le proprie credenziali (ID client e client secret) a un endpoint su Apigee Edge configurato per generare un token di accesso. Se le credenziali sono valide, Edge restituisce un token di accesso all'app client.
Informazioni su questo argomento
Questo argomento offre una descrizione generale del tipo di concessione delle credenziali client OAuth 2.0 e illustra come implementare questo flusso su Apigee Edge.
Casi d'uso
In genere, questo tipo di autorizzazione viene utilizzato quando l'app è anche il proprietario della risorsa. Ad esempio, un'app potrebbe dover accedere a un servizio di archiviazione basato su cloud di backend per archiviare e recuperare i dati che utilizza per svolgere il proprio lavoro, anziché i dati specificamente di proprietà dell'utente finale. Questo flusso del tipo di autorizzazione si verifica rigorosamente tra un'app client e il server di autorizzazione. Un utente finale non partecipa a questo flusso di tipo di autorizzazione.
Ruoli
I ruoli specificano gli "attori" che partecipano al flusso OAuth. Facciamo una rapida panoramica dei ruoli delle credenziali client per capire dove si inserisce Apigee Edge. Per una discussione completa sui ruoli per OAuth 2.0, consulta la specifica OAuth 2.0 di IETF.
- App client: l'app che deve accedere alle risorse protette dell'utente. In genere, con questo flusso, l'app viene eseguita sul server anziché localmente sul laptop o sul dispositivo dell'utente.
- Apigee Edge: in questo flusso, Apigee Edge è il server di autorizzazione OAuth. Il suo ruolo è generare token di accesso, convalidare i token di accesso e passare richieste autorizzate per le risorse protette al server delle risorse.
- Server risorse: il servizio di backend che archivia i dati protetti per i quali l'app client ha bisogno dell'autorizzazione per accedere. Se stai proteggendo i proxy API ospitati su Apigee Edge, Apigee Edge è anche il server delle risorse.
Esempio di codice
Puoi trovare un' implementazione di esempio completa e funzionante del tipo di concessione delle credenziali client su GitHub. Consulta la sezione Risorse aggiuntive di seguito per trovare link ad altri esempi.
Diagramma di flusso
Il seguente diagramma di flusso illustra il flusso delle credenziali del client con Apigee Edge che funge da server di autorizzazione. In generale, Edge è anche il server di risorse in questo flusso, ovvero i proxy API sono le risorse protette.
Passaggi nel flusso delle credenziali client
Di seguito è riportato un riepilogo dei passaggi necessari per implementare il tipo di concessione del codice delle credenziali client in cui Apigee Edge funge da server di autorizzazione. Ricorda che, con questo flusso, l'app client presenta semplicemente il suo ID client e client secret e, se sono validi, Apigee Edge restituisce un token di accesso.
Prerequisito: l'app client deve essere registrata con Apigee Edge per ottenere l'ID client e le chiavi client secret. Per maggiori dettagli, consulta Registrazione delle app client.
1. Il client richiede un token di accesso
Per ricevere un token di accesso, il client PUBBLICA una chiamata API a Edge con i valori per ID client e client secret ottenuti da un'app sviluppatore registrata. Inoltre, il parametro Grants_type=client_credentials deve essere trasmesso come parametro di query. Tuttavia, puoi configurare il criterio OAuthV2 in modo che accetti questo parametro nell'intestazione o nel corpo della richiesta. Per i dettagli, consulta il criterio OAuthV2.
Ad esempio:
$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST 'https://docs-test.apigee.net/oauth/accesstoken' -d 'grant_type=client_credentials&client_id=ns4fQc14Zg4hKFCNaSzArVuwszX95X&client_secret=ZIjFyTsNgQNyxI'
Nota: anche se puoi passare i valori client_id e client_secret come parametri di query come mostrato sopra, è buona norma trasmetterli come stringa con codifica URL base64 nell'intestazione Authorization. Per farlo, devi utilizzare uno strumento o un'utilità di codifica Base64 per codificare i due valori con i due punti che li separano. Ad esempio: aBase64EncodeFunction(clientidvalue:clientsecret). Pertanto, l'esempio precedente verrebbe codificato come segue:
result = aBase64EncodeFunction(ns4fQc14Zg4hKFCNaSzArVuwszX95X:ZIjFyTsNgQNyxI) // Nota i due punti che separano i due valori.
Il risultato della codifica Base64 per la stringa riportata sopra è: bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJOg==
Quindi, effettua la richiesta del token nel seguente modo:
$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST 'https://docs-test.apigee.net/oauth/accesstoken' -d 'grant_type=client_credentials' -H 'Authorization: Basic bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJOg=='
2. Edge convalida le credenziali
Tieni presente che la chiamata API viene inviata all'endpoint /accesstoken. A questo endpoint è associato un criterio che convalida le credenziali dell'app. In altre parole, il criterio confronta le chiavi inviate con quelle create da Apigee Edge al momento della registrazione dell'app. Per saperne di più sugli endpoint OAuth su Edge, consulta Configurazione di endpoint e criteri OAuth.
3. Edge restituisce una risposta
Se le credenziali sono corrette, Edge restituisce un token di accesso al client. In caso contrario, viene restituito un errore.
4. 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), che si occupa della convalida del token di accesso prima di passare la chiamata API al server delle risorse di destinazione. Ad esempio, consulta la sezione Chiamata all'API protetta di seguito.
Configurazione di flussi e criteri
In qualità di server di autorizzazione, Edge elabora le richieste per i token di accesso. In qualità di sviluppatore di API, devi creare un proxy con un flusso personalizzato per gestire le richieste di token e aggiungere e configurare un criterio OAuthV2. Questa sezione spiega come configurare l'endpoint.
Configurazione dei flussi personalizzata
Il modo più semplice per mostrare come è configurato il flusso proxy API è mostrare la definizione del flusso XML. Di seguito è riportato un esempio di flusso proxy API progettato per elaborare una richiesta di token di accesso. Ad esempio, quando arriva una richiesta e il suffisso del percorso corrisponde a /accesstoken, viene attivato il criterio GetAccessToken. Consulta Configurazione di endpoint e criteri OAuth per una rapida panoramica dei passaggi necessari per creare un flusso personalizzato come questo.
<Flows>
<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>GetAccessToken</Name></Step>
</Request>
</Flow>
</Flows>
Configurare il flusso con un criterio
Devi collegare un criterio all'endpoint come indicato di seguito. Consulta Configurazione di endpoint e criteri OAuth per una rapida panoramica dei passaggi necessari per aggiungere un criterio OAuthV2 a un endpoint proxy.
Recupera token di accesso
Questo criterio è collegato al percorso /accesstoken. Utilizza il criterio OAuthV2 con l'operazione GeneraAccessToken specificata.
<OAuthV2 name="GetAccessToken">
<Operation>GenerateAccessToken</Operation>
<ExpiresIn>3600000</ExpiresIn>
<SupportedGrantTypes>
<GrantType>client_credentials</GrantType>
</SupportedGrantTypes>
<GenerateResponse/>
</OAuthV2>
La chiamata API per ottenere il token di accesso è una richiesta POST e include un'intestazione di autorizzazione con client_id + client+secret con codifica Base64 e il parametro di query Grants_type=client_credentials. Può anche includere parametri facoltativi per ambito e stato. Ad esempio:
$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST 'https://docs-test.apigee.net/oauth/accesstoken' -d 'grant_type=client_credentials' -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAySVgT1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ'
Collegamento del criterio del token di accesso di verifica
Per proteggere la tua API con la sicurezza OAuth 2.0, devi aggiungere un criterio OAuthV2 con l'operazione VerificationAccessToken. Questo criterio verifica che le richieste in arrivo abbiano un token di accesso valido. Se il token è valido, Edge elabora la richiesta. Se non è valido, Edge restituisce 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 all'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 di autorizzazione, come segue: tieni presente che il token di accesso è denominato anche "token di trasferimento".
$ curl -H "Authorization: Bearer UAj2yiGAcMZGxfN2DhcUbl9v8WsR" \ http://myorg-test.apigee.net/v0/weather/forecastrss?w=12797282
Vedi anche Inviare un token di accesso.
Risorse aggiuntive
- Apigee offre formazione online per gli sviluppatori di API, compreso un corso sulla sicurezza delle API, che include OAuth.
- Criterio OAuthV2: contiene molti esempi che mostrano come effettuare richieste al server di autorizzazione e come configurare il criterio OAuthV2.