Questa pagina è stata tradotta dall'API Cloud Translation.

Utilizzo di token OAuth di terze parti

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

In questo argomento, parleremo di come importare token di accesso, token di aggiornamento o codici di autenticazione generati esternamente nell'archivio token Edge. Puoi utilizzare questa tecnica se vuoi configurare Apigee Edge per convalidare i token generati al di fuori di Apigee Edge.

Nel solito caso, Apigee Edge genererà e archivierà un token OAuth e lo restituirà all'applicazione chiamante. L'app chiamante presenta quindi il token ad Apigee Edge quando richiede il servizio e Apigee Edge, tramite il criterio OAuthV2 con operazione = VerificationAccessToken, verificherà che il token sia valido. Questo argomento descrive come configurare Apigee Edge per archiviare un token OAuth generato altrove, mantenendo invariata la parte di verifica del token, proprio come se il token fosse stato generato da Edge.

Esempio

Se vuoi vedere un esempio funzionante che illustri la tecnica descritta in questo argomento, dai un'occhiata all'esempio di gestione dei token delegati di Apigee.

Che cos'è?

Supponi di disporre di un sistema di autorizzazione esistente e di voler utilizzare i valori del token o del codice generati da tale sistema al posto del token OAuth2 o dei valori di codice generati da Edge. Puoi quindi effettuare richieste proxy API sicure con il token o il codice sostituito, Edge le convaliderà come se fossero state generate da Edge.

Alcune informazioni di base

In genere, Apigee Edge genera un token generando una stringa casuale di lettere e numeri. Apigee Edge associa al token, altri dati come l'ora di emissione, la scadenza, l'elenco dei prodotti API per i quali il token è valido e l'ambito. Tutte queste informazioni possono essere restituite in una risposta generata automaticamente dal criterio OAuthV2 configurato con l'operazione = generateAccessToken. La risposta sarà simile alla seguente:

{
  "issued_at": "1469735625687",
  "application_name": "06947a86-919e-4ca3-ac72-036723b18231",
  "scope": "urn://example.com/read",
  "status": "approved",
  "api_product_list": "[implicit-test]",
  "api_product_list_json": ["implicit-test"],
  "expires_in": "1799", //--in seconds
  "developer.email": "joe@weathersample.com",
  "token_type": "BearerToken",
  "client_id": "U9AC66e9YFyI1yqaXgUF8H6b9wUN1TLk",
  "access_token": "zBC90HhCGmGlaMBWeZAai2s3za5j",
  "organization_name": "wwitman",
  "refresh_token_expires_in": "0", //--in seconds
  "refresh_count": "0"
}

Il valore dell'attributo access_token è di fatto la chiave di ricerca per i dati di risposta. Un'app potrebbe effettuare una richiesta a un proxy API ospitato in Edge, che porta il token di connessione zBC90HhCGmGlaMBWeZAai2s3za5j, mentre Edge, con il criterio OAuthV2 e con l'operazione VerificationAccessToken, cercherà il token, recupererà tutte le informazioni e utilizzerà queste informazioni per determinare se il token è valido o meno per il proxy API richiesto. Questa procedura è chiamata convalida del token. Tutte le informazioni precedenti comprendono il token. Il valore access_token è solo il modo per cercare queste informazioni.

D'altra parte, seguendo i passaggi descritti qui, puoi configurare Edge per archiviare un token in modo che il suo valore access_token sia generato da un servizio esterno. Tutti gli altri metadati potrebbero essere uguali. Ad esempio, supponi di avere un sistema esterno ad Apigee Edge che genera token nel formato "TOKEN-<16 numeri casuali>" . In questo caso, i metadati completi del token archiviati da Apigee Edge potrebbero essere:

{
  "issued_at": "1469735625687",
  "application_name": "06947a86-919e-4ca3-ac72-036723b18231",
  "scope": "urn://example.com/read",
  "status": "approved",
  "api_product_list": "[implicit-test]",
  "api_product_list_json": ["implicit-test"],
  "expires_in": "1799", //--in seconds
  "developer.email": "joe@weathersample.com",
  "token_type": "BearerToken",
  "client_id": "U9AC66e9YFyI1yqaXgUF8H6b9wUN1TLk",
  "access_token": "TOKEN-1092837373654221",
  "organization_name": "wwitman",
  "refresh_token_expires_in": "0", //--in seconds
  "refresh_count": "0"
}

