Richiedere token di accesso e codici di autorizzazione

Stai visualizzando la documentazione di Apigee Edge.
Consulta la documentazione di Apigee X. info

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

Codice di esempio

Per tua comodità, le policy e gli endpoint descritti in questo argomento sono disponibili su GitHub nel progetto oauth-doc-examples nel repository api-platform-samples di Apigee. 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 OAuth 2.0, consulta 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 questa impostazione predefinita configurando gli elementi <GrantType>, <Code> e <RedirectUri> nel criterio OAuthV2 collegato a questo endpoint /accesstoken. Per i dettagli, vedi policy OAuthV2.

  • grant_type: deve essere impostato sul valore authorization_code.
  • code: il codice di autorizzazione ricevuto dall'endpoint /authorize (o il nome che scegli di assegnargli). 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 richiesta precedente del codice di autorizzazione. Se il parametro redirect_uri non è stato incluso nella richiesta del codice di autorizzazione e se non fornisci questo parametro, questo criterio utilizza il valore dell'URL di callback fornito al momento della registrazione dell'app per sviluppatori.

Parametri facoltativi

  • state: una stringa che verrà restituita con la risposta. In genere viene utilizzato per impedire attacchi di richiesta cross-site.
  • scope: consente di filtrare l'elenco dei prodotti API con cui è possibile utilizzare il token creato. Per informazioni dettagliate sull'ambito, vedi Utilizzo degli ambiti OAuth2.

Autenticazione

Devi trasmettere l'ID client e il client secret come intestazione di autenticazione di base (codificata in Base64) o come parametri del modulo client_id e client_secret. Ottieni questi valori da un'app sviluppatore registrata. Vedi anche "Codifica delle credenziali di autenticazione di base".

Endpoint di esempio

Ecco un esempio di configurazione dell'endpoint per generare un token di accesso. Eseguirà il criterio GenerateAccessToken, che deve essere configurato per supportare il tipo di concessione authorization_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>
...

Norma di esempio

Si tratta di una policy GenerateAccessToken di base configurata per accettare il tipo di concessione authorization_code. Per informazioni sugli elementi di configurazione facoltativi che puoi configurare con questa policy, vedi Policy OAuthV2.

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

Restituisce

Con <GenerateResponse> abilitato, il criterio restituisce una risposta JSON che include il token di accesso, come mostrato di seguito. Il tipo di concessione authorization_code crea un token di accesso e un token di aggiornamento, quindi una risposta potrebbe essere simile a questa:

{
    "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> è impostato su false, il criterio non restituisce una risposta. Viene invece compilato 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 OAuth 2.0, consulta Introduzione a OAuth 2.0.

Richiesta di esempio

Per informazioni sulla codifica dell'intestazione di autenticazione di base nella seguente chiamata, vedi "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 grant_type obbligatorio deve essere x-www-form-urlencoded e 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 i dettagli, vedi policy OAuthV2.

  • grant_type: deve essere impostato sul valore client_credentials.

Parametri facoltativi

  • state: una stringa che verrà restituita con la risposta. In genere viene utilizzato per impedire attacchi di richiesta cross-site.
  • scope: consente di filtrare l'elenco dei prodotti API con cui è possibile utilizzare il token creato. Per informazioni dettagliate sull'ambito, vedi Utilizzo degli ambiti OAuth2.

Autenticazione

Devi trasmettere l'ID client e il client secret come intestazione di autenticazione di base (codificata in Base64) o come parametri del modulo client_id e client_secret. Questi valori vengono ottenuti dall'app per sviluppatori registrata associata alla richiesta. Vedi anche "Codifica delle credenziali di autenticazione di base".

Endpoint di esempio

Ecco un esempio di configurazione dell'endpoint per generare un token di accesso. Eseguirà il criterio GenerateAccessToken, 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>
...

Norma di esempio

Si tratta di una policy GenerateAccessToken di base configurata per accettare il tipo di concessione client_credentials. Per informazioni sugli elementi di configurazione facoltativi che puoi configurare con questa policy, vedi Policy OAuthV2.

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

Restituisce

Con <GenerateResponse> attivato, il criterio restituisce una risposta JSON. Tieni presente che con il tipo di concessione client_credentials, i token di aggiornamento non sono supportati. Viene creato solo un 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> è impostato su false, il criterio non restituisce una risposta. Viene invece compilato 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

Richiesta di un token di accesso: tipo di concessione della password

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

Per ulteriori dettagli sul tipo di concessione della password, incluso un video di 4 minuti che mostra come implementarlo, consulta Implementazione del tipo di concessione della password.

Richiesta di esempio

Per informazioni sulla codifica dell'intestazione di autenticazione di base nella seguente chiamata, vedi "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 questa impostazione predefinita configurando gli elementi <GrantType>, <Username> e <Password> nel criterio OAuthV2 collegato a questo endpoint /token. Per i dettagli, vedi policy OAuthV2.

Le credenziali utente vengono in genere convalidate rispetto a un archivio delle 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à restituita con la risposta. In genere viene utilizzato per impedire attacchi di richiesta cross-site.
  • scope: consente di filtrare l'elenco dei prodotti API con cui è possibile utilizzare il token creato. Per informazioni dettagliate sull'ambito, vedi Utilizzo degli ambiti OAuth2.

Autenticazione

Devi trasmettere l'ID client e il client secret come intestazione di autenticazione di base (codificata in Base64) o come parametri del modulo client_id e client_secret. Questi valori vengono ottenuti dall'app per sviluppatori registrata associata alla richiesta. Vedi anche "Codifica delle credenziali di autenticazione di base".

Endpoint di esempio

Ecco un esempio di configurazione dell'endpoint per generare un token di accesso. Verrà eseguita la policy GenerateAccessToken, che deve essere configurata 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>
...

Norma di esempio

Si tratta di una policy GenerateAccessToken di base configurata per accettare il tipo di concessione della password. Per informazioni sugli elementi di configurazione facoltativi che puoi configurare con questa policy, vedi Policy 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

Con <GenerateResponse> attivato, il criterio restituisce una risposta JSON. Tieni presente che con il tipo di concessione della password vengono generati 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> è impostato su false, il criterio non restituisce una risposta. Viene invece compilato 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 concessione implicita. Per un'introduzione ai tipi di autorizzazione OAuth 2.0, consulta Introduzione 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 precedente); tuttavia, è possibile modificare questa impostazione predefinita configurando gli elementi <ResponseType>, <ClientId> e <RedirectUri> nel criterio OAuthV2 collegato a questo endpoint /token. Per i dettagli, vedi policy OAuthV2.

Le credenziali utente vengono in genere convalidate rispetto a un archivio delle credenziali utilizzando un callout del servizio LDAP o una policy JavaScript.

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

Parametri facoltativi

  • state: una stringa che verrà restituita con la risposta. In genere viene utilizzato per impedire attacchi di richiesta cross-site.
  • scope: consente di filtrare l'elenco dei prodotti API con cui è possibile utilizzare il token creato. Per informazioni dettagliate sull'ambito, vedi Utilizzo degli ambiti OAuth2.

Autenticazione

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

Endpoint di esempio

Ecco un esempio di configurazione dell'endpoint per generare un token di accesso. Verrà eseguito il criterio GenerateAccessTokenImplicitGrant.

...
       <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>
...

Norma di esempio

Si tratta di una policy GenerateAccessTokenImplicitGrant di base che elabora le richieste di token per il flusso del tipo di concessione implicita. Per informazioni sugli elementi di configurazione facoltativi che puoi configurare con questa policy, vedi Policy OAuthV2.

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

Restituisce

Con <GenerateResponse> attivato, il criterio restituisce un reindirizzamento della posizione 302 nell'intestazione della risposta. Il reindirizzamento punta all'URL specificato nel parametro redirect_uri e viene aggiunto con il token di accesso e l'ora di scadenza del token. Tieni presente che il tipo di concessione implicita non supporta i token di aggiornamento. Ad esempio:

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

Se <GenerateResponse> è impostato su false, il criterio non restituisce una risposta. Viene invece compilato 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

Richiesta di 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 è collegata una policy OAuthV2 GenerateAuthorizationCode 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 precedente); tuttavia, è possibile modificare questa impostazione predefinita configurando gli elementi <ResponseType>, <ClientId> e <RedirectUri> nel criterio OAuthV2 collegato a questo endpoint /authorize. Per i dettagli, vedi policy OAuthV2.

  • response_type: deve essere impostato sul valore code.
  • client_id: l'ID client di un'app per sviluppatori registrata.

