Criterio OAuthV2

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

Cosa

OAuthV2 è un criterio sfaccettato per l'esecuzione di operazioni relative ai tipi di concessione OAuth 2.0. Si tratta del criterio principale utilizzato per configurare gli endpoint OAuth 2.0 su Apigee Edge.

Suggerimento:per scoprire di più su OAuth su Apigee Edge, consulta la home page di OAuth. Fornisce link a risorse, esempi, video e altro ancora. Consulta l'esempio di OAuth avanzato su GitHub per una dimostrazione efficace di come questo criterio viene utilizzato in un'applicazione funzionante.

Samples

<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuth-v20-2">
    <DisplayName>OAuth v2.0 2</DisplayName>
    <Operation>VerifyAccessToken</Operation>
    <AccessTokenPrefix>Bearer</AccessTokenPrefix> <!-- Optional, default is Bearer -->
</OAuthV2>

$ curl -H "Authorization: Bearer ylSkZIjbdWybfsUQe9BqP0LH5Z" http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282

<OAuthV2 enabled="true" continueOnError="false" async="false" name="generateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <AppEndUser>Doe</AppEndUser>
    <UserName>jdoe</UserName>
    <PassWord>jdoe</PassWord>
    <GrantType>grant_type</GrantType>
    <ClientId>a_valid_client_id</ClientId>
    <SupportedGrantTypes>
        <GrantType>password</GrantType>
    </SupportedGrantTypes>
</OAuthV2>

var client_id = context.getVariable("local_clientid");
var client_secret = context.getVariable("local_secret");
context.setVariable("request.header.Authorization","Basic "+CryptoJS.enc.Base64.stringify(CryptoJS.enc.Latin1
                                      .parse(client_id + ':' + client_secret)));

Vedi anche "Codificare le credenziali di autenticazione di base".

Riferimento elemento

Il riferimento ai criteri descrive gli elementi e gli attributi dei criteri OAuthV2.

Il criterio di esempio mostrato di seguito è una delle tante configurazioni possibili. Questo esempio mostra un criterio OAuthV2 configurato per l'operazione GenerateAccessToken. Include elementi obbligatori e facoltativi. Per maggiori dettagli, consulta le descrizioni degli elementi in questa sezione.

<OAuthV2 name="GenerateAccessToken">
  <!-- This policy generates an OAuth 2.0 access token using the client_credentials grant type -->
  <Operation>GenerateAccessToken</Operation>
  <!-- This is in millseconds, so expire in an hour -->
  <ExpiresIn>3600000</ExpiresIn>
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GrantType>request.queryparam.grant_type</GrantType>
  <GenerateResponse/>
</OAuthV2>

Attributi <OAuthV2>

<OAuthV2 async="false" continueOnError="false" enabled="true" name="MyOAuthPolicy">

La tabella seguente descrive gli attributi comuni a tutti gli elementi principali del criterio:

&lt;DisplayName&gt; elemento

Da utilizzare in aggiunta all'attributo name per etichettare il criterio in editor proxy della UI di gestione con un nome diverso e in linguaggio naturale.

<DisplayName>Policy Display Name</DisplayName>

Elemento <AccessToken>

<AccessToken>request.header.access_token</AccessToken>

Per impostazione predefinita, VerifyAccessToken si aspetta che il token di accesso venga inviato nell'intestazione Authorization. Puoi modificare il valore predefinito utilizzando questo elemento. Ad esempio, request.queryparam.access_token indica che il token di accesso deve essere presente come un parametro di query denominato access_token.

curl https://myorg-myenv.apigee.net/oauth2/validate -H "access_token:Rft3dqrs56Blirls56a"

curl "https://myorg-myenv.apigee.net/oauth2/validate?access_token:Rft3dqrs56Blirls56a"

Elemento <AccessTokenPrefix>

<AccessTokenPrefix>Bearer</AccessTokenPrefix>

Per impostazione predefinita, VerifyAccessToken si aspetta che il token di accesso venga inviato in un'intestazione Authorization come token Bearer. Ad esempio:

-H "Authorization: Bearer Rft3dqrs56Blirls56a"

Al momento, Bearer è l'unico prefisso supportato.

Elemento <AppEndUser>

<AppEndUser>request.queryparam.app_enduser</AppEndUser>

Nei casi in cui l'ID utente finale dell'app debba essere inviato al server di autorizzazione, questo elemento consente di specificare dove Edge deve cercare l'ID utente finale. Ad esempio, potrebbe essere inviato come parametro di query o in un'intestazione HTTP.

Ad esempio, request.queryparam.app_enduser indica che AppEndUser deve essere presente come parametro di query, ad esempio ?app_enduser=ntesla@theramin.com. Ad esempio, per richiedere AppEndUser in un'intestazione HTTP, imposta questo valore su request.header.app_enduser.

