Utilizzo dei token OAuth JWT

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Questo argomento spiega come generare, verificare e aggiornare i token di accesso JWT utilizzando il criterio OAuthV2.

Introduzione

Le operazioni JWT consentono al criterio OAuthV2 di generare, verificare e aggiornare i token di accesso conformi allo standard IETF RFC 9068, uno standard che descrive come emettere token di accesso in formato JWT. I JWT vengono comunemente utilizzati per condividere rivendicazioni o asserzioni tra applicazioni collegate. L'emissione di token di accesso OAuthV2 in formato JWT è un'alternativa all'emissione di token di accesso opachi.

Se configurato per JWT, il criterio OAuthV2 genera e restituisce un JWT codificato in Base64 costituito da un'intestazione, un payload e una firma separati da punti. Ad esempio:

Figura 1: formato JWT serializzato composto da intestazione, payload e firma separati da punti.

I contenuti codificati di questi elementi dipendono da come configuri il criterio OAuthV2. Nel criterio devi specificare parametri come l'algoritmo di firma e gli elementi del payload come oggetto e nome. Ad esempio, l'intestazione potrebbe decodificare come {"alg":"HS256","typ":"at+JWT"} e il payload potrebbe decodificare come: {"sub":"ABC1234567","iat":1516239022}.

