Utilizzo di token OAuth JWT

Questa pagina si applica a Apigee e Apigee ibridi.

Visualizza documentazione di Apigee Edge.

Questa funzionalità è disponibile sia per Apigee che per Apigee hybrid.

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

Introduzione

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

Se configurato per JWT, il criterio OAuthV2 genera e restituisce un JWT con codifica Base64 che consiste 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 dalla configurazione del criterio OAuthV2. Nel criterio, specifichi parametri come l'algoritmo di firma e gli elementi del payload come oggetto e nome. Ad esempio, l'intestazione potrebbe essere decodificata come {"alg":"HS256","typ":"at+JWT"} e il payload come {"sub":"ABC1234567","iat":1516239022}.

Intestazione

L'intestazione specifica un'affermazione typ (sempre "at+JWT) e l'affermazione alg, che indica 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 consiste in rivendicazioni sull'entità. Alcune dichiarazioni devono essere fornite nei della configurazione dei criteri, mentre altre vengono generate automaticamente dal runtime Apigee. La norma supporta le seguenti dichiarazioni:

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

Firma

La firma viene generata utilizzando l'intestazione, il payload, la chiave segreta/privata e l'algoritmo codificati. 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 IETF RFC 9068: Profilo JWT (JSON Web Token) per token di accesso OAuth 2.0.

Prerequisiti

Questo documento presuppone che tu sappia come generare e verificare i token di accesso OAuth 2.0 utilizzando il criterio OAuth 2.0. Indipendentemente dall'utilizzo delle operazioni JWT o delle 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 concessione OAuth 2.0 supportati. Consulta anche Introduzione a OAuth 2.0.

Generazione

Utilizza le operazioni GenerateJWTAccessToken e GenerateJWTAccessTokenImplicitGrant per generare un token di accesso JWT con il criterio OAuthV2. Queste operazioni sono simili alle tradizionali GenerateAccessToken e GenerateAccessTokenImplicitGrant del criterio operazioni aziendali. La differenza principale è che l'operazione JWT restituisce un token di accesso in formato JWT anziché un token di stringa opaco. Consulta anche Ottenere i token OAuth 2.0.

I seguenti esempi mostrano come utilizzare queste operazioni nel criterio OAuthV2. Gli esempi utilizzano il tipo di autorizzazione client_credentials; tuttavia, con queste operazioni puoi utilizzare uno qualsiasi dei tipi di autorizzazione supportati.

Nota: oltre a un token di accesso JWT, la risposta del criterio include anche un token di aggiornamento opaco.

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

Specifica l'elemento <Algorithm> con uno dei valori Algoritmi HMAC (HS256/HS384/HS512). Fornisci anche il <SecretKey>. L'esempio seguente mostra un criterio configurato per generare un JWT firmato con 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>

Le chiavi secret sono segrete. Per proteggere i secret, è buona prassi che il proxy API li recuperi da una mappa di valori chiave (KVM) basata sull'ambiente. Consulta anche Utilizzo delle mappe chiave-valore.

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 un JWT firmato 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>

Le chiavi private RSA sono segrete. Per proteggere i secret, è buona prassi che il proxy API li recuperi da una mappa di valori chiave (KVM) basata sull'ambiente. Consulta anche Utilizzo delle mappe chiave-valore.

Generazione di un token in formato JWT con il tipo di concessione 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>

Le chiavi private RSA sono segrete. Per proteggere i segreti, è una best practice per consentire al proxy API di recuperarle da una mappa valori chiavi (KVM) con ambito a livello di ambiente. Consulta anche Utilizzo delle mappe chiave-valore.

In fase di verifica

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

Verifica di 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 utilizzi l'operazione VerifyJWTAccessToken con un algoritmo HMAC, la configurazione del criterio deve utilizzare l'elemento <SecretKey> per specificare la chiave segreta utilizzata per firmare il JWT.

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

Le chiavi private sono segrete. Per proteggere i segreti, è una best practice per consentire al proxy API di recuperarle da una mappa valori chiavi (KVM) con ambito a livello di ambiente. Consulta anche Utilizzo delle mappe chiave-valore.

Verifica di un token di accesso JWT firmato con un algoritmo RSA

L'esempio seguente mostra come configurare il criterio OAuthV2 per verificare un JWT che è stato firmato con l'algoritmo RS512. Quando utilizzi l'operazione VerifyJWTAccessToken Con un algoritmo RSA, la configurazione del criterio deve usare l'elemento <PublicKey> per specificare la chiave pubblica che corrisponde 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>

La chiave pubblica non è un segreto. Le buone opzioni per l'archiviazione delle chiavi pubbliche includono una configurazione basata sull'ambiente set di proprietà o con ambito a livello di ambiente e una mappa chiave-valore (KVM). Consulta anche Accedere ai valori degli insiemi di proprietà e Utilizzare le mappe chiave-valore.

Aggiornamento

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

Aggiornamento di un token di accesso firmato con HMAC

L'esempio di criteri seguente illustra come configurare il criterio OAuthV2 per aggiornare un JWT firmato con un algoritmo HMAC. In questo caso, gli elementi <SecretKey> e <Algorithm> sono obbligatori.

La risposta dell'operazione di aggiornamento è simile a quella di un token appena generato. L'operazione di aggiornamento genera un nuovo token JWT con una data di scadenza aggiornata, mantenendo invariati gli altri claim.

<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

L'esempio di criteri seguente illustra come configurare il criterio OAuthV2 per aggiornare un 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>

Le chiavi private RSA sono segrete. Per proteggere i segreti, è una best practice per consentire al proxy API di recuperarle da una mappa valori chiavi (KVM) con ambito a livello di ambiente. Consulta anche Utilizzo delle mappe chiave-valore.

Esempio di risposta del token

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

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6ImF0K0pXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "token_type": "Bearer",
  "developer.email": "[e-mail]",
  "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 obbligatori dei criteri

La seguente tabella descrive gli elementi specifici 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 a cui si fa 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 a cui si fa 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 di token JWT:

Elemento	Note
ExternalAuthorization	Quando viene generato un token di accesso JWT, il criterio OAuthV2 convalida l'ID client e il segreto.
ExternalAccessToken	Quando viene generato un token di accesso JWT, il token viene firmato da Apigee e le rivendicazioni vengono fornite da Apigee per impostazione predefinita o tramite la configurazione delle norme. Il criterio supporta ExternalRefreshToken, che può essere utile per i casi d'uso di 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 al 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. Vengono concessi solo la password e il codice di autorizzazione supportano i token di aggiornamento.
• Includi l'intestazione Autorizzazione 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. Anche se un'applicazione o un gateway esterno che ha accesso alla chiave pubblica o segreta può decodificare i contenuti del JWT, l'applicazione esterna non dispone di informazioni sui prodotti API identificati dal claim client_id e, pertanto, non può svolgere un ruolo nell'autorizzazione del proxy API.