Se fornisci questa impostazione, puoi includere un ID utente finale dell'app nel token di accesso. Questa funzionalità è utile se vuoi poter recuperare o revocare i token di accesso OAuth 2.0 in base all'ID utente finale. Per ulteriori informazioni, consulta Attivare il recupero e la revoca dei token di accesso OAuth 2.0 in base all'ID utente finale, all'ID app o a entrambi.

<Attributes/Attribute>

<Attributes>
    <Attribute name="attr_name1" ref="flow.variable" display="true|false">value1</Attribute>
    <Attribute name="attr_name2" ref="flow.variable" display="true|false">value2</Attribute>
</Attributes>

Utilizza questo elemento per aggiungere attributi personalizzati a un token di accesso o a un codice di autorizzazione. Ad esempio, potresti voler incorporare un ID utente o un identificatore di sessione in un token di accesso che possa essere estratto e verificato in fase di runtime.

Questo elemento consente di specificare un valore in una variabile di flusso o da una stringa letterale. Se specifichi sia una variabile che una stringa, viene utilizzato il valore specificato nella variabile del flusso. Se la variabile non può essere risolta, la stringa è predefinita.

Per ulteriori informazioni sull'utilizzo di questo elemento, consulta Personalizzare i token e i codici di autorizzazione.

Mostrare o nascondere gli attributi personalizzati nella risposta

Ricorda che se imposti l'elemento GenerateResponse di questo criterio su true, la rappresentazione JSON completa del token viene restituita nella risposta, inclusi eventuali attributi personalizzati impostati. In alcuni casi, potresti voler nascondere alcuni o tutti gli attributi personalizzati nella risposta in modo che non siano visibili alle app client.

Per impostazione predefinita, gli attributi personalizzati vengono visualizzati nella risposta. Se vuoi nasconderli, puoi impostare il parametro display su false. Ad esempio:

<Attributes>
    <Attribute name="employee_id" ref="employee.id" display="false"/>
    <Attribute name="employee_name" ref="employee.name" display="false"/>
</Attributes>

Il valore dell'attributo display non viene conservato. Supponiamo che tu generi un token di accesso con attributi personalizzati che vuoi nascondere nella risposta generata. L'impostazione display=false consente di raggiungere questo obiettivo. Tuttavia, se in un secondo momento viene generato un nuovo token di accesso utilizzando un token di aggiornamento, gli attributi personalizzati originali del token di accesso verranno visualizzati nella risposta del token di aggiornamento. Questo accade perché Edge non ricorda che l'attributo display è stato impostato originariamente su false nel criterio di generazione del token di accesso. L'attributo personalizzato fa semplicemente parte dei metadati del token di accesso.

Il comportamento sarà lo stesso se aggiungi attributi personalizzati a un codice di autorizzazione. Quando viene generato un token di accesso utilizzando questo codice, questi attributi personalizzati vengono visualizzati nella risposta del token di accesso. Anche in questo caso, questo potrebbe non essere il comportamento che intendi.

Per nascondere gli attributi personalizzati in questi casi, hai a disposizione le seguenti opzioni:

• Reimposta esplicitamente gli attributi personalizzati nel criterio del token di aggiornamento e imposta la loro visualizzazione su false. In questo caso, potrebbe essere necessario recuperare i valori personalizzati originali dall'attributo access token originale utilizzando il criterio GetOAuthV2Info.
• Utilizza un criterio JavaScript di post-elaborazione per estrarre manualmente gli attributi personalizzati che non vuoi visualizzare nella risposta.

Consulta anche Personalizzare token e codici di autorizzazione.

Elemento <ClientId>

<ClientId>request.formparam.client_id</ClientId>

In diversi casi, l'app client deve inviare l'ID client al server di autorizzazione. Questo elemento specifica che Apigee deve cercare l'ID cliente nella variabile di flusso request.formparam.client_id. L'impostazione di ClientId su qualsiasi altra variabile non è supportata. Vedi anche Richiedere token di accesso e codici di autorizzazione.

Elemento <Code>

<Code>request.queryparam.code</Code>

Nel flusso del tipo di concessione dell'autorizzazione, il client deve inviare un codice di autorizzazione al server di autorizzazione (Apigee Edge). Questo elemento consente di specificare dove Edge deve cercare il codice di autorizzazione. Ad esempio, può essere inviato come parametro di query, intestazione HTTP o parametro del modulo (valore predefinito).

La variabile request.queryparam.auth_code indica che il codice di autorizzazione deve essere presente come parametro di query, ad esempio ?auth_code=AfGlvs9. Ad esempio, per richiedere il codice di autorizzazione in un'intestazione HTTP, imposta questo valore su request.header.auth_code. Vedi anche Richiedere token di accesso e codici di autorizzazione.

Elemento<ExpiresIn>

<ExpiresIn>10000</ExpiresIn> 

