JSON web token


To authorize both subscriber and publisher, you can use JWT and Mutual Authentication. To complete the configuration you have to configure at least one of these methods.

Verify JSON web token

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 and Edge Connect 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 reserved and private claims.

  • Signature
    Ensures the proper identification of the request sender and protects the request from being tampered with. Note that the IoT products support verifying JWT signatures generated with the RS256 and ES256 signing algorithms. For more information, see Signing algorithms.

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 JWT 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 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. For Mac and Linux, see Generate RSA keys.

  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. Optiona: 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.