Parametri facoltativi

  • redirect_uri: se nell'app client registrata è specificato un URI di callback completo (non parziale), questo parametro è facoltativo; in caso contrario, è 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à restituita con la risposta. In genere viene utilizzato per impedire attacchi di richiesta cross-site.
  • scope: consente di filtrare l'elenco dei prodotti API con cui è possibile utilizzare il token creato. Per informazioni dettagliate sull'ambito, vedi Utilizzo degli ambiti OAuth2.

Autenticazione

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

Endpoint di esempio

Di seguito è riportata una configurazione dell'endpoint di esempio per generare 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>

Norma di esempio

Si tratta di una norma GenerateAuthorizationCode di base. Per informazioni sugli elementi di configurazione facoltativi che puoi configurare con questa policy, vedi Policy OAuthV2.

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

Restituisce

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

Se <GenerateResponse> è impostato su false, la policy non restituisce una risposta. Viene invece compilato il seguente insieme di variabili di flusso con i 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 il token di accesso è scaduto o non è più valido. Un token di aggiornamento viene restituito nella risposta quando ricevi un token di accesso.

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

Richiesta di esempio

Per informazioni sulla codifica dell'intestazione di autenticazione di base nella seguente chiamata, vedi "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 li cerca 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> nella policy OAuthV2. Per i dettagli, vedi policy OAuthV2.

Parametri facoltativi

  • state: una stringa che verrà restituita con la risposta. In genere viene utilizzato per impedire attacchi di richiesta cross-site.
  • scope: consente di filtrare l'elenco dei prodotti API con cui è possibile utilizzare il token creato. Per informazioni dettagliate sull'ambito, vedi Utilizzo degli ambiti OAuth2.

Autenticazione

  • client_id
  • client_secret

Devi trasmettere l'ID client e il client secret come intestazione di autenticazione di base (codificata in Base64) o come parametri del modulo client_id e client_secret. Vedi anche "Codifica delle credenziali di autenticazione di base".

Quando viene aggiornato un token di accesso, non viene eseguita una nuova autenticazione dell'utente.

Ecco un esempio di configurazione dell'endpoint per generare un token di accesso utilizzando un token di aggiornamento. Verrà eseguita la policy RefreshAccessToken.

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

Norma di esempio

Si tratta di una policy RefreshAccessToken di base configurata per accettare il tipo di concessione refresh_token. Per informazioni sugli elementi di configurazione facoltativi che puoi configurare con questa policy, vedi Policy 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

Con <GenerateResponse> abilitato, la policy restituisce una risposta JSON contenente il nuovo token di accesso. Il tipo di concessione refresh_token supporta la creazione di token di accesso e 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 la creazione di un nuovo token di aggiornamento, quello originale non è più valido.

La risposta precedente è quella che ottieni se <GenerateResponse> è impostato su true. Se <GenerateResponse> è impostato su false, il criterio non restituisce una risposta. ma compila il seguente insieme di variabili di contesto (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.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, è una buona pratica, consigliata dalla specifica OAuth 2.0, passare i valori client_id e client_secret come intestazione di autenticazione HTTP di base, come descritto in IETF RFC 2617. Per farlo, devi codificare in Base64 il risultato dell'unione dei due valori separati da due punti.

In pseudocodice:

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

In questo esempio, ns4fQc14Zg4hKFCNaSzArVuwszX95X è l'ID client 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==

Dopodiché, puoi effettuare la richiesta del token nel seguente modo:

$ 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'

L'utilità curl creerà l'intestazione HTTP Basic per te, se utilizzi l'opzione -u. Quanto segue è equivalente 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 codificata in base64.

Hashing dei token nel database

Per proteggere l'accesso OAuth e i token di aggiornamento in caso di violazione della sicurezza del database, puoi attivare 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 aggiornamento OAuth appena generati utilizzando l'algoritmo specificato. (Di seguito sono riportate informazioni sull'hashing collettivo dei token esistenti.) I token senza hash vengono utilizzati nelle chiamate API ed Edge li convalida rispetto 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 hai token con hash esistenti e vuoi conservarli fino alla scadenza, imposta le seguenti proprietà nella tua organizzazione, dove l'algoritmo di hashing corrisponde a quello esistente (ad esempio SHA1, l'ex algoritmo predefinito di Edge). Se i token sono stati decrittografati, 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à nella tua organizzazione e, facoltativamente, per eseguire l'hashing collettivo dei token esistenti.

Argomenti correlati