Applica la data e l'ora di scadenza dei token di accesso e dei codici di autorizzazione in millisecondi. Per i token di aggiornamento, utilizza <RefreshTokenExpiresIn>. Il valore dell'ora di scadenza è un valore generato dal sistema più il valore <ExpiresIn>. Se <ExpiresIn> è impostato su -1, il token o il codice scade in base alla scadenza massima del token di accesso OAuth. Se <ExpiresIn> non è specificato, il sistema applica un valore predefinito configurato a livello di sistema.

La data e l'ora di scadenza possono essere impostate anche in fase di esecuzione utilizzando un valore predefinito hardcoded o facendo riferimento a una variabile di flusso. Ad esempio, puoi memorizzare un valore di scadenza del token in una mappa di valori chiave, recuperarlo, assegnarlo a una variabile e farvi riferimento nel criterio. Ad esempio, kvm.oauth.expires_in.

Con Apigee Edge for Public Cloud, Edge memorizza nella cache le seguenti entità per un minimo di 180 secondi dopo l'accesso.

• Token di accesso OAuth. Ciò significa che un token revocato potrebbe comunque essere valido per un massimo di tre minuti, fino alla scadenza del limite della cache.
• Entità Key Management Service (KMS) (app, sviluppatori, prodotti API).
• Attributi personalizzati sui token OAuth e sulle entità KMS.

La stanza seguente specifica una variabile di flusso e anche un valore predefinito. Tieni presente che il valore della variabile di flusso ha la precedenza sul valore predefinito specificato.

<ExpiresIn ref="kvm.oauth.expires_in">
    3600000 <!--default value in milliseconds-->
</ExpiresIn>

Edge non supporta un modo per forzare la scadenza di un token dopo la sua creazione. Se devi forzare la scadenza del token (ad esempio in base a una condizione), una possibile soluzione è stata descritta in questo post della community di Apigee.

Per impostazione predefinita, i token di accesso scaduti vengono eliminati automaticamente dal sistema Apigee Edge 3 giorni dopo la scadenza. Vedi anche Eliminazione dei token di accesso

Private Cloud: per un'installazione Edge per il cloud privato, il valore predefinito è impostato dalla proprietà conf_keymanagement_oauth_auth_code_expiry_time_in_millis. Per impostare questa proprietà:

1. Apri il file message-processor.properties in un editor. Se il file non esiste, creane uno:

   vi /opt/apigee/customer/application/message-processor.properties

2. Imposta la proprietà come preferisci:

   conf_keymanagement_oauth_auth_code_expiry_time_in_millis=3600000

3. Assicurati che il file delle proprietà sia di proprietà dell'utente "apigee":

   chown apigee:apigee /opt/apigee/customer/application/message-processor.properties

4. Riavvia il processore di messaggi.

   /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

Elemento <ExternalAccessToken>

<ExternalAccessToken>request.queryparam.external_access_token</ExternalAccessToken>

Indica ad Apigee Edge dove trovare un token di accesso esterno (un token di accesso non generato da Apigee Edge).

La variabile request.queryparam.external_access_token indica che il token di accesso esterno deve essere presente come parametro di query, ad esempio ?external_access_token=12345678. Ad esempio, per richiedere il token di accesso esterno in un'intestazione HTTP, imposta questo valore su request.header.external_access_token. Consulta anche l'articolo sull'utilizzo di token OAuth di terze parti.

Elemento <ExternalAuthorization>

<ExternalAuthorization>true</ExternalAuthorization>

Se questo elemento è falso o non è presente, Edge convalida client_id e client_secret normalmente rispetto allo store di autorizzazione di Apigee Edge. Utilizza questo elemento quando vuoi utilizzare token OAuth di terze parti. Per informazioni dettagliate sull'utilizzo di questo elemento, consulta Utilizzare i token OAuth di terze parti.

Elemento <ExternalAuthorizationCode>

<ExternalAuthorizationCode>request.queryparam.external_auth_code</ExternalAuthorizationCode>

Indica ad Apigee Edge dove trovare un codice di autenticazione esterno (un codice di autenticazione non generato da Apigee Edge).

La variabile request.queryparam.external_auth_code indica che il codice di autorizzazione esterno deve essere presente come parametro di query, ad esempio ?external_auth_code=12345678. Ad esempio, per richiedere il codice di autorizzazione esterno in un'intestazione HTTP, imposta questo valore su request.header.external_auth_code. Consulta anche Utilizzare i token OAuth di terze parti.

Elemento <ExternalRefreshToken>

<ExternalRefreshToken>request.queryparam.external_refresh_token</ExternalRefreshToken>

Indica ad Apigee Edge dove trovare un token di aggiornamento esterno (un token di aggiornamento non generato da Apigee Edge).

La variabile request.queryparam.external_refresh_token indica che il token di aggiornamento esterno deve essere presente come parametro di query, ad esempio ?external_refresh_token=12345678. Ad esempio, per richiedere il token di aggiornamento esterno in un'intestazione HTTP, imposta questo valore su request.header.external_refresh_token. Consulta anche Utilizzare i token OAuth di terze parti.

Elemento <GenerateResponse>

<GenerateResponse enabled='true'/>