In questo caso, un'app potrebbe effettuare una richiesta a un proxy API ospitato in Edge, che trasporta il token di connessione TOKEN-1092837373654221, mentre Edge, tramite il criterio OAuthV2 con Operazione = VerificationAccessToken, sarà in grado di convalidarlo. Puoi applicare un pattern di importazione simile a codici di autorizzazione e token di aggiornamento.

Parliamo della convalida delle credenziali client

Un prerequisito per la generazione di un token è la convalida del client richiedente. Per impostazione predefinita, il criterio OAuthV2/GeneraAccessToken in Apigee Edge verifica implicitamente le credenziali del client. Normalmente in una richiesta di un token OAuthV2, client_id e client_secret vengono passati nell'intestazione Authorization, codificati tramite autorizzazione di base HTTP (concatenati con i due punti e poi con codifica Base64). Il criterio OAuthV2/GeneraAccessToken in Apigee Edge decodifica l'intestazione e cerca il client_id e verifica che il client_secret passato sia valido per quel client_id. Questo funziona se le credenziali sono note ad Apigee Edge, in altre parole esiste un'app sviluppatore archiviata in Apigee Edge che contiene una credenziale, che a sua volta contiene i client_id e client_secret specificati.

Nel caso in cui le credenziali client non vengano convalidate da Apigee Edge, devi progettare il proxy API prima che generi un token per convalidare esplicitamente il client tramite altri mezzi. Spesso questo avviene tramite un criterio di callout di servizio che si connette a un endpoint remoto nella tua rete.

In un modo o nell'altro, in modo implicito o esplicito, devi assicurarti che il proxy API che genera i token verifichi prima le credenziali del client. Tieni presente che la convalida del client è indipendente dalla generazione del token di accesso. Puoi configurare Apigee Edge per entrambe le operazioni, l'una o l'altra opzione o nessuna delle due.

Se vuoi che il criterio OAuthV2/GeneraAccessToken in Apigee Edge convalidi le credenziali del client rispetto all'archivio perimetrale, imposta l'elemento <ExternalAuthorization> su false all'interno della configurazione del criterio oppure omettilo del tutto. Se vuoi utilizzare un servizio di autorizzazione esterno per convalidare esplicitamente le credenziali del client, imposta <ExternalAuthorization> su true.

Anche se Apigee Edge potrebbe non convalidare le credenziali client, è comunque necessario che client_id sia noto e gestito da Apigee Edge. Ogni access_token in Apigee Edge, generato da Apigee Edge o generato da un sistema esterno e poi importato in Apigee Edge, deve essere associato a un'applicazione client, indicata dal client_id. Quindi, anche nel caso in cui il criterio OAuthV2/GeneraAccessToken in Apigee Edge non convaliderà la corrispondenza di client_id e client_secret, il criterio convaliderà che il client_id è valido, presente e non revocato. Pertanto, come passaggio di configurazione prerequisito, potresti dover importare client_id tramite l'API Edge Admin.

Flusso dei criteri per OAuth di terze parti su Apigee

Per utilizzare i token da sistemi OAuth di terze parti in Apigee Edge, il flusso per la generazione dei token di accesso deve seguire uno dei seguenti pattern.

Convalida esterna delle credenziali client

ServiceCallout per verificare le credenziali del client in entrata e acquisire un token esterno.
ExtractVariables o a passaggio JavaScript per estrarre il token generato esternamente dalla risposta.
AssignMessage per impostare la variabile speciale ben nota denominata oauth_external_authorization_status. Il valore deve essere true per indicare che le credenziali client sono valide.
OAuthV2/GeneraAccessToken con l'elemento <ExternalAuthorization> impostato su true e almeno uno tra <ExternalAccessToken>, <ExternalRefreshToken> o <ExternalAuthorizationCode>.

Convalida interna delle credenziali client

