Questa pagina è stata tradotta dall'API Cloud Translation.

Utilizzo di token OAuth di terze parti

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

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

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

Esempio

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

Cosa significa?

Supponiamo che tu disponga di un sistema di autorizzazione esistente e voglia utilizzare i valori del token o del codice generati da quel sistema al posto dei valori del token OAuth2 o del codice generati da Apigee. Puoi quindi effettuare richieste di proxy API sicure con il token o il codice sostituito e Apigee le convaliderà come se fossero state generate da Apigee.

Alcune informazioni di base

Nel solito caso, Apigee genera un token producendo una stringa casuale di lettere e numeri. Apigee associa a quel 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 Operation = 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": "myorg",
  "refresh_token_expires_in": "0", //--in seconds
  "refresh_count": "0"
}

Il valore access_token viene utilizzato da Apigee per recuperare i metadati del token. Ad esempio, supponi che una richiesta proxy API includa il token di connessione zBC90HhCGmGlaMBWeZAai2s3za5j. Utilizzando il valore del token, Apigee recupera i metadati del token per determinare se il token è valido o meno.

Segui i passaggi descritti qui per configurare Apigee per archiviare un token il cui valore access_token è stato generato da un servizio esterno. Ad esempio, supponiamo di avere un sistema esterno ad Apigee che genera token nel formato "TOKEN-<16 numeri casuali>" . In questo caso, i metadati del token completi archiviati da Apigee 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": "myorg",
  "refresh_token_expires_in": "0", //--in seconds
  "refresh_count": "0"
}

In questo caso, un'app potrebbe effettuare una richiesta a un proxy API, che trasporta il token di connessione TOKEN-1092837373654221, e Apigee potrà convalidarlo. Puoi applicare un pattern di importazione simile ai codici di autorizzazione e ai 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/GenerateAccessToken in Apigee verifica in modo implicito le credenziali del client. Normalmente in una richiesta di un token OAuthV2, client_id e client_secret vengono passati nell'intestazione Authorization, codificati tramite l'autorizzazione di base HTTP (concatenata ai due punti, quindi con codifica Base64). Il criterio OAuthV2/GenerateAccessToken in Apigee decodifica l'intestazione e cerca l'client_id, verifica che il valore client_secret trasmesso sia valido per quel particolare client_id. Questo comando funziona se le credenziali sono note ad Apigee, in altre parole esiste un'app per sviluppatori archiviata in Apigee che contiene una credenziale, che a sua volta contiene i valori client_id e client_secret specificati.

Nel caso in cui le credenziali del client non vengano convalidate da Apigee, devi progettare il proxy API prima che generi un token, al fine di convalidare esplicitamente il client tramite altri mezzi. Spesso questo avviene tramite un criterio 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 convalidi prima le credenziali del client. Tieni presente che la convalida del client è indipendente dalla generazione del token di accesso. Puoi configurare Apigee in modo che esegua entrambe le operazioni, l'una o l'altra o nessuna delle due.

Se vuoi che il criterio OAuthV2/GenerateAccessToken in Apigee convalidi le credenziali del client nell'archivio Apigee, 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 potrebbe non convalidare le credenziali del client, è comunque necessario che client_id sia noto e gestito da Apigee. Ogni access_token in Apigee, generato da Apigee o generato da un sistema esterno e poi importato in Apigee, deve essere associato a un'applicazione client, indicata da client_id. Quindi, anche nel caso in cui il criterio OAuthV2/GenerateAccessToken in Apigee non convaliderà la corrispondenza di client_id e client_secret, il criterio convaliderà che client_id è valido, presente e non revocato. Quindi, come passaggio di configurazione preliminare, potresti dover importare i client_id tramite l'API amministrativa Apigee.

Flusso di criteri per OAuth di terze parti su Apigee

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

Convalida esterna delle credenziali client

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

Note sul flusso e sulla configurazione dei criteri

Se vuoi utilizzare un sistema esterno per convalidare le credenziali del client, spetta a te sviluppare un flusso di criteri che faccia ciò che è necessario. Normalmente useresti un criterio ServiceCallout per inviare le credenziali riconosciute esternamente al servizio di autenticazione esterno. Il servizio di autenticazione esterno restituisce in genere 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é il token access_token generato esternamente ed eventualmente il token refresh_token.
Nel criterio OAuthV2/GenerateAccessToken imposta l'elemento <StoreToken> su true e imposta l'elemento <ExternalAuthorization> su true o false in base alle esigenze.

Quando viene eseguito il criterio OAuthV2/GenerateAccessToken, legge la variabile oauth_external_authorization_status. Se la variabile è impostata e il valore è true, Apigee non tenta di convalidare le credenziali del client. Se la variabile non è impostata o il valore non è true, Apigee proverà a convalidare le credenziali client.
Il criterio OAuthV2 è composto da tre elementi che consentono di specificare i dati esterni da importare: <ExternalAccessToken>, <ExternalRefreshToken> e <ExternalAuthorizationCode>. Ognuno di questi elementi accetta una variabile di flusso. Il criterio di Apigee 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 la logica per inserire i token o i codici esterni nelle variabili appropriate.

Ad esempio, la seguente configurazione nel criterio OAuthV2 indica ad Apigee di cercare il token in una variabile di contesto denominata external_token.
```
<ExternalAccessToken>external_token</ExternalAccessToken>
```
Devi avere anche un passaggio precedente che imposti questa variabile.
Per quanto riguarda l'impostazione della variabile oauth_external_authorization_status, una tecnica comune per impostare questa variabile è l'utilizzo di 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>
```
Ricorda 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 dato che Apigee trova un valore del token nella variabile di flusso external_access_token.

<OAuthV2 name="OAuth-v20-Store-External-Token">
    <DisplayName>OAuth v2.0 1</DisplayName>
    <Attributes/>
    <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 autorizzazione delle credenziali client, devi fornire un'intestazione di autenticazione di base con il client ID e il client secret codificati. Tuttavia, in questo caso non è necessario fornire l'intestazione. Il criterio prevede comunque la presenza di client_id nella richiesta, che sarà convalidata dal criterio. Apigee si aspetta che il codice 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.