Se viene impostato su true, il criterio genera e restituisce una risposta. Ad esempio, per CreateAccessToken, la risposta potrebbe essere simile a:

{
  "issued_at" : "1467841035013",
  "scope" : "read",
  "application_name" : "e31b8d06-d538-4f6b-9fe3-8796c11dc930",
  "refresh_token_issued_at" : "1467841035013",
  "status" : "approved",
  "refresh_token_status" : "approved",
  "api_product_list" : "[Product1, nhl_product]",
  "expires_in" : "1799",
  "developer.email" : "edward@slalom.org",
  "token_type" : "BearerToken",
  "refresh_token" : "rVSmm3QaNa0xBVFbUISz1NZI15akvgLJ",
  "client_id" : "Adfsdvoc7KX5Gezz9le745UEql5dDmj",
  "access_token" : "AnoHsh2oZ6EFWF4h0KrA0gC5og3a",
  "organization_name" : "cerruti",
  "refresh_token_expires_in" : "0",
  "refresh_count" : "0"
}

Se false, non viene inviata alcuna risposta. Viene invece compilato un insieme di variabili di flusso con valori correlati alla funzione del criterio. Ad esempio, una variabile di flusso denominata oauthv2authcode.OAuthV2-GenerateAuthorizationCode.code viene compilata con il codice di autenticazione appena creato. Tieni presente che il valore di expires_in è espresso in secondi nella risposta.

Elemento <GenerateErrorResponse>

<GenerateErrorResponse enabled='true'/>

Se viene impostato su true, il criterio genera e restituisce una risposta se l'attributo ContinueOnError è impostato su true. Se false (il valore predefinito), non viene inviata alcuna risposta. Un insieme di variabili di flusso viene invece compilato con i valori correlati alla funzione del criterio.

<GrantType>

<GrantType>request.queryparam.grant_type</GrantType>

Indica al criterio dove trovare il parametro del tipo di concessione passato in una richiesta. In base alla specifica OAuth 2.0, il tipo di concessione deve essere fornito con le richieste di token di accesso e codici di autorizzazione. La variabile può essere un'intestazione, un parametro di query o un parametro di modulo (valore predefinito).

Ad esempio, request.queryparam.grant_type indica che la password deve essere presente come parametro di query, ad esempio ?grant_type=password. Ad esempio, per richiedere il tipo di concessione in un'intestazione HTTP, imposta questo valore su request.header.grant_type. Vedi anche Richiesta di token di accesso e codici di autorizzazione.

Elemento <Operation>

<Operation>GenerateAuthorizationCode</Operation>

L'operazione OAuth 2.0 eseguita dal criterio.

Elemento <PassWord>

<PassWord>request.queryparam.password</PassWord>

Questo elemento viene utilizzato solo con il tipo di autorizzazione con password. Con il tipo di concessione della password, le credenziali utente (password e nome utente) devono essere rese disponibili per il criterio OAuthV2. Gli elementi <PassWord> e <UserName> vengono utilizzati per specificare le variabili in cui Edge può trovare questi valori. Se questi elementi non sono specificati, il criterio si aspetta di trovare i valori (per impostazione predefinita) nei parametri del modulo denominati username e password. Se i valori non vengono trovati, il criterio genera un errore. Puoi utilizzare gli elementi <PassWord> e <UserName> per fare riferimento a qualsiasi variabile di flusso contenente le credenziali.

Ad esempio, puoi passare la password in una richiesta di token utilizzando un parametro di query e impostare l'elemento come segue: <PassWord>request.queryparam.password</PassWord>. Per richiedere la password in un'intestazione HTTP, imposta questo valore su request.header.password.

Il criterio OAuthV2 non esegue altre operazioni con questi valori delle credenziali; Edge si limita a verificare che siano presenti. Spetta allo sviluppatore dell'API recuperare la richiesta di valori e inviarli a un provider di identità prima dell'esecuzione del criterio di generazione del token.

Vedi anche Richiedere token di accesso e codici di autorizzazione.

Elemento <RedirectUri>

<RedirectUri>request.queryparam.redirect_uri</RedirectUri>

Specifica dove Edge deve cercare il parametro redirect_uri nella richiesta.

Informazioni sugli URI di reindirizzamento

Gli URI di reindirizzamento vengono utilizzati con il codice di autorizzazione e i tipi di autorizzazione impliciti. L'URI di reindirizzamento indica al server di autorizzazione (Edge) dove inviare un codice di autorizzazione (per il tipo di autorizzazione del codice di autorizzazione) o un token di accesso (per il tipo di autorizzazione implicita). È importante capire quando questo parametro è obbligatorio, quando è facoltativo e come viene utilizzato:

• (obbligatorio) Se un URL di callback è registrato nell'app per sviluppatori associata alle chiavi client della richiesta e se redirect_uri è presente nella richiesta, i due elementi devono corrispondere esattamente. Se non corrispondono, viene restituito un errore. Per informazioni sulla registrazione delle app per sviluppatori su Edge e sulla specifica di un URL di callback, consulta Registrare le app e gestire le chiavi API.

