Richiedere token di accesso e codici di autorizzazione

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

In questo argomento, ti mostriamo come richiedere token di accesso e codici di autorizzazione, configurare endpoint OAuth 2.0 e criteri per ogni tipo di autorizzazione supportato.

Codice campione

Per praticità, i criteri e gli endpoint illustrati in questo argomento sono disponibili in GitHub nel progetto oauth-doc-examples nel repository Apigee api-platform-samples. Puoi eseguire il deployment del codice campione e provare le richieste di esempio mostrate in questo argomento. Per i dettagli, consulta il file README del progetto.

Richiesta di un token di accesso: tipo di concessione del codice di autorizzazione

Questa sezione spiega come richiedere un token di accesso utilizzando il flusso del tipo di concessione del codice di autorizzazione. Per un'introduzione ai tipi di autorizzazione con OAuth 2.0, vedi Introduzione a OAuth 2.0.

Richiesta di esempio

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
   -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \
   -X POST 'https://docs-test.apigee.net/oauth/accesstoken' \
   -d 'code=I9dMGHAN&grant_type=authorization_code&redirect_uri=http://example-callback.com'

Parametri obbligatori

Per impostazione predefinita, questi parametri devono essere x-www-form-urlencoded e specificati nel corpo della richiesta (come mostrato nell'esempio precedente). Tuttavia, è possibile modificare questo valore predefinito configurando gli elementi <GrantType>, <Code> e <RedirectUri> nel criterio OAuthV2 collegato a questo endpoint /accesstoken. Per maggiori dettagli, vedi Criterio OAuthV2.

  • grant_type: deve essere impostato sul valore authorization_code.
  • code - Il codice di autorizzazione ricevuto dall'endpoint /authorize (o da qualsiasi nome tu scelga di assegnare). Per richiedere un token di accesso nel flusso del tipo di concessione del codice di autorizzazione, devi prima ottenere un codice di autorizzazione. Consulta la sezione Richiesta di codici di autorizzazione di seguito. Vedi anche Implementazione del tipo di concessione del codice di autorizzazione.
  • redirect_uri: devi fornire questo parametro se il parametro redirect_uri è stato incluso nella precedente richiesta del codice di autorizzazione. Se il parametro redirect_uri non è stato incluso nella richiesta del codice di autorizzazione e non lo specifichi, questo criterio utilizza il valore dell'URL di callback fornito al momento della registrazione dell'app dello sviluppatore.

Parametri facoltativi

  • state - Una stringa che verrà inviata con la risposta. In genere viene utilizzato per prevenire attacchi di falsificazione di richieste tra siti.
  • scope: consente di filtrare l'elenco dei prodotti API con cui è possibile utilizzare il token creato. Per informazioni dettagliate sull'ambito, consulta l'articolo sull'utilizzo degli ambiti OAuth2.

Autenticazione

Devi passare l'ID client e il client secret come intestazione dell'autenticazione di base (con codifica Base64) o come parametri di forma client_id e client_secret. Puoi ottenere questi valori da un'app sviluppatore registrata. Vedi anche "Codificare le credenziali di autenticazione di base".

Endpoint di esempio

Di seguito è riportata una configurazione di endpoint di esempio per la generazione di un token di accesso. Verrà eseguito il criterio GeneraAccessToken, che deve essere configurato in modo da supportare il tipo di concessione autorizzazione_code.

...
       <Flow name="generate-access-token">
            <Description>Generate a token</Description>
            <Request>
                <Step>
                    <Name>GenerateAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition>
        </Flow>
...

Criterio di esempio

Questo è un criterio GeneraAccessToken di base configurato per accettare il tipo di autorizzazione authorization_code. Per informazioni sugli elementi di configurazione facoltativi che puoi configurare con questo criterio, consulta l'articolo sul criterio OAuthV2.

<OAuthV2 name="GenerateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>1800000</ExpiresIn>
    <RefreshTokenExpiresIn>86400000</RefreshTokenExpiresIn>
    <SupportedGrantTypes>
      <GrantType>authorization_code</GrantType>
    </SupportedGrantTypes>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Restituisce

Se <GenerateResponse> è abilitato, il criterio restituisce una risposta JSON che include il token di accesso, come mostrato di seguito. Il tipo di autorizzazione authorization_code crea un token di accesso e un token di aggiornamento. Una risposta potrebbe avere il seguente aspetto:

{
    "issued_at": "1420262924658",
    "scope": "READ",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "refresh_token_issued_at": "1420262924658",
    "status": "approved",
    "refresh_token_status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "tesla@weathersample.com",
    "organization_id": "0",
    "token_type": "BearerToken",
    "refresh_token": "fYACGW7OCPtCNDEnRSnqFlEgogboFPMm",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "2l4IQtZXbn5WBJdL6EF7uenOWRsi",
    "organization_name": "docs",
    "refresh_token_expires_in": "86399", //--in seconds
    "refresh_count": "0"
}

Se <GenerateResponse> viene impostato su false, il criterio non restituisce una risposta. Compila invece il seguente insieme di variabili di flusso con i dati relativi alla concessione del token di accesso.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token
oauthv2accesstoken.{policy-name}.refresh_token_expires_in //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token_issued_at
oauthv2accesstoken.{policy-name}.refresh_token_status

Ad esempio:

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token
oauthv2accesstoken.GenerateAccessToken.refresh_token_expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token_issued_at
oauthv2accesstoken.GenerateAccessToken.refresh_token_status

Richiesta di un token di accesso: tipo di concessione delle credenziali client

Questa sezione spiega come richiedere un token di accesso utilizzando il flusso del tipo di concessione delle credenziali client. Per un'introduzione ai tipi di autorizzazione con OAuth 2.0, vedi Introduzione a OAuth 2.0.

Richiesta di esempio

Per informazioni sulla codifica dell'intestazione dell'autenticazione di base nella chiamata seguente, consulta la sezione "Codifica delle credenziali di autenticazione di base".

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic c3FIOG9vSGV4VHoAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \
  -X POST 'https://docs-test.apigee.net/oauth/accesstoken' \
  -d 'grant_type=client_credentials'

Parametri obbligatori

Per impostazione predefinita, il parametro allow_type obbligatorio deve essere x-www-form-urlencoded e deve essere specificato nel corpo della richiesta (come mostrato nell'esempio precedente); tuttavia, è possibile modificare questo valore predefinito configurando l'elemento <GrantType> nel criterio OAuthV2 collegato a questo endpoint /accesstoken. Ad esempio, puoi scegliere di passare il parametro in un parametro di query. Per maggiori dettagli, vedi Criterio OAuthV2.

  • grant_type: deve essere impostato sul valore client_credentials.

Parametri facoltativi

  • state - Una stringa che verrà inviata con la risposta. In genere viene utilizzato per prevenire attacchi di falsificazione di richieste tra siti.
  • scope: consente di filtrare l'elenco dei prodotti API con cui è possibile utilizzare il token creato. Per informazioni dettagliate sull'ambito, consulta l'articolo sull'utilizzo degli ambiti OAuth2.

Autenticazione

Devi passare l'ID client e il client secret come intestazione dell'autenticazione di base (con codifica Base64) o come parametri di forma client_id e client_secret. Puoi ottenere questi valori dall'app dello sviluppatore registrata associata alla richiesta. Vedi anche "Codifica delle credenziali di autenticazione di base".

Endpoint di esempio

Di seguito è riportata una configurazione di endpoint di esempio per la generazione di un token di accesso. Verrà eseguito il criterio GeneraAccessToken, che deve essere configurato per supportare il tipo di concessione client_credentials.

...
       <Flow name="generate-access-token">
            <Request>
                <Step>
                    <Name>GenerateAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition>
        </Flow>
...

Criterio di esempio

Questo è un criterio GeneraAccessToken di base configurato per accettare il tipo di autorizzazione client_credentials. Per informazioni sugli elementi di configurazione facoltativi che puoi configurare con questo criterio, consulta l'articolo sul criterio OAuthV2.

<OAuthV2 name="GenerateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>1800000</ExpiresIn> <!-- 30 minutes -->
    <SupportedGrantTypes>
      <GrantType>client_credentials</GrantType>
    </SupportedGrantTypes>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Restituisce

Se il criterio <GenerateResponse> è abilitato, il criterio restituisce una risposta JSON. Tieni presente che con il tipo di autorizzazione client_credentials, i token di aggiornamento non sono supportati. Viene creato un solo token di accesso. Ad esempio:

{
    "issued_at": "1420260525643",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "scope": "READ",
    "status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "tesla@weathersample.com",
    "organization_id": "0",
    "token_type": "BearerToken",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "XkhU2DFnMGIVL2hvsRHLM00hRWav",
    "organization_name": "docs"
}

Se <GenerateResponse> viene impostato su false, il criterio non restituisce una risposta. Compila invece il seguente insieme di variabili di flusso con i dati relativi alla concessione del token di accesso.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in //--in seconds

Ad esempio:

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in     //--in seconds

Richiedere un token di accesso: tipo di concessione della password

Questa sezione spiega come richiedere un token di accesso utilizzando il flusso del tipo di autorizzazione (password) del proprietario della risorsa. Per un'introduzione ai tipi di autorizzazione con OAuth 2.0, consulta Introduzione a OAuth 2.0.

Per maggiori dettagli sul tipo di concessione della password, incluso un video di 4 minuti che mostra come implementarla, consulta la sezione Implementazione del tipo di concessione della password.

Richiesta di esempio

Per informazioni sulla codifica dell'intestazione dell'autenticazione di base nella chiamata seguente, consulta la sezione "Codifica delle credenziali di autenticazione di base".

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAySVg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \
  -X POST https://docs-test.apigee.net/oauth/token \
  -d 'grant_type=password&username=the-user-name&password=the-users-password'

Parametri obbligatori

Per impostazione predefinita, questi parametri devono essere x-www-form-urlencoded e specificati nel corpo della richiesta (come mostrato nell'esempio precedente). Tuttavia, è possibile modificare questo valore predefinito configurando gli elementi <GrantType>, <Username> e <Password> nel criterio OAuthV2 collegato a questo endpoint /token. Per maggiori dettagli, vedi Criterio OAuthV2.

Le credenziali utente vengono in genere convalidate in un archivio credenziali utilizzando un criterio LDAP o JavaScript.

  • grant_type: deve essere impostato sul valore password.
  • username: il nome utente del proprietario della risorsa.
  • password: la password del proprietario della risorsa.

Parametri facoltativi

  • state - Una stringa che verrà inviata con la risposta. In genere viene utilizzato per prevenire attacchi di falsificazione di richieste tra siti.
  • scope: consente di filtrare l'elenco dei prodotti API con cui è possibile utilizzare il token creato. Per informazioni dettagliate sull'ambito, consulta l'articolo sull'utilizzo degli ambiti OAuth2.

Autenticazione

Devi passare l'ID client e il client secret come intestazione dell'autenticazione di base (con codifica Base64) o come parametri di forma client_id e client_secret. Puoi ottenere questi valori dall'app dello sviluppatore registrata associata alla richiesta. Vedi anche "Codifica delle credenziali di autenticazione di base".

Endpoint di esempio

Di seguito è riportata una configurazione di endpoint di esempio per la generazione di un token di accesso. Verrà eseguito il criterio GeneraAccessToken, che deve essere configurato per supportare il tipo di concessione della password.

...
       <Flow name="generate-access-token">
            <Request>
                <Step>
                    <Name>GenerateAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition>
        </Flow>
...

Criterio di esempio

Questo è un criterio GeneraAccessToken di base configurato per accettare il tipo di concessione della password. Per informazioni sugli elementi di configurazione facoltativi che puoi configurare con questo criterio, consulta la pagina relativa al criterio OAuthV2.

<OAuthV2 name="GenerateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>1800000</ExpiresIn> <!-- 30 minutes -->
    <RefreshTokenExpiresIn>28800000</RefreshTokenExpiresIn> <!-- 8 hours -->
    <SupportedGrantTypes>
      <GrantType>password</GrantType>
    </SupportedGrantTypes>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Restituisce

Se il criterio <GenerateResponse> è abilitato, il criterio restituisce una risposta JSON. Tieni presente che con il tipo di concessione della password vengono creati sia un token di accesso sia un token di aggiornamento. Ad esempio:

{
    "issued_at": "1420258685042",
    "scope": "READ",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "refresh_token_issued_at": "1420258685042",
    "status": "approved",
    "refresh_token_status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "tesla@weathersample.com",
    "organization_id": "0",
    "token_type": "BearerToken",
    "refresh_token": "IFl7jlijYuexu6XVSSjLMJq8SVXGOAAq",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "I6daIgMSiUgYX1K2qgQWPi37ztS6",
    "organization_name": "docs",
    "refresh_token_expires_in": "28799", //--in seconds
    "refresh_count": "0"
}

Se <GenerateResponse> viene impostato su false, il criterio non restituisce una risposta. Compila invece il seguente insieme di variabili di flusso con i dati relativi alla concessione del token di accesso.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in   //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token
oauthv2accesstoken.{policy-name}.refresh_token_expires_in  //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token_issued_at
oauthv2accesstoken.{policy-name}.refresh_token_status

Ad esempio:

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token
oauthv2accesstoken.GenerateAccessToken.refresh_token_expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token_issued_at
oauthv2accesstoken.GenerateAccessToken.refresh_token_status

Richiesta di un token di accesso: tipo di concessione implicita

Questa sezione spiega come richiedere un token di accesso utilizzando il flusso del tipo di autorizzazione implicito. Per un'introduzione ai tipi di autorizzazione con OAuth 2.0, consulta la guida introduttiva a OAuth 2.0.

Richiesta di esempio

$ curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
  'https://docs-test.apigee.net/oauth/implicit?response_type=token&client_id=ABC123&redirect_uri=http://callback-example.com'

Parametri obbligatori

Per impostazione predefinita, questi parametri devono essere parametri di query (come mostrato nell'esempio sopra). Tuttavia, è possibile modificare questa impostazione predefinita configurando gli elementi <ResponseType>, <ClientId> e <RedirectUri> nel criterio OAuthV2 collegato a questo endpoint /token. Per maggiori dettagli, vedi Criterio OAuthV2.

In genere, le credenziali utente vengono convalidate rispetto a un archivio credenziali utilizzando un callout di servizio LDAP o un criterio JavaScript.

  • response_type - Deve essere impostato sul valore token.
  • client_id: l'ID client di un'app sviluppatore registrata.
  • redirect_uri: questo parametro è obbligatorio se non è stato fornito un URI di callback al momento della registrazione dell'app sviluppatore client. Se al momento della registrazione del client è stato fornito un URL di callback, questo verrà confrontato con questo valore e deve corrispondere esattamente.

Parametri facoltativi

  • state - Una stringa che verrà inviata con la risposta. In genere viene utilizzato per prevenire attacchi di falsificazione di richieste tra siti.
  • scope: consente di filtrare l'elenco dei prodotti API con cui è possibile utilizzare il token creato. Per informazioni dettagliate sull'ambito, consulta l'articolo sull'utilizzo degli ambiti OAuth2.

Autenticazione

La concessione implicita non richiede l'autenticazione di base. Devi passare un ID client come parametro di richiesta, come spiegato qui.

Endpoint di esempio

Di seguito è riportata una configurazione di endpoint di esempio per la generazione di un token di accesso. Verrà eseguito il criterio CreateAccessTokenImplicitGrant.

...
       <Flow name="generate-access-token-implicit">
            <Request>
                <Step>
                    <Name>GenerateAccessTokenImplicitGrant</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/implicit") and (request.verb = "POST")</Condition>
        </Flow>
...

Criterio di esempio

Questo è un criterio GeneraAccessTokenImplicitGrant di base che elabora le richieste di token per il flusso del tipo di autorizzazione implicita. Per informazioni sugli elementi di configurazione facoltativi che puoi configurare con questo criterio, consulta l'articolo sul criterio OAuthV2.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OAuthV2 name="GenerateAccessTokenImplicit">
    <DisplayName>GenerateAccessTokenImplicit</DisplayName>
    <Operation>GenerateAccessTokenImplicitGrant</Operation>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Restituisce

Se il criterio <GenerateResponse> è attivo, il criterio restituisce un reindirizzamento di località 302 nell'intestazione della risposta. Il reindirizzamento rimanda all'URL specificato nel parametro redirect_uri e viene aggiunto il token di accesso e la relativa scadenza. Tieni presente che il tipo di autorizzazione implicita non supporta i token di aggiornamento. Ad esempio:

https://callback-example.com#expires_in=1799&access_token=In4dKm4ueoGZRbIYJhC9yZCmTFw5

Se <GenerateResponse> viene impostato su false, il criterio non restituisce una risposta. Compila invece il seguente insieme di variabili di flusso con i dati relativi alla concessione del token di accesso.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in  //--in seconds

Ad esempio:

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in   //--in seconds

Richiedere un codice di autorizzazione

Se utilizzi il flusso del tipo di concessione del codice di autorizzazione, devi ottenere un codice di autorizzazione prima di poter richiedere un token di accesso.

Richiesta di esempio

$ curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
  'http://myorg-test.apigee.net/oauth/authorize?client_id={consumer_key}&response_type=code'

in cui un criterio CreateAuthorizationCode OAuthV2 è collegato all'endpoint proxy /oauth/authorize (vedi l'endpoint di esempio di seguito).

Parametri obbligatori

Per impostazione predefinita, questi parametri devono essere parametri di query (come mostrato nell'esempio sopra). Tuttavia, è possibile modificare questa impostazione predefinita configurando gli elementi <ResponseType>, <ClientId> e <RedirectUri> nel criterio OAuthV2 collegato a questo endpoint /authorize. Per maggiori dettagli, vedi Criterio OAuthV2.

  • response_type - Deve essere impostato sul valore code.
  • client_id: l'ID client di un'app sviluppatore registrata.

Parametri facoltativi

  • redirect_uri: se nell'app client registrata viene specificato un URI di callback completo (non parziale), questo parametro è facoltativo, altrimenti obbligatorio. Il callback è l'URL a cui Edge invia il codice di autorizzazione appena creato. Vedi anche Registrare app e gestire le chiavi API.
  • state - Una stringa che verrà inviata con la risposta. In genere viene utilizzato per prevenire attacchi di falsificazione di richieste tra siti.
  • scope: consente di filtrare l'elenco dei prodotti API con cui è possibile utilizzare il token creato. Per informazioni dettagliate sull'ambito, consulta l'articolo sull'utilizzo degli ambiti OAuth2.

Autenticazione

Non richiede l'autenticazione di base, ma nella richiesta deve essere fornito l'ID client dell'app client registrata.

Endpoint di esempio

Di seguito è riportata una configurazione di endpoint di esempio per la generazione di un codice di autorizzazione:


<OAuthV2 name="GenerateAuthorizationCode">
  <Operation>GenerateAuthorizationCode</Operation>
    <!--
    ExpiresIn, in milliseconds. The ref is optional. The explicitly specified
    value is the default, when the variable reference cannot be resolved.
        60000 = 1 minute
       120000 = 2 minutes
    -->
  <ExpiresIn>60000</ExpiresIn>
  <GenerateResponse enabled="true"/>
</OAuthV2>

Criterio di esempio

Questo è un criterio di generateAuthorizationCode di base. Per informazioni sugli elementi di configurazione facoltativi che puoi configurare con questo criterio, consulta l'articolo sul criterio OAuthV2.

<OAuthV2 name="GenerateAuthorizationCode">
    <Operation>GenerateAuthorizationCode</Operation>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Restituisce

Se <GenerateResponse> è abilitato, il criterio restituisce il parametro di query ?code alla località redirect_uri (URI di callback) con il codice di autorizzazione allegato. Viene inviato tramite un reindirizzamento del browser 302 con l'URL nell'intestazione Posizione della risposta. Ad esempio: ?code=123456.

Se <GenerateResponse> viene impostato su false, il criterio non restituisce alcuna risposta. Compila invece il seguente insieme di variabili di flusso con dati relativi al codice di autorizzazione.

oauthv2authcode.{policy-name}.code
oauthv2authcode.{policy-name}.scope
oauthv2authcode.{policy-name}.redirect_uri
oauthv2authcode.{policy-name}.client_id

Ad esempio:

oauthv2authcode.GenerateAuthorizationCode.code
oauthv2authcode.GenerateAuthorizationCode.scope
oauthv2authcode.GenerateAuthorizationCode.redirect_uri
oauthv2authcode.GenerateAuthorizationCode.client_id

Aggiornamento di un token di accesso

Un token di aggiornamento è una credenziale che utilizzi per ottenere un token di accesso, in genere dopo che è scaduto o non è più valido. Quando ricevi un token di accesso, nella risposta viene restituito un token di aggiornamento.

Per richiedere un nuovo token di accesso utilizzando un token di aggiornamento:

Richiesta di esempio

Per informazioni sulla codifica dell'intestazione dell'autenticazione di base nella chiamata seguente, consulta la sezione "Codifica delle credenziali di autenticazione di base".

$ curl -X POST \
  -H "Content-type: application/x-www-form-urlencoded" \
  -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \
  https://myorg-test.apigee.net/my_oauth_endpoint/refresh_accesstoken \
  -d 'grant_type=refresh_token&refresh_token=my-refresh-token'

Parametri obbligatori

  • grant_type: deve essere impostato sul valore refresh_token.
  • refresh_token: il token di aggiornamento associato al token di accesso che vuoi rinnovare.

Per impostazione predefinita, il criterio cerca questi parametri come parametri x-www-form-urlencoded specificati nel corpo della richiesta, come mostrato nell'esempio precedente. Per configurare una posizione alternativa per questi input, puoi utilizzare gli elementi <GrantType> e <RefreshToken> nel criterio OAuthV2. Per maggiori dettagli, vedi Criterio OAuthV2.

Parametri facoltativi

  • state - Una stringa che verrà inviata con la risposta. In genere viene utilizzato per prevenire attacchi di falsificazione di richieste tra siti.
  • scope: consente di filtrare l'elenco dei prodotti API con cui è possibile utilizzare il token creato. Per informazioni dettagliate sull'ambito, consulta l'articolo sull'utilizzo degli ambiti OAuth2.

Autenticazione

  • client_id
  • client_secret

Devi passare l'ID client e il client secret come intestazione dell'autenticazione di base (con codifica Base64) o come parametri di forma client_id e client_secret. Vedi anche "Codifica delle credenziali di autenticazione di base".

Quando aggiorni un token di accesso, l'utente non esegue nuovamente l'autenticazione.

Di seguito è riportata una configurazione di endpoint di esempio per la generazione di un token di accesso utilizzando un token di aggiornamento. Verrà eseguito il criterio UpdateAccessToken.

 ...
       <Flow name="generate-refresh-token">
            <Request>
                <Step>
                    <Name>RefreshAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/refresh") and (request.verb = "POST")</Condition>
       </Flow>
...

Criterio di esempio

Questo è un criterio di base UpdateAccessToken configurato per accettare il tipo di autorizzazione refresh_token. Per informazioni sugli elementi di configurazione facoltativi che puoi configurare con questo criterio, consulta l'articolo sul criterio OAuthV2.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OAuthV2 name="RefreshAccessToken">
    <Operation>RefreshAccessToken</Operation>
    <GenerateResponse enabled="true"/>
    <ExpiresIn>1800000</ExpiresIn> <!-- 30 minutes -->
    <RefreshTokenExpiresIn>28800000</RefreshTokenExpiresIn> <!-- 8 hours -->
</OAuthV2>

Restituisce

Se <GenerateResponse> è abilitato, il criterio restituisce una risposta JSON contenente il nuovo token di accesso. Il tipo di concessione refresh_token supporta il mining sia del token di accesso sia di nuovi token di aggiornamento. Ad esempio:

{
    "issued_at": "1420301470489",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "scope": "READ",
    "refresh_token_issued_at": "1420301470489",
    "status": "approved",
    "refresh_token_status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "tesla@weathersample.com",
    "token_type": "BearerToken",
    "refresh_token": "8fKDHLryAD9KFBsrpixlq3qPJnG2fdZ5",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "jmZ2Hqv3iNsABUtAAsfWR3QGNctw",
    "organization_name": "docs",
    "refresh_token_expires_in": "28799", //--in seconds
    "refresh_count": "2"
}

Tieni presente che, dopo il mining di un nuovo token di aggiornamento, l'originale non è più valido.

La risposta riportata sopra è quella che ottieni se <GenerateResponse> è impostato su true. Se il criterio <GenerateResponse> viene impostato su false, il criterio non restituisce alcuna risposta. Compila invece il seguente insieme di variabili di contesto (flusso) con dati relativi alla concessione dei token di accesso.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in   //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token
oauthv2accesstoken.{policy-name}.refresh_token_expires_in  //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token_issued_at
oauthv2accesstoken.{policy-name}.refresh_token_status

Ad esempio:

oauthv2accesstoken.RefreshAccessToken.access_token
oauthv2accesstoken.RefreshAccessToken.expires_in
oauthv2accesstoken.RefreshAccessToken.refresh_token
oauthv2accesstoken.RefreshAccessToken.refresh_token_expires_in
oauthv2accesstoken.RefreshAccessToken.refresh_token_issued_at
oauthv2accesstoken.RefreshAccessToken.refresh_token_status

Codifica delle credenziali di autenticazione di base

Quando effettui una chiamata API per richiedere un token o un codice di autorizzazione, è buona prassi come consigliato dalla specifica OAuth 2.0, passare i valori client_id e client_secret come intestazione di autenticazione HTTP di base, come descritto in RFC 2617 di IETF. Per farlo, devi codificare in base64 il risultato dell'unione dei due valori con i due punti che li separano.

Nello pseudocodice:

result = Base64Encode(concat('ns4fQc14Zg4hKFCNaSzArVuwszX95X', ':', 'ZIjFyTsNgQNyxI'))

In questo esempio, ns4fQc14Zg4hKFCNaSzArVuwszX95X è il client_id e ZIjFyTsNgQNyxI è il client secret.

Indipendentemente dal linguaggio di programmazione utilizzato per calcolare il valore con codifica Base64, per le credenziali client specificate il risultato con codifica Base64 è: bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJOg==

Quindi, puoi effettuare la richiesta del token come segue:

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJOg==' \
  -X POST 'https://docs-test.apigee.net/oauth/accesstoken' \
  -d 'grant_type=client_credentials'

Se utilizzi l'opzione -u, l'utilità curl creerà effettivamente l'intestazione HTTP di base per te. Quanto segue equivale a quanto sopra:

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
  -u 'ns4fQc14Zg4hKFCNaSzArVuwszX95X:ZIjFyTsNgQNyxI' \
  -X POST 'https://docs-test.apigee.net/oauth/accesstoken' \
  -d 'grant_type=client_credentials'

Altri ambienti di programmazione potrebbero avere scorciatoie simili che generano automaticamente l'intestazione con codifica Base64.

Hashing dei token nel database

Per proteggere i token di accesso e di aggiornamento OAuth in caso di violazione della sicurezza del database, puoi abilitare l'hashing automatico dei token nella tua organizzazione Edge. Quando la funzionalità è abilitata, Edge crea automaticamente una versione sottoposta ad hashing dei token di accesso e di aggiornamento OAuth appena generati utilizzando l'algoritmo specificato. Di seguito sono riportate informazioni sull'hashing collettivo dei token esistenti. I token non sottoposti ad hashing vengono utilizzati nelle chiamate API ed Edge li convalida in base alle versioni con hash nel database.

Le seguenti proprietà a livello di organizzazione controllano l'hashing dei token OAuth.

features.isOAuthTokenHashingEnabled = true
features.OAuthTokenHashingAlgorithm = SHA1 | SHA256 | SHA384 | SHA512 | PLAIN

Se disponi di token con hash esistenti e vuoi conservarli fino alla scadenza, imposta le seguenti proprietà nella tua organizzazione, in cui l'algoritmo di hashing corrisponde a quello esistente (ad esempio SHA1, il precedente valore predefinito di Edge). Se i token non sono stati sottoposti ad hashing, utilizza PLAIN.

features.isOAuthTokenFallbackHashingEnabled = true
features.OAuthTokenFallbackHashingAlgorithm = SHA1 | SHA256 | SHA384 | SHA512 | PLAIN

Se sei un cliente Edge Cloud, contatta l'assistenza Apigee Edge per impostare queste proprietà sulla tua organizzazione e, facoltativamente, per eseguire l'hashing in blocco dei token esistenti.

Argomenti correlati