JWT and ACL overview

JWTs

Overview

The Stitch 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.

One way to create a new application is from the Nexmo CLI:

nexmo app:create "My Stitch App" https://example.com/answer https://example.com/event --type=rtc --keyfile=private.key
Application created: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
No existing config found. Writing to a new file.
Credentials written to /path/to/your/local/folder/.nexmo-app
Private Key saved to: private.key

You can also create a new application within the Nexmo Dashboard.

Claims

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

Claim Description
sub The "subject". The subject, in this case, will be the name of the user created in Stitch
acl Access control list. The Stitch API uses this as a permission system for users. Read more about it in the ACL overview
application_id This is the ID of the Nexmo Application you created.
iat "Issued at time" This is the time the JWT was issued, in unix epoch time.
jti "JWT ID". This is a unique identifier for this JWT.
exp "Expiration time" This is the time in the future that the JWT will expire, in unix epoch time.

The exp claim is optional. If the claim is not provided, then the JWT will expire by default in 15 minutes. The max expiration time for a JWT is 24 hours. JWTs should be typically short living, as it is trivial to create a new JWT and some JWTs can have multiple far-reaching permissions.

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": {
      "/v1/users/**": {},
      "/v1/conversations/**": {},
      "/v1/sessions/**": {},
      "/v1/devices/**": {},
      "/v1/image/**": {},
      "/v3/media/**": {},
      "/v1/applications/**": {},
      "/v1/push/**": {},
      "/v1/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 Stitch features.

Paths

Endpoint Description
/v1/sessions/** Log in as a User.
/v1/users/** Create and manage Users.
/v1/conversations/** Create and manage Conversations & send/receive messages.
/v1/image/** Send and receive images.
/v3/media/** Send and receive audio.
/v1/knocking/** Start Calls.
/v1/push/** Receive push notifications
/v1/devices/** Send push notifications.
/v1/applications/** Upload push notification certificate.

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 /v1/applications/**or /v1/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":{"/v1/users/**":{},"/v1/conversations/**":{},"/v1/sessions/**":{},"/v1/devices/**":{},"/v1/image/**":{},"/v3/media/**":{},"/v1/applications/**":{},"/v1/push/**":{},"/v1/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": {
    "/v1/users/**": {},
    "/v1/conversations/**": {},
    "/v1/sessions/**": {},
    "/v1/devices/**": {},
    "/v1/image/**": {},
    "/v3/media/**": {},
    "/v1/applications/**": {},
    "/v1/push/**": {},
    "/v1/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.

Nexmo::generateJwt([
        'application_id': "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
        'exp' => time() + 86400,
        'sub' => "jamie",
        'acl' => ["paths" => ["/v1/sessions/**" => (object)[], "/v1/users/**" => (object)[], "/v1/conversations/**" => (object)[], "/v1/devices/**" => (object)[], "/v1/image/**" => (object)[], "/v3/media/**" => (object)[], "/v1/applications/**" => (object)[], "/v1/push/**" => (object)[], "/v1/knocking/**" => (object)[]]],
    ])

Other languages

Creating a JWT with the appropriate claims for authenticating a Stitch user is not currently provided in any of the other Nexmo Client Libraries. Instead, we 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.