• (Facoltativo) Se è registrato un URL di callback e redirect_uri non è presente nella richiesta, Edge reindirizza all'URL di callback registrato.
• (obbligatorio) Se non è registrato un URL di callback, redirect_uri è obbligatorio. Tieni presente che in questo caso Edge accetterà QUALSIASI URL. Questo caso può presentare un problema di sicurezza e pertanto deve essere utilizzato solo con app client attendibili. Se le app client non sono attendibili, la best practice è richiedere sempre la registrazione di un URL di callback.

Puoi inviare questo parametro in un parametro di query o in un'intestazione. La variabile request.queryparam.redirect_uri indica che RedirectUri deve essere presente come parametro di query, ad esempio ?redirect_uri=login.myapp.com. Per richiedere RedirectUri in un'intestazione HTTP, ad esempio, imposta questo valore su request.header.redirect_uri. Consulta anche Richiedere token di accesso e codici di autorizzazione.

Elemento <RefreshToken>

<RefreshToken>request.queryparam.refreshtoken</RefreshToken>

Quando richiedi un token di accesso utilizzando un token di aggiornamento, devi fornire il token di aggiornamento nella richiesta. Questo elemento consente di specificare dove Edge deve cercare il token di aggiornamento. Ad esempio, può essere inviato come parametro di query, intestazione HTTP o parametro di modulo (valore predefinito).

La variabile request.queryparam.refreshtoken indica che il token di aggiornamento deve essere presente come parametro di query, ad esempio ?refresh_token=login.myapp.com. Ad esempio, per richiedere il token di aggiornamento in un'intestazione HTTP, imposta questo valore su request.header.refresh_token. Vedi anche Richiesta di token di accesso e codici di autorizzazione.

Elemento <RefreshTokenExpiresIn>

<RefreshTokenExpiresIn>1000</RefreshTokenExpiresIn>

Applica la scadenza dei token di aggiornamento in millisecondi. Il valore della data e dell'ora di scadenza è un valore generato dal sistema più il valore <RefreshTokenExpiresIn>. Se <RefreshTokenExpiresIn> è impostato su -1, il token di aggiornamento scade in base alla scadenza massima del token di aggiornamento OAuth. Se <RefreshTokenExpiresIn> non è specificato, il sistema applica un valore predefinito configurato a livello di sistema. Contatta l'assistenza Apigee Edge per ulteriori informazioni sulle impostazioni di sistema predefinite.

La data e l'ora di scadenza possono essere impostate anche in fase di esecuzione utilizzando un valore predefinito hardcoded o facendo riferimento a una variabile di flusso. Ad esempio, puoi memorizzare un valore di scadenza del token in una mappa di valori chiave, recuperarlo, assegnarlo a una variabile e farvi riferimento nel criterio. Ad esempio, kvm.oauth.expires_in.

La stanza seguente specifica una variabile di flusso e un valore predefinito. Tieni presente che il valore della variabile flow ha la precedenza sul valore predefinito specificato.

<RefreshTokenExpiresIn ref="kvm.oauth.expires_in">
    3600000 <!--default value in milliseconds-->
</RefreshTokenExpiresIn>

Private Cloud: per un'installazione di Edge per Private Cloud, il valore predefinito è impostato dalla proprietà conf_keymanagement_oauth_refresh_token_expiry_time_in_millis. Per impostare questa proprietà:

1. Apri il file message-processor.properties in un editor. Se il file non esiste, creane uno:

   vi /opt/apigee/customer/application/message-processor.properties

2. Imposta la proprietà come preferisci:

   conf_keymanagement_oauth_refresh_token_expiry_time_in_millis=3600000

3. Assicurati che il file delle proprietà sia di proprietà dell'utente "apigee":

   chown apigee:apigee /opt/apigee/customer/application/message-processor.properties

4. Riavvia il processore di messaggi.

   /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

Elemento <ResponseType>

<ResponseType>request.queryparam.response_type</ResponseType>

Questo elemento indica a Edge il tipo di concessione richiesto dall'app client. Viene utilizzato solo con i flussi del codice di autorizzazione e del tipo di autorizzazione implicita.

Per impostazione predefinita, Edge cerca il valore del tipo di risposta in un parametro della query response_type. Se vuoi ignorare questo comportamento predefinito, utilizza l'elemento <ResponseType> per configurare una variabile di flusso contenente il valore del tipo di risposta. Ad esempio, se imposti questo elemento su request.header.response_type, Edge cerca il tipo di risposta da passare nell'intestazione della richiesta. Vedi anche Richiedere token di accesso e codici di autorizzazione.

Elemento <ReuseRefreshToken>

<ReuseRefreshToken>true</ReuseRefreshToken>

Se impostato su true, il token di aggiornamento esistente viene riutilizzato fino alla scadenza. Se false, Apigee Edge emette un nuovo token di aggiornamento quando viene presentato un token di aggiornamento valido.

