# IT:AD:JWT #



<callout type="Navigation" class="small">

* [[../|(UP)]]
{{indexmenu>.#2|nsort tsort}}
* See also:
  * [[IT/AD/JWS/]]
  * [[IT/AD/id_token/]]
  * [[IT/AD/Certificates/]]
  * [[IT/AD/REST/]]
  * https://jwt.io/
  * [[IT/AD/OIDC/]]
  * [[IT/AD/OAuth/]]
  * https://evertpot.com/jwt-is-a-bad-default/
  * https://hasura.io/blog/best-practices-of-using-jwt-with-graphql/
  * https://medium.com/permify-tech-blog/jwt-vs-paseto-new-era-of-token-based-authentication-68b5ca6c3a32
  * [[IT/AD/PASETO/]]


</callout>


<panel title="Summary">

A JSON Web Token (JWT) is a JSON object that is defined in RFC 7519 as a safe and compact way to represent a set of information (claims) between two parties.  The token is string composed of a header, a payload, and a signature (JSON Web Signature (JWS)).

<sxh>
header.payload.signature
</sxh>

The purpose of using JWT is **NOT** to hide data in any way (encoded and signed, not encrypted) -- it is to prove that the sent data was actually created by an authentic source.


</panel>


## Structure ##

The 3 parts, separated by `.`, are as follows:

### Header ###
The Header is for describing the encryption used. 

<sxh>
{
    "typ": "JWT",
    "alg": "HS256"
}
</sxh>



### Payload ###

The payload is any valid JSON object. 

[[IT/AD/OIDC/]] uses [[IT/AD/JWT/]] for it's [[IT/AD/id_token/]], which looks like:

<sxh javascript>
{
  "sub"       : "jsmith",
  "iss"       : "https://openid.c2id.com",
  "aud"       : "client-12345",
  "nonce"     : "n-0S6_WzA2Mj",
  "auth_time" : 1311280969,
  "acr"       : "c2id.loa.hisec",
  "iat"       : 1311280970,
  "exp"       : 1311281970,
}
</sxh> 



### Signature ###

The signature is a hash of a concatenation of the base64 Header and base64 Body, using the shared client `secret`.



### JWT ###
The 3 parts are combined into a JWT string as follows:

<sxh javascript>
var base64Header = base64urlEncode(header);
var base64Body = base64urlEncode(payload)
var signatureHash = Hash(data,secret,hashAlgorythmToUse);
var jwt = base64Header+"."+base64Body+"."+signatureHash;
</sxh>



### Usage ###

[[IT/AD/OIDC/]] uses [[IT/AD/JWT/]]s for passing back the [[IT/AD/id_token/]].

[[IT/AD/SPA/]]s embed the JWT token as Cookies or headers when accessing APIs (each has its own use case and advantages/disadvantages).

## Verification ##

Once the `client` has received the JWT from a `resource server`, it can check the signature. 

It does this by:
* unencoding the header and body (they're not encrypted -- just base64'ed).
* from the body, can see who authenticated the client (`iis`).
* Therefore, it can get the `iis`'s shared secret, in order to
* create a hash of the base64header and base64body.
* if they match, the contents are good.

## Usage

Note that the token is not encrypted -- so can only be used with trusted components.

Examples are between [[IT/AD/OAuth/]] `client` and `resource service`.


### Assertions

JWT's can be used as Assertions:

* https://tools.ietf.org/html/rfc7523

## Resources ##

* https://medium.com/vandium-software/5-easy-steps-to-understanding-json-web-tokens-jwt-1164c0adfcec
* http://jwt.io/
* https://medium.com/vandium-software/5-easy-steps-to-understanding-json-web-tokens-jwt-1164c0adfcec
* https://en.wikipedia.org/wiki/JSON_Web_Token
* https://connect2id.com/learn/openid-connect