JSON Web Token (JWT)

JSON Web Tokens (JWTs) are used to allow external systems to authorize and create Convergence users. JWT is an open industry standard defined in RFC 7519 that provides a secure way for two systems to transfer claims and/or assertions between them. Convergence uses JWTs to allow an external system to authenticate a user, using whatever mechanism they see fit, and to then allow that user to connect to Convergence without needing to provide a username and password.

Convergence has chosen to use the RS256 Asymmetric Key approach to establishing trust between the two systems. In this model a public / private key pair is generated and used to digitally sign the JWT via an RSA Signature using the SHA-256 hash algorithm. Convergence will store the public key so that it can verify the digital signature. The external system will store the private key and will use the private key to digitally sign the token containing information about the user that was authenticated.

On Demand User Creation / Update

When users log in using JWT, Convergence will check to see if a user account matching the username in the JWT already exists. If it does not, Convergence will automatically create a new user based on the claims supplied in the JWT. If the user does exist, Convergence will update the user based on the current claims provided.

Creating a JWT Key in Convergence

The first step in using JWT authentication is to create and enable a JWT Key in the Convergence Administration Console. You can accomplish this by:

Convergence JavaScript JWT Generators

Convergence provides a node module that is preconfigured to generate JWTs compatible with Convergence. This module greately reduces the complexity of generating a JWT from Node. The package can be installed as shown below:

npm install convergence-jwt

NOTE: The module is done but has not actually been posted to NPM. This is in progress.

Other Tools / Languages

If you are not developing in JavaScript, or you would just rather build your own JWT, there are several options out there for creating JWTs. Please reference http://jwt.io for a comprehensive list of tools for various platforms.