Elemento <Scope>

<Scope>request.queryparam.scope</Scope>

Se questo elemento è presente in uno dei criteri GenerateAccessToken o GenerateAuthorizationCode, viene utilizzato per specificare gli ambiti a cui concedere il token o il codice. Questi valori vengono solitamente trasmessi al criterio nella richiesta da un'app client. Puoi configurare l'elemento in modo che accetti una variabile di flusso, dandoti la possibilità di scegliere in che modo gli ambiti vengono trasmessi in una richiesta. Nel seguente esempio, request.queryparam.scope indica che l'ambito deve essere presente come parametro di query, ad esempio ?scope=READ. Per richiedere l'ambito in un'intestazione HTTP, ad esempio, imposta questo valore su request.header.scope.

Se questo elemento viene visualizzato in un criterio "VerifyAccessToken", viene utilizzato per specificare gli ambiti che il criterio deve applicare. In questo tipo di criterio, il valore deve essere un nome di ambito "hard coded", non puoi utilizzare variabili. Ad esempio:

<Scope>A B</Scope>

Vedi anche Utilizzo degli ambiti OAuth2 e Richiesta di token di accesso e codici di autorizzazione.

Elemento <State>

<State>request.queryparam.state</State>

Nei casi in cui l'app client deve inviare le informazioni sullo stato al server di autorizzazione, questo elemento consente di specificare dove Edge deve cercare i valori dello stato. Ad esempio, potrebbe essere inviato come parametro di query o in un'intestazione HTTP. Il valore dello stato viene in genere utilizzato come misura di sicurezza per impedire attacchi CSRF.

Ad esempio, request.queryparam.state indica che lo stato deve essere presente come parametro di query, ad esempio ?state=HjoiuKJH32. Per richiedere lo stato in un'intestazione HTTP, ad esempio, imposta questo valore su request.header.state. Vedi anche Richiedere token di accesso e codici di autorizzazione.

Elemento <StoreToken>

 <StoreToken>true</StoreToken> 

Imposta questo elemento su true quando l'elemento <ExternalAuthorization> è true. L'elemento <StoreToken> indica ad Apigee Edge di memorizzare il token di accesso esterno. In caso contrario, non verrà mantenuto.

Elemento <SupportedGrantTypes>/<GrantType>

<SupportedGrantTypes>
    <GrantType>authorization_code</GrantType>
    <GrantType>client_credentials</GrantType>
    <GrantType>implicit</GrantType>
    <GrantType>password</GrantType>
</SupportedGrantTypes>

Specifica i tipi di concessione supportati da un endpoint del token OAuth su Apigee Edge. Un endpoint potrebbe supportare più tipi di autorizzazione (ovvero, un singolo endpoint può essere configurato per distribuire i token di accesso per più tipi di autorizzazione). Per saperne di più sugli endpoint, consulta Informazioni sugli endpoint OAuth. Il tipo di concessione viene passato nelle richieste di token in un parametro grant_type.

Se non vengono specificati tipi di concessione supportati, gli unici tipi di concessione consentiti sono authorization_code e implicit. Vedi anche l'elemento <GrantType> (un elemento di livello superiore utilizzato per specificare dove Apigee Edge deve cercare il parametro grant_type che viene passato in una richiesta del client). Edge si assicurerà che il valore del parametro grant_type sia uguale a uno dei tipi di concessione supportati.

Elemento <Tokens>/<Token>

Utilizzato con le operazioni ValidateToken e InvalidateToken. Consulta anche Approvare e revocare i token di accesso. L'elemento <Token> identifica la variabile di flusso che definisce l'origine del token da revocare. Se gli sviluppatori devono inviare token di accesso come parametri di query denominati access_token, ad esempio, devono utilizzare request.queryparam.access_token.

Elemento <UserName>

<UserName>request.queryparam.user_name</UserName>

Questo elemento viene utilizzato solo con il tipo di autorizzazione con password. Con il tipo di concessione della password, le credenziali utente (password e nome utente) devono essere rese disponibili per il criterio OAuthV2. Gli elementi <PassWord> e <UserName> vengono utilizzati per specificare le variabili in cui Edge può trovare questi valori. Se questi elementi non sono specificati, il criterio si aspetta di trovare i valori (per impostazione predefinita) nei parametri del modulo denominati username e password. Se i valori non vengono trovati, il criterio genera un errore. Puoi utilizzare gli elementi <PassWord> e <UserName> per fare riferimento a qualsiasi variabile di flusso contenente le credenziali.

Ad esempio, puoi passare il nome utente in un parametro di query e impostare l'elemento <UserName> in questo modo: <UserName>request.queryparam.username</UserName>.Per richiedere il nome utente in un'intestazione HTTP, imposta questo valore su request.header.username.

Il criterio OAuthV2 non esegue altre operazioni con questi valori delle credenziali; Edge si limita a verificare che siano presenti. Spetta allo sviluppatore dell'API recuperare la richiesta di valori e inviarli a un provider di identità prima dell'esecuzione del criterio di generazione del token.

