Criterio di decodifica JWT

Questa pagina si applica a Apigee e Apigee ibridi.

Visualizza la documentazione di Apigee Edge.

Cosa

Decodifica un JWT senza verificare la firma sul JWT. Ciò è particolarmente utile quando utilizzato con la normaVerifyJWT, quando il valore di una dichiarazione all'interno del JWT deve essere noto prima di verificare la firma del JWT.

Il criterio di decodifica JWT funziona indipendentemente dall'algoritmo utilizzato per firmare il JWT. Per un'introduzione dettagliata, consulta la panoramica delle norme JWS e JWT.

Questo criterio è un criterio standard e può essere implementato in qualsiasi tipo di ambiente. Per informazioni sui tipi di criteri e sulla loro disponibilità in base a ciascun tipo di ambiente, consulta Tipi di criteri.

Video

Nota: il seguente video mostra la versione classica dell'Editor proxy nello UI di Apigee. Apigee sta introducendo una nuova versione di Proxy Editor, che ha un design diverso dalla versione classica mostrata nel video.

Guarda un breve video per imparare a decodificare un JWT.

Esempio: decodifica un JWT

Il criterio mostrato di seguito decodifica un JWT trovato nella variabile di flusso var.jwt. Questa variabile deve essere presente e contenere un JWT valido (decodificabile). Il criterio può ottenere il JWT da qualsiasi variabile di flusso.

<DecodeJWT name="JWT-Decode-HS256">
    <DisplayName>JWT Verify HS256</DisplayName>
    <Source>var.jwt</Source>
</DecodeJWT>

Il criterio scrive l'output nelle variabili di contesto in modo che i criteri o le condizioni successive nel proxy API possono esaminare questi valori. Consulta Variabili di flusso per un elenco delle variabili impostate da questo criterio.

Riferimento degli elementi per la decodifica JWT

La guida di riferimento al criterio descrive gli elementi e gli attributi del criterio Decode JWT.

Attributi che si applicano all'elemento di primo livello

<DecodeJWT name="JWT" continueOnError="false" enabled="true" async="false">

I seguenti attributi sono comuni a tutti gli elementi principali dei criteri.

Attributo	Descrizione	Predefinito	Presenza
nome	Il nome interno del criterio. I caratteri utilizzabili nel nome sono limitati a: A-Z0-9._\-$ %. Tuttavia, la UI di Apigee applica come la rimozione automatica di caratteri non alfanumerici. Se vuoi, utilizza l'elemento <displayname></displayname> per etichettare il criterio nell'editor proxy dell'interfaccia utente di Apigee con un nome diverso in linguaggio naturale.	N/D	Obbligatorio
continueOnError	Imposta su false per restituire un errore quando un criterio non va a buon fine. Questo è un comportamento previsto per la maggior parte dei criteri. Imposta su true per continuare l'esecuzione del flusso anche dopo un fallimento del criterio.	falso	Facoltativo
abilitato	Imposta il valore su true per applicare il criterio. Imposta su false per "disattivare" il criterio. Il criterio non verrà applicato in modo forzato anche se rimane collegato a un flusso.	true	Facoltativo
asinc	Questo attributo è obsoleto.	falso	Ritirato

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

Da utilizzare insieme all'attributo name per etichettare il criterio nell'editor proxy dell'interfaccia utente di Apigee con un nome diverso in linguaggio naturale.

Predefinito	Se ometti questo elemento, viene utilizzato il valore dell'attributo nome del criterio.
Presenza	Facoltativo
Tipo	Stringa

<Source>

<Source>jwt-variable</Source>

Se presente, specifica la variabile di flusso in cui il criterio si aspetta di trovare il JWT da decodificare.

Nota: per impostazione predefinita, il JWT viene recuperato dalla variabile request.header.authorization In questo caso, Apigee cerca il JWT nell'intestazione Authorization della richiesta. Se passi il JWT nell'intestazione Authorization, non devi includere l'elemento Source nel criterio. Tuttavia, devi includere Bearer nell'intestazione di autenticazione. Ad esempio, puoi passare il JWT nell'intestazione Authorization come segue:

curl -v http://52.200.92.187:9001/doctest-jwt/verify-rs256 -H "Authorization: Bearer <your JWT>"

Puoi configurare il criterio per recuperare il JWT da una variabile di parametro di query o modulo o da qualsiasi un'altra variabile. Se la variabile non esiste o se il criterio non riesce a trovare il JWT, il criterio restituisce un errore.

