JWT Keys and RingCentral API Connections

One of the basic challenges that traditional server-to-server communications face is the sometimes fragile connections that can exist between them. You can see these challenges play out in RingCentral applications in two different ways.

Password-based authentication challenges for private apps

Customarily at RingCentral, private server-to-server connections are facilitated by password-based authentication for the following reasons:

• Server-to-server interfaces lack a user interface to enable more traditional three-legged OAuth flows.
• All actions performed by the underlying backend service are done via a single user identity, often referred to as a “service user.”

Password-based authentication has been ideal in these circumstances since you don’t need to share your password with anyone outside your organization, and creating a whole user interface to connect a single user is overkill.

However, password-based authentication is still far from perfect. The simple act of a user changing their password can inadvertently sever the connection between two servers that need to reliably converse. Also, password-based authentication is incompatible with accounts that require the use of an external Single Sign-On provider, not to mention the obvious concerns associated with the need to store password credentials in plain-text on your servers.

Auth code flow challenges associated with 3rd-party backend services

Additionally, sometimes a backend service provided by a third-party vendor also needs access to your account. In this circumstance, password-based authentication is not even an option because password-based authentication is restricted to internal/private applications only. Vendors therefore must not only implement a three-legged auth flow, but must also implement additional services devoted to the task of keeping auth sessions from expiring or timing out in order to maintain continuity.

Even then, a user changing their password can still disrupt access between RingCentral and their backend service.

The solution

Enter the “JWT” (pronounced “jot”), short for JSON Web Token — a form of authentication that relies on an independently generated credential that can be configured to never expire, and can easily be exchanged with others or stored securely in a vault to be accessed by your application. By employing JWT authentication, developers can greatly reduce the complexity of their implementations and reduce overhead associated with maintaining access and refresh tokens.

JWT is a relatively new Internet-based standard for establishing and maintaining secure and authorized communication between protected web entities such as a Content Delivery Network (CDN) or an API service.

This new form of authentication supported by RingCentral allows for the creation of a unique cryptographic key that can be used for quick, secure, and efficient API access. It is an ideal substitute for brokering all forms of access between server-to-server applications because it successfully addresses the many challenges discussed above. JWT auth credentials:

• never expire by default
• are immutable
• are compatible with accounts configured for Single Sign-On
• work with both public and private apps

RingCentral is pleased to be able to provide this additional security option to their API clients, alongside the auth code and PCKE flows currently supported, as it offers yet another secure path to API use.

How JWT authentication works

JWT authentication is powered by cryptographic keys (also referred to as “credentials”) created within the RingCentral Developer Console. Each credential is bound to a specific user, and each user is able to generate multiple credentials for themselves for maximum security and audit ability.

As mentioned, JWT credentials are generated and managed within the Developer Console. Not only can developers manage their personal set of credentials, but administrators can manage all of the credentials within their organization. This ensures that the person generating the credential is already authorized and vetted to do so.

After the JWT key is created on the development platform it can be used repeatedly for authentication purposes. The following figure shows the process of how the JWT credential is employed.

In the top portion, an access token is requested by offering the JWT credential. The Authorization Server unpacks the JWT key and validates it. Once validated the Authorization Server returns an access token. Then, in the second part of the figure, the access token is used to gain entry to the protected content on the Resource Server.

Restricting credentials to specific applications for added security

RingCentral has added an additional feature on top of the basic creation of JWTs: the ability to securely restrict the use of JWT credentials to specific applications.This is accomplished by specifying the Client IDs of the applications you wish to restrict a credential to. With this approach, admins can have separate JWT credentials for individual applications or have a subset of applications all share the same credential. This gives admins the power to implement granular access control policies within their organization.

Conveniently, this also makes it easier for organizations to work with freelance developers as you can grant a third-party access to an application without the risk of affecting any other application projects that you are working on within the same account. Furthermore, access can then be terminated if and when the freelancer has completed their work.

To restrict a JWT credential to a specific application, on the screen where the JWT is created there is an area where you can assign one or multiple Client IDs to the JWT. It will look similar to that shown in the following image.

Once you create the application connection it will be added to a list of connected apps on the display of the JWT credential.

Summary

The addition of the JWT authentication for accessing apps that communicate with RingCentral’s APIs is a big step forward for RingCentral developers. The added security, ease of use, and convenience are all welcome additions to the development process.

More information can be found here: JWT Developer Guide

Please let us know what you think by leaving your questions and comments below. To learn even more about other features we have make sure to visit our developer site and if you’re ever stuck make sure to go to our developer forum.

Want to stay up to date and in the know about new APIs and features? Join our Game Changer Program and earn great rewards for building your skills and learning more about RingCentral!