Vedi anche Richiedere token di accesso e codici di autorizzazione.

Verifica dei token di accesso

Una volta configurato un endpoint token per un proxy API, un criterio OAuthV2 corrispondente che specifica l'operazione VerifyAccessToken viene associato al flusso che espone la risorsa protetta.

Ad esempio, per garantire che tutte le richieste a un'API siano autorizzate, il seguente criterio applica la verifica dei token di accesso:

<OAuthV2 name="VerifyOAuthAccessToken">
  <Operation>VerifyAccessToken</Operation>
</OAuthV2>

Il criterio è associato alla risorsa API da proteggere. Per assicurarti che tutte le richieste a un'API siano verificate, collega il criterio al PreFlow della richiesta ProxyEndpoint, come segue:

<PreFlow>
  <Request>
    <Step><Name>VerifyOAuthAccessToken</Name></Step>
  </Request>
</PreFlow>

I seguenti elementi facoltativi possono essere utilizzati per eseguire l'override delle impostazioni predefinite per l'operazione VerifyAccessToken.

<OAuthV2 name="ValidateOauthScopePolicy">
  <Operation>VerifyAccessToken</Operation>
  <Scope>READ WRITE</Scope>
</OAuthV2>

Vedi anche Verificare i token di accesso e Richiedere token di accesso e codici di autorizzazione.

Specificare le posizioni delle variabili di richiesta

Per ogni tipo di autorizzazione, il criterio fa ipotesi sulla posizione o sulle informazioni richieste nei messaggi di richiesta. Queste ipotesi si basano sulla specifica OAuth 2.0. Se le tue app devono discostarsi dalla specifica OAuth 2.0, puoi specificare le posizioni previste per ciascun parametro. Ad esempio, quando gestisci un codice di autorizzazione, puoi specificare la posizione del codice di autorizzazione, l'ID cliente, l'URI di reindirizzamento e l'ambito. Questi possono essere specificati come intestazioni HTTP, parametri di query o parametri di modulo.

L'esempio seguente mostra come specificare la posizione dei parametri obbligatori del codice di autorizzazione come intestazioni HTTP:

  ...
  <GrantType>request.header.grant_type</GrantType>
  <Code>request.header.code</Code>
  <ClientId>request.header.client_id</ClientId>
  <RedirectUri>request.header.redirect_uri</RedirectUri>
  <Scope>request.header.scope</Scope>
  ...

In alternativa, se necessario per supportare la base di app client, puoi combinare intestazioni e parametri di query:

  ...
  <GrantType>request.header.grant_type</GrantType>
  <Code>request.header.code</Code>
  <ClientId>request.queryparam.client_id</ClientId>
  <RedirectUri>request.queryparam.redirect_uri</RedirectUri>
  <Scope>request.queryparam.scope</Scope>
  ...

È possibile configurare una sola località per parametro.

Variabili di flusso

Le variabili di flusso definite in questa tabella vengono compilate quando vengono eseguiti i rispettivi criteri OAuth e, di conseguenza, sono disponibili per altri criteri o applicazioni in esecuzione nel flusso del proxy API.

Operazione VerifyAccessToken

Viene eseguita l'operazione VerifyAccessToken; un numero elevato di variabili di flusso vengono compilate nel contesto di esecuzione del proxy. Queste variabili forniscono proprietà relative al token di accesso, all'app sviluppatore, allo sviluppatore e all'azienda. Ad esempio, puoi utilizzare un criterio AssignMessage o JavaScript per leggere una di queste variabili e utilizzarla in base alle esigenze in un secondo momento nel flusso. Queste variabili possono essere utili anche per scopi di debug.

Variabili specifiche per token

Variabili specifiche per l'app

Queste variabili sono correlate all'app per sviluppatori associata al token.

Variabili specifiche per lo sviluppatore

Se app.appType è "Company", vengono compilati gli attributi dell'azienda e se app.appType è "Developer", vengono compilati gli attributi dello sviluppatore.

Variabili specifiche per l'azienda

Se app.appType è "Company", vengono compilati gli attributi dell'azienda e se app.appType è "Developer", vengono compilati gli attributi dello sviluppatore.

Operazione GenerateAuthorizationCode

Queste variabili vengono impostate quando l'operazione GenerateAuthorizationCode viene eseguita correttamente:

Prefisso: oauthv2authcode.{policy_name}.{variable_name}

Esempio: oauthv2authcode.GenerateCodePolicy.code

Operazioni GenerateAccessToken e RefreshAccessToken

Queste variabili vengono impostate quando le operazioni GenerateAccessToken e RefreshAccessToken vengono eseguite correttamente. Tieni presente che le variabili del token di aggiornamento non si applicano al flusso di tipo di concessione delle credenziali client.

Prefisso: oauthv2accesstoken.{policy_name}.{variable_name}

