This year we announced RingCentral's plans to discontinue support for the password grant type for authenticating against the API. To assist developers in successfully transitioning away from this authentication method, we have assembled the following guidance.
Selecting the best auth type to migrate to
There are two different alternative methods for authenticating against the API which are applicable to the vast majority of developers. Each of these methods is discussed in greater detail below, with detailed guidance for determining which is most appropriate for your use case.
Once you determine the right auth method to migrate to, we will then provide guidance and pointers on how to successfully migrate.
JWT Auth
JWT auth is best for server-to-server use cases. Think about the following questions to see if JWT is best for your application.
If your application does not have a user interface, and operates mainly in the background (perhaps even on a schedule), then JWT is probably best.
If your application prompts an admin to log in and provide their credentials to enable the application to work across and entire account, then JWT is probably best.
If your application only needs to collect a very small or finite number of credentials from users in order to operate, then JWT is probably best.
If your users will in no way be intimidated or daunted by logging into the Developer Console to generate an obscure JWT credential, then JWT is potentially a good option.
Authorization code flow
The authorization code flow is best for user-centric use cases. Think about the following questions to see if the authorization doe flow is best to migrate to.
If your application needs each user in an account to provide credentials in order for the application to function properly, then the auth code flow is probably best.
If your application has a user interface that users interact with directly to provision or provide credentials, then the auth code flow is probably best.
If you originally considered the auth code flow, but decided to use password auth because of concerns relating to access keys expiring and needing to be refreshed, then auth code flow is probably best.
If asking users to login to the Developer Console to generate a JWT token is daunting because you are concerned that users will be confused or intimidated by the process, then auth code flow is probably best.
Migrating to JWT auth
Transitioning to the JWT auth type
To configure your application to JWT, login to the Developer Console, edit the app's settings, look for the "Auth" section, and select "JWT auth flow." When you click the "Update" button to save your changes, your application will be converted to JWT.
Please bear in mind, as soon as this change is made you will be unable to convert your application back to the password grant type. Therefore, if your application will rely on the password grant type while you develop and test your changes you may wish to register a second app in which to do your development. Then convert your primary application to use JWT only as a final step.
If your deployment strategy however requires your application to support both password and JWT grant types simulaneously, then a RingCentral administrator can help configure your application accordingly. This will employ a custom auth setting for your application and will prevent you from changing your auth method on your own in the future. If you elect to go this route, be sure to contact us when your migration is complete so that we can update your auth method to restore your ability to edit your app going forward. To request help from support to configure your application in this way, please file a help ticket with support.
Transitioning your code to JWT
From a code-level perspective, migrating from password grant to JWT is easily the most straightforward. If you are using a RingCentral SDK, the difference between the two auth methods is trivial. Let's take a look at Javascript to compare (other languages are similarly simple).
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
})
Functionally, they operate in an identical fashion. You provide a set of credentials, and receive back an "access key." The access key is then passed in your HTTP Authorization header to authenticate subsequent API calls.
Transitioning from one set of credentials to another
Perhaps the trickiest part of this transition is in generating or collecting the JWT credentials for each of the username/password combos you have stored in your system. To transition seamlessly from password to JWT we recommend you do the following:
Before you update your application to use JWT, first generate or collect a JWT credential for each of the users who need to log in via your application. Store these JWT credentials alongside the usernames and passwords you have stored. Pro tip: if you find this step daunting due to the number of credentials you need to generate or collect, then that is a strong signal that JWT might not be the best auth method to migrate to. Consult the section above to make sure you are selecting the most optimal auth type.
Make sure you have a JWT credential for every username/password before proceeding.
Update and test your new code in sandbox. Bear in mind that you will need different JWT credentials for sandbox vs. production for every user.
When you are ready to deploy and officially migrate, bring your application down for maintenance.
Deploy your new code to production.
Update your app's settings to use "JWT auth flow" under the "Auth" section of your app.
Perform user acceptance testing.
Take your application out of maintenance mode.
Pro-tip. Since you already possess each user's login credentials, one could log in to the Developer Console and generate a new JWT credential on their behalf. This could save valuable time and help ensure a more seamless transition.
Migrating to authorization code flow
The password and auth code flows are sufficiently different from one another, that migrating from one to the other could be quite challenging to do in a fully automated manner. However, with proper planning, and some patience, it can be done. Consider the following migration strategy:
Contact RingCentral developer support to enable both password grant and the auth code flow for your app.
Implement the auth code flow in your application and deploy it to customers. In your application, prompt users to connect to RingCentral using OAuth. Store the access key you acquire from RingCentral and work to keep it fresh using refresh tokens.
Once a user has successfully connected to RingCentral, migrate that user to utilize the auth code flow from that point forward.
Engage your users via email and other channels to connect their accounts to RingCentral.
Once all users have transitioned successfully to the auth code flow, contact RingCentral developer support to remove the password grant type auth option from your application.
Keeping access keys fresh and maintaining connectivity a user's account
The most challenging part of migrating to the authorization code flow is planning for how the access keys you acquire through the process will be kept fresh, as access keys expire automatically over time. This requires developers to create a simple service that runs on a regular basis to loop over all stored access keys and to refresh them using a refresh token. This process ensures that whenever your product or service needs to call the API there will be a valid access key to use.
In implementing the service described above, developers should be mindful of race conditions that could impact connectivity, as an access token is immediately invalidated when a refresh token is used to refresh it.
Getting help and support
We are committed to helping all developers migrate successfully. If you have questions or need assistance, please reach out to developer support by filing a help ticket, or better yet, ask the RingCentral developer community here.
