End of Life announcement for Password Flow/ Grant Type

In compliance with the industry standards of the OAuth Working Group; Password Flow and password grant type support will be discontinued on March 31, 2024. Instead of utilizing the Password Flow, developers are encouraged to update their apps to utilize JSON Web Tokens (JWT).

Using JWT

The quickest and easiest way to update your app is to replace Password flow with a more secure authorization process called JSON Web Tokens (JWT). With JWT you use a secure user generated token that is limited to the apps specified and can be deleted or regenerated on demand. This prevents malicious actors from obtaining user credentials, using the login information to access to the account, and helps limit a user’s exposure should a token be compromised. These tokens are also much longer and therefore more difficult to exploit by brute force or guessing attempts.

Here is an example what a RingCentral JWT looks like, note its length and structure:

eyJraWQiOiI4NzYyZjU5OGQwNTk0NGRiODZiZjVjYTk3ODA0NzYwOCIsInR5cCI6IkpXVCIsImFsZyI6IlJTMjU2In0.eyJhdWQiOiJodHRwczovL3BsYXRmb3JtLmRldnRlc3QucmluZ2NlbnRyYWwuY29tL3Jlc3RhcGkvb2F1dGgvdG9rZW4iLCJzdWIiOiIyMzgxMTIwMDQiLCJpc3MiOiJodHRwczovL3BsYXRmb3JtLmRldnRlc3QucmluZ2NlbnRyYWwuY29tIiwiZXhwIjoxNjg5ODk3NTk5LCJpYXQiOjE2ODkyNjg5MzYsImp0aSI6IkZSazNyRlFFUnNhZElvNjdPeWRzRWcifQ.dkgOlXbX8JN8Zh4Srlyw6NMQgns4ydlLIJbn5PWdCZk2iEWO1cSoszWwvTU6ZAQyl-Z_hQjOC8pySRqG44BIKMqOdif-UCzSJMqTwusQ4x9aCSySZ6foIZDgSJFK61Vo4iG5uLcSp4bQc6SKuQ4M2xS-_X8OqdaUx74u8gRPGHXSCSplXuMaC-MX1hubzP6lLWc9SRmU9OKShmCLOIl6SJs8yTnIzrotILA0cbrzEfWUKfW-dUSNzppHbt2yPBYn-FDJmnN4tF — 36g5OEfGguli1PSU6eIApaF-eYnaoxilNhaU2UuOCgN9iNJT7qMV843aXPO1ARTIAK1EFFwIlQ

Learn how to generate your JSON Web Token (JWT) here.

Updating your code

The change to your code should be relatively easy to implement. First make sure you have installed the latest version of the RingCentral SDK for your programming language.

In the following example, we will update a PHP code block from Password Flow to JWT. This will be similar when writing code within RingCentral’s other supported SDKs.

In the following code block we first instantiate the RingCentral SDK using our app’s client ID, client secret, and environment (sandbox or production servers). Then we log the user in by providing their username, extension, and password. As you can see, this means the user’s credentials have to be stored and rendered in plain text, potentially compromising the user if your application’s code is breached:

$sdk = new RingCentral\SDK\SDK($client_id, $client_secret, $server);
$sdk->platform()->login($username, $extension, $password);

To move from Password Flow to JWT, we will use the same structure, but instead of providing the username, extension, and password we will provide an array with a key of “jwt” and a value that is the user’s token.

$sdk = new RingCentral\SDK\SDK($client_id, $client_secret, $server);
$sdk->platform()->login( [ “jwt” => $token ] );

Learn more about utilizing JWT here.

Using OAuth

The alternate approach to authenticating to the API is through the OAuth or Authorization Code Flow method. This is also sometimes called a “3-legged authorization flow”. In this method there are three steps taken before an access token is granted to the application. The steps are:

1. An authorization is requested (and granted) by way of a user interface
2. The granted permission is exchanged for an access token through an API call
3. The access token is then used to call the API to perform the desired task

The first step is typically called from a third-party app that you want to use the RingCentral API within and it needs access to the API platform. Therefore it calls the login screen and shows it in a pop-up window. It can look like this image after the credentials are supplied:

Figure 1 — User guided authorization process

When the access is confirmed with this login authorization an access token is returned to the calling application within the URL, step # 2 above.

Then using that access token you can start using the API in a similar way to that of the JWT approach above. Again, here is a PHP code example.

The SDK is invoked in the same way that a JWT key is started, as in the following PHP code example:

$sdk = new RingCentral\SDK\SDK($client_id, $client_secret, $server);
$platform = $sdk->platform();

After this however, the code changes a little, when you need to get the redirect URL and use that to login to the platform. The last part of step 2 then is to store the returned access token into a session for later use.

$qs = $platform->parseAuthRedirectUrl( $_SERVER[‘QUERY_STRING’] );
$qs[“redirectUri”] = $_ENV[‘RC_REDIRECT_URL’];
$platform->login($qs);
$_SESSION[‘sessionAccessToken’] = $platform->auth()->data();

With the access token “in hand” then you can send it to the API and call your process endpoints after that (sending an SMS message, processing a call log, etc.)

if (isset($_SESSION[‘sessionAccessToken’])) {
 $platform->auth()->setData((array)$_SESSION[‘sessionAccessToken’]);
}

Learn more about using OAuth here.

Choosing a path

As you can see there are two paths to moving away from the Password Flow process. The flow you choose should depend on whether or not your application provides an interface to your users. If users will be utilizing a user interface with your application, it is recommended to have them utilize the OAuth flow where they will log in on RingCentral’s system and you will be provided an access token.

However, if you are creating a server based application that typically does not utilize a user-interface, for example a cron job, a chatbot, or a notifications/ alert system it is recommended to utilize a JWT token. In this event the user will be able to provide you a JWT string to use for authentication instead of being required to log in to RingCentral through your application.

Regardless, RingCentral user credentials no longer need to be shared with application developers, and with these new processes they are never stored or accessed by third party applications — preventing potential compromise by malicious users.