How to generate JWTs

JWTs

Overview

The Vonage Client SDKs use JWTs for authentication when a user logs in. These JWTs are generated using the application ID and private key that is provided when a new application is created.

Claims

Using that private.key and the application ID, we can mint a new JWT. In order to log a user into a Nexmo client, the JWT will need the following claims:

Sample JWT Payload

Once all the claims have been provided, the resulting claims should appear like so:

{
  "iat": 1532093588,
  "jti": "705b6f50-8c21-11e8-9bcb-595326422d60",
  "sub": "jamie",
  "exp": "1532179987",
  "acl": {
    "paths": {
      "/*/users/**": {},
      "/*/conversations/**": {},
      "/*/sessions/**": {},
      "/*/devices/**": {},
      "/*/image/**": {},
      "/*/media/**": {},
      "/*/applications/**": {},
      "/*/push/**": {},
      "/*/knocking/**": {}
    }
  },
  "application_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
}

ACLs

Overview

In the previous section, you can see that the acl claim has paths object containing multiple endpoints. These endpoints correspond with certain permissions a user can have when utilizing Client SDK features.

Paths

It is not necessary to provide users with the permissions to access all of these paths. For instance, if a user was not going to upload or receive push notifications, you could create a JWT without including the /*/applications/**or /*/push/** paths.

Nexmo Client Libraries

CLI

Currently, you can use the beta version of the Nexmo CLI to create a JWT including the appropriate claims

nexmo jwt:generate ./private.key sub=jamie exp=$(($(date +%s)+86400)) acl='{"paths":{"/*/users/**":{},"/*/conversations/**":{},"/*/sessions/**":{},"/*/devices/**":{},"/*/image/**":{},"/*/media/**":{},"/*/applications/**":{},"/*/push/**":{},"/*/knocking/**":{}}}' application_id=YOUR_APP_ID
> JWT: [...JWT String...]

Node

The beta version of the Nexmo Node library can also create a JWT including the appropriate claims

const aclPaths = {
  "paths": {
    "/*/users/**": {},
    "/*/conversations/**": {},
    "/*/sessions/**": {},
    "/*/devices/**": {},
    "/*/image/**": {},
    "/*/media/**": {},
    "/*/applications/**": {},
    "/*/push/**": {},
    "/*/knocking/**": {}
  }
}

Nexmo.generateJwt(PRIVATE_KEY, {
            application_id: "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
            sub: "jamie",
            //expire in 24 hours
            exp: Math.round(new Date().getTime()/1000)+86400,
            acl: aclPaths
          })

PHP

The current version of the Nexmo PHP library can also create a JWT including the appropriate claims when using the Keypair authentication.

$keypair = new \Nexmo\Client\Credentials\Keypair(
    file_get_contents('/path/to/private.key'),
    'aaaaaaaa-bbbb-cccc-dddd-0123456789ab'
);
$client = new \Nexmo\Client($keypair);

$claims = [
    'acl' => [
        'paths' => [
            '/*/users/**' => (object) [],
            '/*/conversations/**' => (object) [],
            '/*/sessions/**' => (object) [],
            '/*/devices/**' => (object) [],
            '/*/image/**' => (object) [],
            '/*/media/**' => (object) [],
            '/*/applications/**' => (object) [],
            '/*/push/**' => (object) [],
            '/*/knocking/**' => (object) [],
        ]
    ]
];
$token = $client->generateJwt($claims);
$tokenString = (string) $token;

Other languages

Creating a JWT with the appropriate claims for authenticating a Nexmo user is not currently provided in any of the other Nexmo Client Libraries. Instead, you are encourage you to use your JWT library of choice to create a new JWT with the Sample JWT Payload. JWT.io has a selection of libraries for generating JWTs in multiple languages.

---