# 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)
)
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://iothentix.gitbook.io/developer-guide/json-web-token-jwt/authentication-jwt.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.