> For the complete documentation index, see [llms.txt](https://iothentix.gitbook.io/developer-guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://iothentix.gitbook.io/developer-guide/json-web-token-jwt/authentication-jwt.md).

# Authentication JWT

To authenticate IoT devices to our IdP, we rely on the state-of-art authentication method called **private key JWT authentication**. This requires the IoT device to create a private key JWT which is a JSON object that consists of three parts, a header, a body, as well as a signature. 

### Structure

A private key JWT is a base64 encoded JSON object that is composed of the three parts concatenated and separated by a dot. An example of how a fully assembled JWT may look is displayed below.

```
eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InRlc3QuZGV2aWNlLjAxIn0.eyJzdWIiOiJ0ZXN0LmRldmljZS4wMSIsImp0aSI6IkE2NTU4QjVENzI5OTk1MUU1MjQxRTI5QTg1MkNBQjNDIn0.UX7a95u7BpkLg0IVbJDxA3w82M8IrSsxxdwIPxlfGOawBy3GaCKUI7OpVyCRHRxHnJn7cHA_qoAchkmwrW7luA
```

There is a handy [web tool](https://jwt.io) available to review any JWT online. 

Now, let's have a look at the individual components and which claims they have to contain in order to use the JWT to authenticate an IoT device with our IoT IdP.

#### Header

The header object contains three claims: 

* **alg**: The cryptographic algorithm used to generate the signature of the JWT.
* **typ**: The type of JWT the object represents. Has to be set to `JWT`. 
* **kid**: The id of the key used to generate the signature of the JWT. This claim has to correspond to the device ID registered with IoT IdP.

An example of how a JWT header may look is displayed below. 

```
{
  "alg": "ES256",
  "typ": "JWT",
  "kid": "test-device-01"
}
```

#### Body

The body has two contain two claims

* **sub**: The subject of the JWT. This claim has to correspond to the device ID registered with the IoT IdP.
* **jti**: The JWT ID is a 32-character long hexadecimal random number, which has to be unique. As a result, preventing replay attacks and ensures that an issued JWT can only be used once for each device. 

An example of how a JWT body may look is displayed below.

```
{
  "sub": "test-device-01",
  "jti": "A6558B5D7299951E5241E29A852CAB3C"
}
```

#### Signature

The signature is generated using the private key that corresponds to the registered public key and the defined algorithm in the **alg** claim of the header, e.g. for the above-displayed header the signature is calculated as follows. 

```
ECDSASHA256(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload)
)
```