L'intestazione specifica un'attestazione typ (sempre "at+JWT) e l'attestazione alg, a indicare l'algoritmo utilizzato per firmare il JWT. Apigee supporta gli algoritmi RSA e HMAC: RS(256.384.512) e HS(256.384.512).

Payload

Il payload è costituito dalle rivendicazioni sull’entità. Alcune attestazioni devono essere fornite nella configurazione dei criteri, mentre altre vengono generate automaticamente dal runtime Apigee. La norma supporta le seguenti affermazioni:

Richiedi Description Fornito da
iss L'emittente del token. Questo valore è impostato come segue: (http|https)://{domain-name-for-proxy}/{proxy-basePath}. Ad esempio: https://api.mycompany.com/auth/v2. Apigee
sub L'ID client o l'ID del proprietario della risorsa (in caso di password o tipi di autorizzazione). Se il parametro appEndUserId viene fornito nella richiesta, tale valore viene utilizzato come ID proprietario della risorsa. Puoi controllare dove è impostato questo valore utilizzando l'elemento <AppEndUser> del criterio OAuthV2. Sviluppatore di API
jti Un ID univoco, rappresentato come una stringa casuale supportata da UUID, per identificare in modo univoco il token. Apigee
exp La data di scadenza, ovvero l'ora dopo la quale il token deve essere considerato non valido. Il valore è espresso in tempo del periodo (in secondi). Apigee
iat L'ora di emissione, ovvero l'ora in cui è stato creato il token. Il valore è espresso in tempo del periodo (in secondi). Apigee
client_id L'identificatore univoco dell'applicazione client. Sviluppatore di API
scope L'ambito OAuth assegnato al token. Vedi anche Utilizzo degli ambiti OAuth. Sviluppatore di API

Firma

La firma viene generata utilizzando l'intestazione codificata, il payload, la chiave segreta/privata e l'algoritmo. La firma viene utilizzata per garantire che i contenuti del token non siano stati manomessi.

Per ulteriori informazioni sui token di accesso OAuth 2.0 in formato JWT, consulta il documento IETF RFC 9068: JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens.

Prerequisiti

Questo documento presuppone che tu sappia come generare e verificare i token di accesso OAuthV2 utilizzando il criterio OAuthV2. Sia che utilizzi le operazioni JWT sia le operazioni tradizionali che creano token di stringa opachi, l'utilizzo di base del criterio OAuthV2 è lo stesso. Puoi utilizzare i token di accesso JWT con tutti i tipi di autorizzazione OAuthV2 supportati. Consulta anche la pagina Introduzione a OAuth 2.0.

Generazione

Utilizza le operations GenerateJWTAccessToken e GenerateJWTAccessTokenImplicitGrant per generare un token di accesso JWT con il criterio OAuthV2. Queste operazioni sono simili a quelle tradizionali dei criteri GenerateAccessToken e GenerateAccessTokenImplicitGrant. La differenza principale è che l'operazione JWT restituisce un token di accesso in formato JWT invece di un token stringa opaco. Vedi anche Ottenere i token OAuth 2.0.

Gli esempi seguenti mostrano come utilizzare queste operazioni nel criterio OAuthV2. Negli esempi viene utilizzato il tipo di autorizzazione client_credentials, ma con queste operazioni puoi utilizzare uno qualsiasi dei tipi di autorizzazione supportati.

Generazione di un token in formato JWT firmato con un algoritmo HMAC

Specifica l'elemento <Algorithm> con uno degli algoritmi HMAC (HS256/HS384/HS512). Fornisci anche l'<SecretKey>. L'esempio seguente mostra un criterio configurato per generare un JWT firmato con l'algoritmo HS512, utilizzando la chiave secret specificata.

<OAuthV2 name="generate-policy">
  <Operation>GenerateJWTAccessToken</Operation>
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GenerateResponse enabled="true"/>
  <Algorithm>HS512</Algorithm>
  <SecretKey>
    <Value ref="private.mysecretkey"/>
  </SecretKey>
  <ExpiresIn ref="kvm.oauth.expires_in">3600000</ExpiresIn>
</OAuthV2>

Generazione di un token in formato JWT firmato con un algoritmo RSA

Specifica uno degli algoritmi RSA (uno tra RS256/RS384/RS512) nell'elemento <Algorithm> e fornisci la chiave privata nell'elemento <PrivateKey>. L'esempio seguente mostra un criterio configurato per generare una firma JWT con una chiave privata RSA utilizzando l'algoritmo RS256.

<OAuthV2 name="generate-policy">
  <Operation>GenerateJWTAccessToken</Operation>
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GenerateResponse enabled="true"/>
  <Algorithm>RS256</Algorithm>
  <PrivateKey>
    <Value ref="private.rsa-privatekey-1"/>
  </PrivateKey>
  <ExpiresIn ref="kvm.oauth.expires_in">3600000</ExpiresIn>
</OAuthV2>

Generazione di un token in formato JWT con il tipo di autorizzazione implicita

L'operazione GenerateJWTAccessTokenImplicitGrant genera un token di accesso JWT utilizzando il tipo di autorizzazione implicita. Fornisce automaticamente al token il tipo di concessione implicita, pertanto l'elemento <SupportedGrantTypes> non è obbligatorio. Poiché si tratta di un JWT, l'elemento <Algorithm> è obbligatorio. L'esempio seguente mostra l'utilizzo dell'algoritmo RS256. Per questo motivo, l'elemento <PrivateKey> è obbligatorio. Vedi anche Utilizzare il tipo di autorizzazione implicita.

<OAuthV2 name="generate-policy">
  <Operation>GenerateJWTAccessTokenImplicitGrant</Operation>
  <GenerateResponse enabled="true"/>
  <Algorithm>RS256</Algorithm>
  <PrivateKey>
    <Value ref="private.rsa-privatekey-1"/>
  </PrivateKey>
  <ExpiresIn ref="kvm.oauth.expires_in">3600000</ExpiresIn>
</OAuthV2>

In fase di verifica

Utilizza l'operazione VerifyJWTAccessToken per verificare un token di accesso JWT con il criterio OAuthV2. Questa operazione è simile all'operazione VerifyAccessToken; la differenza è che VerifyJWTAccessToken si applica ai token in formato JWT, mentre VerifyAccessToken si applica ai token opachi.

Verificare un token di accesso JWT firmato con un algoritmo HMAC

L'esempio seguente mostra come configurare il criterio OAuthV2 per verificare un token JWT firmato con l'algoritmo HS512. Quando si utilizza l'operazione VerifyJWTAccessToken con un algoritmo HMAC, la configurazione del criterio deve utilizzare l'elemento <SecretKey> per specificare la chiave secret utilizzata per firmare il JWT.

<OAuthV2 name="OAuthV2-verify-jwt">
  <Operation>VerifyJWTAccessToken</Operation>
  <Algorithm>HS512</Algorithm>
  <SecretKey>
    <Value ref="private.mysecretkey"/>
  </SecretKey>
</OAuthV2>

Verificare un token di accesso JWT firmato con un algoritmo RSA

L'esempio seguente mostra come configurare il criterio OAuthV2 per verificare un token JWT firmato con l'algoritmo RS512. Quando si utilizza l'operazione VerifyJWTAccessToken con un algoritmo RSA, la configurazione dei criteri deve utilizzare l'elemento <PublicKey> per specificare la chiave pubblica corrispondente alla chiave privata utilizzata per firmare il JWT.

<OAuthV2 name="OAuthV2-verify-jwt">
  <Operation>VerifyJWTAccessToken</Operation>
  <Algorithm>RS512</Algorithm>
  <PublicKey>
    <Value ref="propertyset.non-secrets.rsa-publickey-1"/>
  </PublicKey>
</OAuthV2>

Aggiornamento

Utilizza l'operazione RefreshJWTAccessToken per aggiornare un token di accesso JWT. Questa operazione è simile all'operazione RefreshAccessToken tradizionale del criterio. Vedi anche Aggiornare un token di accesso.

Aggiornamento di un token di accesso firmato HMAC

Il seguente esempio di criteri illustra come configurare il criterio OAuthV2 per aggiornare un token JWT firmato con un algoritmo HMAC. Gli elementi <SecretKey> e <Algorithm> sono obbligatori in questo caso.

La risposta dell'operazione di aggiornamento è simile alla risposta di un token appena generato. L'operazione di aggiornamento genera un nuovo token JWT con una data di scadenza aggiornata, mantenendo invariate le altre attestazioni.

<OAuthV2 name="RefreshAccessToken">
    <Operation>RefreshJWTAccessToken</Operation>
    <GenerateResponse enabled="true"/>
    <Algorithm>HS512</Algorithm>
    <SecretKey>
      <Value ref="private.mysecretkey"/>
    </SecretKey>
    <RefreshTokenExpiresIn ref="kvm.oauth.expires_in">3600000</RefreshTokenExpiresIn>
</OAuthV2>

Aggiornamento di un token di accesso JWT firmato RSA

Il seguente esempio di criteri illustra come configurare il criterio OAuthV2 per aggiornare un token JWT firmato con un algoritmo RSA. Vedi anche Aggiornare un token di accesso.

<OAuthV2 name="RefreshAccessToken">
    <Operation>RefreshJWTAccessToken</Operation>
    <GenerateResponse enabled="true"/>
    <Algorithm>RS256</Algorithm>
    <PrivateKey>
      <Value ref="private.rsa-privatekey-1"/>
    </PrivateKey>
    <RefreshTokenExpiresIn ref="kvm.oauth.expires_in">3600000</RefreshTokenExpiresIn>
</OAuthV2>

Esempio di risposta al token

Per le operazioni di generazione e aggiornamento, il corpo della risposta è simile all'esempio seguente. Tieni presente che access_token è rappresentato come un JWT serializzato e il token di aggiornamento è un token opaco tradizionale.

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6ImF0K0pXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "token_type": "Bearer",
  "developer.email": "developer@example.org",
  "token_type": "Bearer",
  "issued_at": "1658352381404",
  "expires_in": 1799,
  "refresh_token": "rVSmm3QaNa0xBVFbUISz1NZI15akvgLJ",
  "refresh_token_issued_at": "1658352381404",
  "refresh_token_expires_in": 86399,
  "refresh_token_status": "Approved",
  "refresh_count": "0",
  "organization_name": "cerruti",
  "api_product_list_json": [ "TestingProduct" ]
}

