Utilizzo di token OAuth di terze parti

Stai visualizzando la documentazione di Apigee X.
Visualizza la documentazione di Apigee Edge.

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

Come di consueto, Apigee genera e archivia un token OAuth e lo restituisce all'applicazione chiamante. L'app chiamante poi presenta il token ad Apigee quando richiede il servizio e Apigee, tramite il criterio OAuthV2 con Operazione = VerificationAccessToken, verifica la validità del token. Questo argomento descrive come configurare Apigee per archiviare un token OAuth generato altrove, mantenendo invariata la parte della verifica del token, proprio come se il token fosse generato da Apigee.

Esempio

Se vuoi un esempio pratico che illustra la tecnica descritta in questo argomento, guarda l'esempio di gestione dei token con delega Apigee.

Che cos'è?

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

Alcune informazioni di base

Come di consueto, Apigee genera un token producendo una stringa casuale di lettere e numeri. Apigee associa al token, altri dati come l'ora in cui è stato emesso, la scadenza, l'elenco di prodotti API per cui il token è valido e l'ambito. Tutte queste informazioni possono essere restituite in una risposta generata automaticamente dal criterio OAuthV2 configurato con Operazione = generateAccessToken. La risposta sarà simile a questa:

{
  "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 connessione zBC90HhCGmGlaMBWeZAai2s3za5j. Utilizzando il valore del token, Apigee recupera i metadati del token per determinare se il token è valido o meno.

Seguendo la procedura descritta qui, puoi configurare Apigee per archiviare un token il cui valore access_token è stato generato da un servizio esterno. Ad esempio, supponiamo che tu abbia un sistema esterno ad Apigee che genera token nel formato "TOKEN-<16 numeri casuali". In tal 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, con il token di connessione TOKEN-1092837373654221, e Apigee potrà convalidarla. Puoi applicare un pattern di importazione simile ai codici di autorizzazione e ai token di aggiornamento.

Parliamo della convalida delle credenziali del client

Un prerequisito per la generazione di un token è la convalida del client richiedente. Per impostazione predefinita, il criterio OAuthV2/GenerateAccessToken in Apigee verifica implicitamente le credenziali del client. Normalmente, in una richiesta di token OAuthV2, i valori client_id e client_secret vengono passati nell'intestazione Authorization, codificati tramite l'Autorizzazione HTTP di base (concatenata dai due punti, quindi codifica Base64). Il criterio OAuthV2/GenerateAccessToken in Apigee decodifica l'intestazione e cerca client_id, nonché verifica che il valore client_secret inviato per tale client_id sia valido. Ciò funziona se le credenziali sono note a Apigee, ovvero è presente un'app per sviluppatori archiviata in Apigee che contiene una credenziale che a sua volta contiene i dati client_id e client_secret.

Nel caso in cui le credenziali client non vengano convalidate da Apigee, devi progettare il proxy API, prima che generi un token, per convalidare esplicitamente il client tramite altri mezzi. Spesso accade tramite un criterio callout per il servizio che si connette a un endpoint remoto nella 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 o che eseguano una o l'altra opzione oppure nessuna delle due.

Se vuoi che il criterio OAuthV2/GenerateAccessToken in Apigee convalida le credenziali del client rispetto all'archivio di 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 in modo esplicito 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, indicato da client_id. Pertanto, anche nel caso in cui il criterio OAuthV2/GenerateAccessToken in Apigee non convalida la corrispondenza di client_id e client_secret, il criterio convaliderà la validità di client_id, la presenza e la revoca. Quindi, come passaggio di configurazione prerequisito, potresti dover importare client_id's tramite l'API amministrativa Apigee.

Flusso dei criteri per OAuth di terze parti su Apigee

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

Convalida esterna delle credenziali del client

  1. ServiceCallout per verificare le credenziali del 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 vero per indicare che le credenziali del client sono valide.
  4. OAuthV2/GenerateAccessToken con l'elemento <ExternalAuthorization> impostato su true e almeno uno tra <ExternalAccessToken>, <ExternalRefreshToken> o <ExternalAuthorizationCode>.

Convalida interna delle credenziali del 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 sul flusso e sulla configurazione dei criteri

  • Nel caso in cui voglia utilizzare un sistema esterno per convalidare le credenziali del client, sta a te sviluppare un flusso di criteri che esegua tutte le operazioni necessarie. 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 callout dei servizi, il proxy API deve analizzare la risposta per estrarre lo stato di validità, oltre al access_token generato esternamente e possibilmente al refresh_token.

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

    Quando il criterio OAuthV2/GenerateAccessToken viene eseguito, 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 è vero, Apigee tenterà di convalidare le credenziali del client.

  • Il criterio OAuthV2 prevede 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 Apigee leggerà la variabile in modo da trovare il token di accesso, il token di aggiornamento o il codice di autorizzazione generati esternamente. Sta a te implementare criteri e 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>
    

    Dovresti anche avere un passaggio precedente che imposta la variabile.

  • Per quanto riguarda l'impostazione della variabile oauth_external_authorization_status, una tecnica comune per impostare questa variabile consiste nell'utilizzare un criterio MessageMessage con l'elemento GiveVariable, come questo:

    <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 rientrare nel criterio OAuthV2 con un'operazione = GenerationAccessToken.

Esempio di criterio OAuthV2

Il seguente criterio OAuthV2 genera un token di accesso, in quanto Apigee rileva 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, puoi applicare questo pattern a qualsiasi servizio di autorizzazione OAuth2 di terze parti.