A minimal project to implement RingCentral Auth Code Flow in JavaScript

I work at RingCentral and recently I handled a support case about the RingCentral Auth Code flow in JavaScript. A developer was following this official get started guide, but he met some technical issues about setting up Express. But wait, why do we need express at all?

Do we need Express?

While Express is mainly for creating an application server in node.js, Auth Code Flow is mainly about frontend development. In theory Auth Code Flow doesn’t need any dynamic server side code at all. So we don’t actually need Express. But why does the official get started guide use it? Well, it tries to provide you with a comprehensive guide. If in case your project also has a dynamic server side, you may reference its implementation.

And the official get started guide also uses express-session which is for session management for Express. It is not necessary because even Express is not necessary. The official guide also uses ejs which is Embedded JavaScript templates. Do we need templates? Well, maybe, but I am pretty sure we can go without it. I know you may be wondering: you said lots of third party libraries are not necessary at all, then what should a minimal project look like?

A Minimal implementation

After some experiments, I found that the following code could be a minimal implementation:

There are 35 lines in total, including comments and blank lines. It could be simplified further if you want. For example you could remove the console.log lines. You may also remove the API call to /restapi/v1.0/account/~/extension/~/call-logbecause it is not part of the OAuth process. If you do so, you can reduce the code to under 30 lines which makes the project truly “minimal”.

How we set the redirect URI:

const redirectUri = window.location.origin + window.location.pathname;

We set it to the current location of the page. So that we do not need to hard code it. You may also change it a little bit if the redirect to the page is separate. Let’s say it’s the callback.html page index of index.html page, change the code to:

const redirectUri = window.location.origin + window.location.pathname + 'callback.html';

How we get the code query parameter:

const urlSearchParams = new URLSearchParams(new URL(window.location.href).search);
const code = urlSearchParams.get('code');

It’s a pretty standard and reliable way to get query parameters from the current page’s URL.

How we tell if the user is visiting the page directly or being redirected back to the page?

if(code === null) {
  // first time visiting page
} else {
  // redirected back to page
}

Please note that, this code snippet is only necessary if the redirectURI is the current page. For those who have a separate page as redirect to page, it is not needed.

And the idea is pretty simple, if the user is redirected to the page, there must be a query parameter named code.

If the user is visiting the page for the first time:

// login
const loginUrl = platform.loginUrl({
    redirectUri
});
console.log(loginUrl);
const link = document.createElement('a');
link.href = loginUrl;
link.innerText = 'Login';
document.body.appendChild(link);

We show him a link to login.

If the user is redirected to this page:

const resp = await platform.login({code, redirect_uri: redirectUri});
const token = await resp.json();
console.log(token);
const r = await platform.get('/restapi/v1.0/account/~/extension/~/call-log');
console.log(await r.json());

We exchange the code for token and make an API to make sure that the token works.

How to build the code

Because we are using some ES6 syntax the code will not able to run in all browsers unless we build it using some tools. There are several tools which could get the job done but here we will be using webpack.

Above is the webpack.config.js file. I won’t go into further detail about this, because it’s a bit out of the scope of this article.

Source code

The source code of the project we built in this article can be found here.

Conclusion

RingCentral Auth Code Flow doesn’t have to be hard. You do not need to write any server side code. Just around 30 lines of client side code can get the job done.

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!