Guidance on migrating from password to alternative grant types

RingCentral has discontinued support for the password grant type for API authentication. To assist developers in transitioning to alternative authentication methods, this guide provides detailed recommendations and migration steps.

Selecting the Best Authentication Method

There are two primary alternatives to the password grant type:

1. JWT Authentication - Best suited for server-to-server use cases.

2. Authorization Code Flow - Best for user-centric applications.

Each method is discussed below to help you determine the best option for your application.

JWT Authentication

JWT authentication is ideal for applications operating in the background or requiring admin credentials for account-wide access.

Consider JWT if:

• Your application does not have a user interface and operates mainly in the background.

• Your application requires an admin to log in once to enable functionality across an entire account.

• You only need to collect a small number of credentials from users.

• Your users are comfortable using the Developer Console to generate JWT credentials.

Authorization Code Flow

The authorization code flow is designed for applications that require individual user authentication.

Consider the authorization code flow if:

• Each user must provide credentials for the application to function.

• Your application has a user interface where users enter their credentials.

• You initially considered authorization code flow but opted for password grant due to concerns about token expiration.

• Asking users to generate JWT tokens manually is impractical or confusing.

Migrating to JWT Authentication

Transitioning to JWT Auth Type

To switch to JWT authentication:

1. Log in to the Developer Console.

2. Edit your app’s settings and navigate to the "Auth" section.

3. Select "JWT Auth Flow" and click "Update."

Important: This change is irreversible. If you need to develop and test before fully migrating, consider registering a second app. If your app requires both password and JWT grant types temporarily, contact RingCentral support for assistance.

Updating Your Code for JWT Authentication

Migrating from password grant to JWT authentication is straightforward. If you are using a RingCentral SDK, the changes are minimal. For example, in JavaScript:

Before:

platform.login({
  'username': process.env.RC_USERNAME,
  'password': process.env.RC_PASSWORD,
  'extension': process.env.RC_EXTENSION
})

After:

platform.login({
  'jwt': process.env.RC_JWT
})

The authentication process remains the same: you provide credentials and receive an access key, which is then used in API calls.

Transitioning Credentials

To transition credentials seamlessly:

1. Generate or collect JWT credentials for each user before updating your app.

2. Store JWT credentials alongside existing username/password pairs.

3. Ensure all necessary JWT credentials are obtained before proceeding.

4. Deploy the new code.

5. Update the app settings to "JWT Auth Flow."

6. Conduct user acceptance testing.

7. Take the application out of maintenance mode.

Pro Tip: If you already have user login credentials, you can generate JWT credentials on their behalf via the Developer Console to streamline the transition.

Migrating to Authorization Code Flow

Since the password and authorization code flows differ significantly, migrating requires careful planning. The recommended migration strategy is:

1. Contact RingCentral support to enable both password grant and auth code flow for your app.

2. Implement the authorization code flow and deploy it to customers.

3. Prompt users to authenticate with RingCentral using OAuth.

4. Store and refresh access keys as needed.

5. Notify and engage users to transition to the new authentication method.

6. Once all users have migrated, request RingCentral support to disable password grant.

Managing Access Keys

A key challenge with the authorization code flow is keeping access keys fresh. Developers should implement a background service that:

• Regularly refreshes stored access tokens.

• Handles race conditions where an access token is invalidated when refreshed.

Getting Help and Support

We are committed to ensuring a smooth migration. If you need assistance:

• File a help ticket

• Engage with the RingCentral developer community

By following this guide, you can successfully transition away from password grant authentication while ensuring continued access to RingCentral's API.