Predefinito	request.header.authorization (consulta la nota sopra per informazioni importanti sull'impostazione predefinita).
Presenza	Facoltativo
Tipo	Stringa
Valori validi	Nome della variabile di flusso Apigee

Variabili di flusso

Se l'operazione riesce, i criteri Verify JWT (Verifica JWT) e Decode JWT (Decodifica JWT) sono stati impostati. variabili di contesto in base a questo pattern:

jwt.{policy_name}.{variable_name}

Ad esempio, se il nome del criterio è jwt-parse-token, il criterio memorizza il soggetto specificato nel JWT nella variabile di contesto denominata jwt.jwt-parse-token.decoded.claim.sub. Per la compatibilità con le versioni precedenti, sarà disponibile anche in jwt.jwt-parse-token.claim.subject.

Nome variabile	Descrizione
claim.audience	L'attributo del segmento di pubblico JWT. Questo valore può essere una stringa o un array di stringhe.
claim.expiry	La data e l'ora di scadenza, espresse in millisecondi dall'epoca.
claim.issuedat	La data di emissione del token, espressa in millisecondi dall'epoca.
claim.issuer	La rivendicazione dell'emittente JWT.
claim.notbefore	Se il JWT include un claim nbf, questa variabile conterrà il valore, expressed in milliseconds since epoch.
claim.subject	L'affermazione del soggetto JWT.
claim.name	Il valore dell'attestazione denominata (standard o aggiuntiva) nel payload. Uno di questi verrà impostato per ogni rivendicazione nel payload.
decoded.claim.name	Il valore decodificabile in JSON dell'affermazione denominata (standard o aggiuntiva) nel payload. È impostata una variabile per ogni richiesta nel payload. Ad esempio, puoi utilizzare decoded.claim.iat per recupera il valore emesso al momento del JWT, espresso in secondi dall'epoca. Mentre puoi anche usare le variabili di flusso claim.name, queste sono variabile consigliata da utilizzare per accedere a una rivendicazione.
decoded.header.name	Il valore analizzabile in JSON di un'intestazione nel payload. È impostata una variabile per ogni intestazione nel payload. Sebbene tu possa utilizzare anche le variabili di flusso header.name, questa è la variabile consigliata per accedere a un'intestazione.
expiry_formatted	Data e ora di scadenza, formattate come stringa leggibile. Esempio: 2017-09-28T21:30:45.000+0000
header.algorithm	L'algoritmo di firma utilizzato nel JWT. Ad esempio, RS256, HS384 e così via. Per saperne di più, consulta Parametro intestazione(algoritmo).
header.kid	L'ID chiave, se aggiunto al momento della generazione del JWT. Consulta anche la sezione "Utilizzo di un set di chiavi web JSON (JWKS)" presso JWT panoramica dei criteri per verificare un JWT. Per saperne di più, consulta la sezione Parametro dell'intestazione (ID chiave).
header.type	Verrà impostato su JWT.
header.name	Il valore dell'intestazione denominata (standard o aggiuntiva). Una di queste sarà impostata su ogni intestazione aggiuntiva nella parte di intestazione del JWT.
header-json	L'intestazione in formato JSON.
is_expired	true o false
payload-claim-names	Un array di attestazioni supportate dal JWT.
payload-json	Il payload in formato JSON.
seconds_remaining	Il numero di secondi prima della scadenza del token. Se il token è scaduto, questo numero sarà negativo.
time_remaining_formatted	Il tempo rimanente prima della scadenza del token, formattato come stringa leggibile. Esempio: 00:59:59.926
valid	Nel caso di VerifyJWT, questa variabile sarà vera quando la firma è verificata e l'ora corrente è precedente alla scadenza del token e successiva al valore notBefore del token, se sono presenti. In caso contrario, false. Nel caso di DecodeJWT, questa variabile non è impostata.

Messaggi di errore

Questa sezione descrive i codici di errore e i messaggi di errore restituiti e le variabili di errore impostate da Apigee quando questo criterio attiva un errore. Queste informazioni sono importanti se stai sviluppando regole di errore per gestire gli errori. Per scoprire di più, consulta Informazioni importanti sugli errori relativi alle norme e Gestione degli errori.

Errori di runtime

Questi errori possono verificarsi durante l'esecuzione del criterio.

Codice guasto	Stato HTTP	Causa	Correggi
steps.jwt.FailedToDecode	401	Si verifica quando il criterio non è in grado di decodificare il JWT. Il JWT potrebbe avere un formato non corretto, non essere valido o non essere decodificabile.
steps.jwt.FailedToResolveVariable	401	Si verifica quando la variabile di flusso specificata nell'elemento <Source> del criterio non esiste.
steps.jwt.InvalidToken	401	Si verifica quando la variabile di flusso specificata nell'elemento <Source> del criterio non rientra nell'ambito o non può essere risolta.

Errori di deployment

Questi errori possono verificarsi quando esegui il deployment di un proxy contenente questo criterio.

Nome dell'errore	Causa	Correggi
InvalidEmptyElement	Si verifica quando la variabile di flusso contenente il JWT da decodificare non è specificata nell'elemento <Source> del criterio.

Variabili di errore

Queste variabili vengono impostate quando si verifica un errore di runtime. Per ulteriori informazioni, vedi Cosa devi sapere sugli errori relativi alle norme.

Variabili	Dove	Esempio
fault.name="fault_name"	fault_name è il nome dell'errore, come indicato nella tabella Errori di runtime sopra. Il nome dell'errore è l'ultima parte del codice di errore.	fault.name Matches "InvalidToken"
JWT.failed	Tutti i criteri JWT impostano la stessa variabile in caso di errore.	JWT.failed = true

Esempio di risposta di errore

Per la gestione degli errori, la best practice è intercettare la parte errorcode della risposta all'errore. Non fare affidamento sul testo in faultstring, perché potrebbe cambiare.

Esempio di regola di errore

    <FaultRules>
        <FaultRule name="JWT Policy Errors">
            <Step>
                <Name>JavaScript-1</Name>
                <Condition>(fault.name Matches "InvalidToken")</Condition>
            </Step>
            <Condition>JWT.failed=true</Condition>
        </FaultRule>
    </FaultRules>