Questa pagina si applica a Apigee e Apigee ibridi.
Visualizza documentazione di Apigee Edge.
Questo argomento spiega come generare, verificare e aggiornare i token di accesso JWT utilizzando il token Criterio 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 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 con codifica Base64 che consiste un'intestazione, un payload e una firma separati da punti. Ad esempio:
I contenuti codificati di questi elementi
dipendono da come configuri
il criterio OAuthV2. Nel criterio, puoi specificare parametri quali
l’algoritmo di firma e gli elementi del payload, come l’oggetto e il nome. Ad esempio, l'intestazione
potrebbe decodificare come {"alg":"HS256","typ":"at+JWT"}
e
il payload potrebbe decodificare come: {"sub":"ABC1234567","iat":1516239022}
.
Intestazione
L'intestazione specifica una dichiarazione typ
(sempre "at+JWT
) e una dichiarazione alg
, che indica l'algoritmo utilizzato per firmare il JWT. Apigee
supporta RSA e algoritmi 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
password o tipi di concessioni di autorizzazione). 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 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 termini di tempo dell'epoca (in secondi). | Apigee |
iat |
L'espressione emessa al momento, ovvero il momento 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. Vedi anche Utilizzo degli ambiti OAuth. | Sviluppatore API |
Firma
La firma viene generata utilizzando l'intestazione, il payload, la chiave segreta/privata codificati 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 IETF RFC 9068: Profilo JWT (JSON Web Token) per token di accesso OAuth 2.0.
Prerequisiti
Questo documento presuppone la conoscenza di come generare e verificare i token di accesso OAuthV2 usando il criterio OAuthV2. Sia che utilizzi le operazioni JWT sia le operazioni tradizionali creano token di stringa opaci, l'utilizzo di base del criterio OAuthV2 è lo stesso. Puoi usare JWT con tutti i tipi di autorizzazione OAuthV2 supportati. Consulta anche Introduzione a OAuth 2.0.
Generazione
Utilizza GenerateJWTAccessToken
e GenerateJWTAccessTokenImplicitGrant
operative per generare un token di accesso JWT con
Criterio OAuthV2. Queste operazioni sono simili alle tradizionali GenerateAccessToken
e GenerateAccessTokenImplicitGrant
del criterio
operazioni. La differenza principale è che l'operazione JWT restituisce un token di accesso in formato JWT
invece
di un token di stringa opaco. Vedi anche Recuperare i token OAuth 2.0.
I seguenti esempi mostrano come utilizzare queste operazioni
nel criterio OAuthV2. Negli esempi viene utilizzato il tipo di autorizzazione client_credentials
. ma puoi
utilizza uno qualsiasi dei tipi di concessioni supportati con queste operazioni.
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>
Generare 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>
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. Le seguenti
un esempio mostra l'uso dell'algoritmo RS256. Per questo motivo, <PrivateKey>
è obbligatorio. Vedi anche
Utilizza 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
Criterio OAuthV2. Questa operazione è simile all'operazione VerifyAccessToken
operativa; 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 JWT
firmato con l'algoritmo HS512. Quando utilizzi l'operazione VerifyJWTAccessToken
Con un algoritmo HMAC, la configurazione del criterio deve usare 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>
Verificare 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>
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 HMAC
Il seguente esempio di criteri illustra come configurare il criterio OAuthV2 per aggiornare un JWT
firmato con un algoritmo HMAC. <SecretKey>
e <Algorithm>
sono obbligatori in questo caso.
La risposta dell'operazione di aggiornamento è simile a quella di un token appena generato. Aggiornamento l'operazione genera un nuovo token JWT con data di scadenza aggiornata, mantenendo invariate le altre rivendicazioni.
<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 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 del token
Per le operazioni di generazione e aggiornamento, il corpo della risposta è simile al seguente
esempio. 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 viene generato un token di accesso JWT, il criterio OAuthV2 convaliderà l'ID client e il secret. |
ExternalAccessToken | Quando generi un token di accesso JWT, questo viene firmato da Apigee
le attestazioni saranno fornite da Apigee per impostazione predefinita o tramite configurazione dei criteri.
Il criterio non supporta ExternalRefreshToken , che può essere utile in
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. Sebbene
un'applicazione o un gateway esterno che ha accesso alla chiave pubblica o segreta può decodificare
contenuto del JWT, l'applicazione esterna non dispone di informazioni sui prodotti API
identificati dalla rivendicazione
client_id
e pertanto non possono svolgere un ruolo Autorizzazione proxy API.