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, vedremo come importare token di accesso, token di aggiornamento o codici di autorizzazione generati esternamente nell'archivio token Apigee. Puoi utilizzare questa tecnica se vuoi configurare Apigee per convalidare i token generati al di fuori di Apigee.

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

Esempio

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

Che cos'è?

Supponiamo che tu abbia un sistema di autorizzazione esistente e che tu voglia utilizzare i valori di token o codice generati da questo sistema al posto dei valori di token o codice OAuth2 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.

Un po' di contesto

Nel caso normale, Apigee genera un token producendo una stringa casuale di lettere e numeri. Apigee associa a questo 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 dalla policy OAuthV2 configurata con Operation = GenerateAccessToken. La risposta è 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, supponiamo che una richiesta proxy API includa il token di autenticazione zBC90HhCGmGlaMBWeZAai2s3za5j. Utilizzando il valore del token, Apigee recupera i metadati del token per determinare se il token è valido o meno.

Se segui i passaggi descritti qui, puoi configurare Apigee in modo che memorizzi 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 completi del token 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, con il token di autenticazione TOKEN-1092837373654221, e Apigee 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 generare un token è la convalida del client richiedente. Per impostazione predefinita, i criteri OAuthV2/GenerateAccessToken in Apigee verificano implicitamente le credenziali client. Normalmente, in una richiesta di token OAuthV2, client_id e client_secret vengono passati nell'intestazione Authorization, codificata tramite l'autorizzazione di base HTTP (concatenata con i due punti, poi codificata in base64). Il criterio OAuthV2/GenerateAccessToken in Apigee decodifica l'intestazione e cerca client_id e verifica che client_secret passato sia valido per client_id. Questa operazione funziona se le credenziali sono note ad Apigee, ovvero se in Apigee è archiviata un'app per sviluppatori che contiene una credenziale, la quale a sua volta contiene il client_id e il client_secret forniti.

Nel caso in cui le credenziali client non debbano essere convalidate da Apigee, devi progettare il proxy API, prima che generi un token, per convalidare esplicitamente il client con altri mezzi. Spesso questo avviene tramite una policy ServiceCallout che si connette a un endpoint remoto nella tua rete.

In un modo o nell'altro, implicitamente o esplicitamente, devi assicurarti che il proxy API che genera i token convalidi prima le credenziali 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, o una o l'altra, o nessuna delle due.

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

Anche se Apigee potrebbe non convalidare le credenziali client, è comunque necessario che client_id sia noto e gestito da Apigee. Ogni access_token in Apigee, generato da Apigee o da un sistema esterno e poi importato in Apigee, deve essere associato a un'applicazione client, indicata da client_id. Pertanto, anche nel caso in cui la norma OAuthV2/GenerateAccessToken in Apigee non convalidi la corrispondenza tra client_id e client_secret, la norma convaliderà che client_id sia valido, presente e non revocato. Pertanto, come passaggio di configurazione preliminare, potrebbe essere necessario importare client_id tramite l'API amministrativa di Apigee.

Flusso dei 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 seguenti pattern.

Esterna Convalida delle credenziali client

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

Interna Convalida delle credenziali client

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

Note sulla configurazione del flusso e delle norme

  • Se vuoi utilizzare un sistema esterno per convalidare le credenziali client, spetta a te sviluppare un flusso di criteri che faccia ciò che è necessario. In genere utilizzi un criterio ServiceCallout per inviare le credenziali riconosciute esternamente al servizio di autenticazione esterno. Il servizio di autenticazione esterno in genere restituisce una risposta e, se le credenziali sono valide, anche un token di accesso.

  • Dopo ServiceCallout, il proxy API deve analizzare la risposta per estrarre lo stato di validità, nonché l'access_token generato esternamente e, possibilmente, il refresh_token.

  • Nel criterio OAuthV2/GenerateAccessToken, imposta l'elemento <StoreToken> su true e l'elemento <ExternalAuthorization> su true o false, a seconda dei casi.

    Quando viene eseguita la policy OAuthV2/GenerateAccessToken, viene letta la variabile oauth_external_authorization_status. Se la variabile è impostata e il valore è true, Apigee non tenta di convalidare le credenziali client. Se la variabile non è impostata o il valore non è true, Apigee tenterà di convalidare le credenziali del client.

  • Esistono tre elementi per il criterio OAuthV2 che ti consentono di specificare i dati esterni da importare: <ExternalAccessToken>, <ExternalRefreshToken> e <ExternalAuthorizationCode>. Ciascuno di questi elementi accetta una variabile di flusso. Il criterio Apigee leggerà questa variabile per trovare il token di accesso, il token di aggiornamento o il codice di autorizzazione generato esternamente. Spetta a te implementare le norme 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 anche avere un passaggio precedente che imposti la variabile.

  • Per quanto riguarda l'impostazione della variabile oauth_external_authorization_status, una tecnica comune per impostarla è utilizzare una policy AssignMessage con l'elemento AssignVariable, 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 essere precedente al criterio OAuthV2 con Operation = GenerateAccessToken.

Esempio di policy 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 teoria, potresti applicare questo pattern con qualsiasi servizio di autorizzazione OAuth2 di terze parti.