JSON web token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained method for securely transmitting JSON-encoded information between parties. At ​Akamai​, you can use JWTs to quickly identify and authorize OTA Updates clients who send requests to origin servers.

A JWT contains information about an entity in the form of claims and combines three elements encapsulated in JSON objects:

• Header
  Contains information about the media type of the JWT and the hashing algorithm used for encoding the JWT.

• Payload
  Contains the actual statements represented as public claims that two parties exchange. Currently, the IoT products support the use of pre-defined registered and private claims. For more information, see IoT-supported registered claims.

• Signature
  Ensures the proper identification of the request sender and protects the request from being tampered with.

JWTs are stateless, which means that incoming JWT requests can be validated on the spot. You don't have to store session states on the server and load user information from a database or cache. This immediate validation increases the scalability of your system and provides an overall faster client-server experience.

​Akamai​ verifies JWT signatures at the edge, which negates the need to go back to origin for verification and offloads your identity provider. This behavior also contributes to improved security by allowing edge servers to filter out unauthorized requests before they can reach your origin infrastructure.

The IoT products support the use of RSA private/public key pairs for JWT signature verification. This ensures the data in the JWT payload has not been modified by third parties. Your identity provider first signs a JWT by using a private key. The IoT products then verify the integrity of the JWT by using a public key that you upload in the Token Access Control application.

Based on your JWT claim configuration, the IoT products check the token for the presence of claims and validates the value of each present claim. If the optional claims are present and their expected values are correct, JWT validation succeeds and the system allows the entity issuing the JWT to access the requested resources.

For more information on the JWT standard, see the JWT specification.

Signing algorithms

The IoT products support verification of JWT signatures generated with these algorithms:

• RS256
  RSA Digital Signature Algorithm with the SHA–256 hash function. It's an asymmetric algorithm that uses a pair of RSA private and public keys to generate and validate JWT signatures. For IoT, you can use only RSA keys with a key length between 1024 and 4096 bits. See JWT algorithms.

• ES256
  Elliptic Curve Digital Signature Algorithm with the P–256 curve and the SHA–256 hash function. It's an asymmetric algorithm that uses a pair of ECDSA private and public keys to generate and validate JWT signatures. For IoT, you can use only ECDSA keys using the P–256 (secp256k1) curve. See JWT algorithms.

Create a JWT key collection

A collection is a namespace that indicates a particular set of public keys. Typically, you need to refer to a key collection in the IoT JSON web token (JWT) verification behaviors to indicate the public keys that you want to use to check the integrity of clients' JWT signatures. A new key collection doesn't include public keys and isn't active in the staging or production environments.

Before you begin, complete this step if you want to use JWTs as an authentication method.

1. Go to ☰ > IOT SOLUTIONS > Token access control.

2. Click New collection on the JWT Key Collections page.

3. In the Create new collection window, enter a unique name for the key collection and click Create.

   The empty collection appears in the list of all key collections.

4. Click Manage next to an appropriate key collection.

5. In the <key collection name> window:

   • If you're uploading public keys to an empty key collection, click Upload your first keys.

   • If you're uploading public keys to a collection version, click New version.

   You can generate a pair of new keys externally. On Mac and Linux, use the following commands:

   ssh-keygen -m PEM -t rsa -b 4096 -f jwtRS256.key
   # Don't add a passphrase
   openssl rsa -in jwtRS256.key -pubout -outform PEM -out jwtRS256.key.pub
   

6. On the New Version page:

   1. In Description, enter a meaningful description of the key collection version.

   2. In Primary Key, upload the primary RSA public key for the JWT signature verification.

   3. Optional: In Backup Key, upload the backup RSA public key that you want to use in case the primary key fails to verify the JWT signature.

   4. Click Create.

7. Activate the JWT key collection:

   1. In JWT Control Access, click Manage next to the appropriate key collection name.

   2. On the Key collection name page, click the version that you want to activate.

      The system numbers key collection versions in ascending order with the highest number indicating the latest version.

   3. On the Version page, click Activate on production.

      The activation process may take up to 30 minutes.
      You can track the activation's progress in the collections details view.

The collection version appears in the list of all collection's versions. The system assigns the highest number to the new collection version.

Configure the JWT verification behavior

JSON web token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained method for securely transmitting JSON-encoded information between parties. Use this behavior to quickly identify and authorize consumers who send requests to your origin server. You can specify the HTTP header in client requests where a JWT is passed and the collection of public keys used to verify the integrity of that token.

1. Access Property Manager configurations associated with the selected ​Akamai Control Center​ account. Go to ☰ > CDN > Properties (or just enter Properties in the search box).

   The Property Groups page opens.

2. Click the Property Name link for your property.

3. On the Property Details page, click the Version of your configuration that you want to access in Manage Versions and Activations.

4. On the Property Manager Editor page, select Default Rule in Property Configuration Settings.

5. In Behaviors, add the JWT Verification behavior.

   You can add one JWT verification behavior in an OTA Updates property.

6. Select JWT location from the dropdown:

   • Select Request header to extract JWTs from a custom request header.

   • Select Query string parameter to extract JWTs from a custom query string parameter.

7. In JWT key collection, select the name of the active key collection to verify a token's signature. If you don't have a key collection, see Create a JWT key collection.

   When selecting a key collection, pay attention to the following:

   • The key collection needs to be active in the environment where you're activating your property. For example, if you're activating the property on staging, the key collection needs to be already active in the staging environment.

   • The key collection needs to store public keys that match the type of algorithm you use to sign JWTs. For example, if you allow authentication with tokens signed with the RS256 algorithms, the JWT collection needs to store RSA public keys.

📘

You can check if a key collection is active in either environment and the type of public keys it stores next to this key collection name in the JWT key collection dropdown.

8. Specify one or more algorithms that you want to use to sign your JWTs:

   • Set Allow RS256 to Yes to allow authentication with tokens signed with the RS256 algorithm.

   • Set Allow ES256 to Yes to allow authentication with tokens signed with the ES256 algorithm.

   See Signing algorithms.

IoT-supported registered claims

The following table lists the optional public registered claims that you can encode and transmit as the payload of a JSON web token (JWT).

Supported public registered claims