ServiceCallout per acquisire un token esterno.
ExtractVariables o a passaggio JavaScript per estrarre il token generato esternamente dalla risposta.
OAuthV2/GeneraAccessToken con l'elemento <ExternalAuthorization> impostato su false e almeno uno tra <ExternalAccessToken>, <ExternalRefreshToken> o <ExternalAuthorizationCode>.

Note sul flusso e sulla configurazione dei criteri

Nel caso in cui tu voglia utilizzare un sistema esterno per convalidare le credenziali del cliente, spetta a te sviluppare un flusso di criteri che faccia ciò che è necessario. In genere, devi utilizzare un criterio ServiceCallout per inviare le credenziali riconosciute esternamente al servizio di autenticazione esterno. In genere, il servizio di autenticazione esterno restituisce una risposta e, se le credenziali sono valide, anche un token di accesso.
Dopo il ServiceCallout, il proxy API deve analizzare la risposta per estrarre lo stato di validità, nonché l'access_token generato esternamente ed eventualmente il refresh_token.
Nel criterio OAuthV2/GeneraAccessToken, imposta l'elemento <StoreToken> su true e l'elemento <ExternalAuthorization> su true o false in base alle esigenze.

Quando il criterio OAuthV2/GeneraAccessToken viene eseguito, legge la variabile oauth_external_authorization_status. Se la variabile è impostata e il valore è true, Apigee Edge non tenterà di convalidare le credenziali del client. Se la variabile non è impostata o il valore non è true, Apigee Edge tenterà di convalidare le credenziali client.
Il criterio OAuthV2 è composto da tre elementi che consentono di specificare i dati esterni da importare: <ExternalAccessToken>, <ExternalRefreshToken> e <ExternalAuthorizationCode>. Ciascuno di questi elementi accetta una variabile di flusso. Il criterio Edge leggerà quella variabile per trovare il token di accesso, il token di aggiornamento o il codice di autorizzazione generati esternamente. Spetta a te implementare criteri e logica per posizionare i token o i codici esterni nelle variabili appropriate.

Ad esempio, la seguente configurazione nel criterio OAuthV2 indica a Edge di cercare il token in una variabile di contesto denominata external_token.
```
<ExternalAccessToken>external_token</ExternalAccessToken>
```
Dovresti avere anche un passaggio precedente che imposta questa variabile.
Per quanto riguarda l'impostazione della variabile oauth_external_authorization_status, una tecnica comune per impostare questa variabile consiste nell'utilizzare un criterioAssignMessage con l'elemento AssegnaVariable, come segue:
```
<AssignMessage name="AssignMessage-SetVariable">
    <DisplayName>Assign Message - Set Variable</DisplayName>
    <AssignVariable>
        <Name>oauth_external_authorization_status</Name>
        <Value>true</Value>
    </AssignVariable>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>
```
Tieni presente che questo criterio deve precedere il criterio OAuthV2 con l'operazione = generateAccessToken.

Esempio di criterio OAuthV2

Il seguente criterio OAuthV2 genera un token di accesso Apigee Edge se Edge trova un valore del token nella variabile di flusso external_access_token.

<OAuthV2 name="OAuth-v20-Store-External-Token">
    <ExternalAccessToken>external_access_token</ExternalAccessToken>
    <ExternalAuthorization>true</ExternalAuthorization>
    <Operation>GenerateAccessToken</Operation>
    <GenerateResponse enabled="true">
        <Format>FORM_PARAM</Format>
    </GenerateResponse>
    <ReuseRefreshToken>false</ReuseRefreshToken>
    <StoreToken>true</StoreToken>
    <SupportedGrantTypes>
        <GrantType>client_credentials</GrantType>
    </SupportedGrantTypes>
    <ExpiresIn ref='flow.variable'>2400000</ExpiresIn>
</OAuthV2>

In genere, con il tipo di concessione delle credenziali client, devi fornire un'intestazione di autenticazione di base con l'ID client codificato e il client secret. Tuttavia, in questo caso non è necessario fornire l'intestazione. Il criterio prevede comunque la presenza di client_id nella richiesta e il criterio lo convaliderà. Edge prevede che l'oggetto client_id venga inviato come parte dei dati del modulo di richiesta, ad esempio in request.formparam.client_id.

In teoria, puoi applicare questo pattern con qualsiasi servizio di autorizzazione OAuth2 di terze parti.