Riepilogo degli elementi dei criteri richiesti

La tabella seguente descrive gli elementi specifici di JWT utilizzati negli esempi precedenti:

Elemento Tipo Note
Algoritmo Valore statico Specifica l'algoritmo utilizzato per firmare il token.
SecretKey Valore di riferimento Fornisce la chiave segreta utilizzata per verificare o firmare i token con un algoritmo HMAC: HS (256/384/512).
PrivateKey Valore di riferimento Fornisce la chiave privata utilizzata per generare il token. Da utilizzare solo se l'algoritmo è un algoritmo RSA: RS (256/384/512).
PublicKey Valore di riferimento Fornisce la chiave pubblica utilizzata per verificare il token. Da utilizzare solo se l'algoritmo è un algoritmo RSA: RS (256/384/512).

Elementi dei criteri non supportati

I seguenti elementi dei criteri OAuthV2 non sono supportati con le configurazioni dei token JWT:

Elemento Note
ExternalAuthorization Quando generi un token di accesso JWT, il criterio OAuthV2 convaliderà l'ID client e il secret.
ExternalAccessToken Quando generi un token di accesso JWT, il token verrà firmato da Apigee e le richieste verranno fornite da Apigee per impostazione predefinita o tramite la configurazione dei criteri. Il criterio supporta ExternalRefreshToken, il che può essere utile nei casi d'uso della migrazione.
RFCCompliantRequestResponse La generazione e l'aggiornamento dei token di accesso JWT sono conformi a RFC per impostazione predefinita.

Note sull'utilizzo

  • I JWT criptati non sono supportati.
  • Oltre a un token di accesso JWT, la risposta del criterio include anche un token di aggiornamento opaco per i tipi di autorizzazione in cui sono supportati i token di aggiornamento. Solo i tipi di concessione di password e codice di autorizzazione supportano i token di aggiornamento.
  • Includi l'intestazione Authorization nelle richieste inviate al proxy contenente il criterio OAuthV2.
  • Impossibile revocare un token di accesso JWT. Il token JWT generato rimarrà valido fino alla scadenza. Puoi revocare un token di aggiornamento associato a un token di accesso JWT.
  • La generazione, la verifica e l'aggiornamento dei token di accesso devono essere gestiti da Apigee. Sebbene un gateway o un'applicazione esterna che abbia accesso alla chiave pubblica o segreta possa decodificare i contenuti del JWT, l'applicazione esterna non dispone di informazioni sui prodotti API identificati dall'attestazione client_id e, pertanto, non può svolgere un ruolo nell'autorizzazione proxy API.