Esempio: oauthv2accesstoken.GenerateTokenPolicy.access_token

GenerateAccessTokenImplicitGrant

Queste variabili vengono impostate quando l'operazione GenerateAccessTokenImplicit viene eseguita correttamente per il flusso del tipo di concessione implicita.

Prefisso: oauthv2accesstoken.{policy_name}.{variable_name}

Esempio: oauthv2accesstoken.RefreshTokenPolicy.access_token

Riferimento all'errore

Questa sezione descrive i codici e i messaggi di errore restituiti, nonché le variabili di errore impostate da Edge quando questo criterio attiva un errore. È importante sapere se stai sviluppando regole di errore per per gestire gli errori. Per saperne di più, consulta Cosa devi sapere sugli errori relativi ai criteri e sulla gestione di errore.

Errori di runtime

Questi errori possono verificarsi quando il criterio viene eseguito.

Errori di deployment

Questi errori possono verificarsi quando esegui il deployment di un proxy contenente questo criterio.

Variabili di errore

Queste variabili vengono impostate quando il criterio attiva un errore in fase di runtime.

Esempio di risposta di errore

Queste risposte vengono inviate al client se <GenerateResponse> è true.

Se <GenerateResponse> è true, il criterio restituisce errori in questo formato per le operazioni che generano token e codici. Per un elenco completo, vedi Errore HTTP OAuth riferimento della risposta.

{"ErrorCode" : "invalid_client", "Error" :"ClientId is Invalid"}

Se <GenerateResponse> è true, il criterio restituisce errori per le operazioni di verifica e convalida. Per un elenco completo, vedi Errore HTTP OAuth riferimento della risposta.

{  
   {  
      "fault":{  
         "faultstring":"Invalid Access Token",
         "detail":{  
            "errorcode":"keymanagement.service.invalid_access_token"
         }
      }
   }

Esempio di regola di errore

<FaultRule name=OAuthV2 Faults">
    <Step>
        <Name>AM-InvalidClientResponse</Name>
        <Condition>(fault.name = "invalid_client") OR (fault.name = "InvalidClientIdentifier")</Condition>
    </Step>
    <Step>
        <Name>AM-InvalidTokenResponse</Name>
        <Condition>(fault.name = "invalid_access_token")</Condition>
    </Step>
    <Condition>(oauthV2.failed = true) </Condition>
</FaultRule>

Schema dei criteri

Ogni tipo di criterio è definito da uno schema XML (.xsd). Come riferimento, su GitHub sono disponibili gli schemi dei criteri.

Utilizzo della configurazione OAuth predefinita

Per ogni organizzazione (anche per quelle con prova senza costi) su Apigee Edge viene eseguito il provisioning di un endpoint del token OAuth. L'endpoint è preconfigurato con i criteri nel proxy API chiamato oauth. Puoi iniziare a utilizzare l'endpoint token non appena crei un account su Apigee Edge. Per maggiori dettagli, consulta la pagina Informazioni sugli endpoint OAuth.

Pulizia dei token di accesso

Per impostazione predefinita, i token OAuth2 vengono eliminati dal sistema Apigee Edge 3 giorni (259200 secondi) dopo la scadenza sia del token di accesso sia del token di aggiornamento (se esistente). In alcuni casi, potresti voler modificare questa impostazione predefinita. Ad esempio, potresti voler ridurre il tempo di eliminazione per risparmiare spazio su disco se viene generato un numero elevato di token.

Se utilizzi Edge for Private Cloud, puoi modificare questa impostazione predefinita impostando le proprietà dell'organizzazione come spiegato in questa sezione. L'eliminazione di 3 giorni dei token scaduti si applica a Edge for Private Cloud versione 4.19.01 e successive. Per le versioni precedenti, l'intervallo di eliminazione predefinito è di 180 giorni.

Aggiornamento delle impostazioni di eliminazione per Edge Private Cloud 4.16.01 e versioni successive

Nota:sono interessati solo i token generati dopo l'applicazione di queste impostazioni. Le impostazioni non si applicano ai token generati in precedenza.

Aggiornamento delle impostazioni di eliminazione per Edge Private Cloud 4.15.07

Nota: sono interessati solo i token generati dopo l'applicazione di queste impostazioni; le impostazioni non si applicano ai token generati in precedenza.

Comportamento non conforme allo standard RFC

Il criterio OAuthV2 restituisce una risposta del token che contiene determinate proprietà non conformi allo standard RFC. La tabella seguente mostra le proprietà non conformi restituite dal criterio OAuthV2 e le proprietà conformi corrispondenti.

Inoltre, la risposta di errore per un token di aggiornamento scaduto quando grant_type = refresh_token è:

{"ErrorCode" : "invalid_request", "Error" :"Refresh Token expired"}

Tuttavia, la risposta conforme alla specifica RFC è:

{"error" : "invalid_grant", "error_description" :"refresh token expired"}

Argomenti correlati

• Introduzione a OAuth 2.0