JavaScript Authorization

Sample Project

Download a sample project specific to this tutorial configured with your Auth0 API Keys.

The previous step covers how to protect the resources served by your API such that only users who have authenticated in your application (and who are properly authorized) can access them. While this deals with protecting data resources from your server, it is likely that you will also need some way to control authorization in your client-side single page application.

Access Control in Single Page Apps

Distinguishing between different users and controlling what they can and cannot access is typically known as access control. The way that access control is implemented depends on the needs of your application, but with Auth0 the most common approach is to use the scopes granted to a user as a way to make decisions about what they can see in the application and which routes they have access to.

For single page applications which get their data from APIs, there are two major things that need to be considered when authorization and access control are introduced:

  1. The particular data being requested from the API should only be released if the user making the request is authorized to access it
  2. The user should only be able to access client-side routes and see certain UI elements if they have an appropriate access level to do so

The previous step used a scope of read:messages for access to API resources. Since this scope indicates that the user has read-only access to data, it might be considered that the user has some kind of "regular user" access level. If you wanted some users to have write access to the same resource, and therefore some kind of "administrator" access level, you might consider introducing a scope of write:messages.

Auth0 makes no assumptions about how the scopes for your API map to various access levels, nor is there any restriction on what you call your scopes and access levels. These details are at your discretion.

Determining a User's Scopes

When login transactions are initiated, you can specify which scopes you would like to request. Typically this is done when auth0.WebAuth is instantiated, but it can also be done in an options object passed to the authorize method.

If a requested scope is available for the user, the access_token that gets signed and sent back for them will have a scope claim in the payload. The value of this claim will be a string with any scopes that were granted.

Determining UI behavior in the client-side application can be done by using the scopes that were granted for a user, but there's a catch: the access_token must be treated as opaque in client-side applications and thus must not be decoded there. This means that you cannot decode and read the payload of the access_token itself to find out which scopes were granted for the user.

The solution is to use the value of the scope param that comes back after authentication. This will be a string value containing all of the scopes that were granted for the user, separated by spaces. However, this param will only be populated if the scopes that are granted for the user differ in any way from what was originally requested.

The resulting workflow for determining which scopes a user has is as such:

  1. Check for a value on authResult.scope. If one exists, use that value because these are the scopes that were granted for the user.
  2. If there is no value for authResult.scope, it means that all of the scopes requested for the user were granted. In this scenario, the scopes that were requested when the authentication transaction was initiated can be used directly to make UI decisions.

Handle Scopes

Adjust your app.js file to use a local variable with any scopes you would like to request when users log in. Use this in the auth0.WebAuth instance.

// app.js

var requestedScopes = 'openid profile read:messages write:messages';

var auth0 = new auth0.WebAuth({
  // ...
  scope: requestedScopes

In the setSession method, save the scopes granted for the user into local storage. The first place to check for these granted scope values is the scope key from the authResult. If something exists there it's because the scopes which were granted for the user differ from those that were requested. If there is nothing on authResult.scope, it means that the granted scopes match those that were requested, so the requested values can be used directly. If there are no values for either of these, you can fall back to an empty string.

// app.js

function setSession(authResult) {
  const scopes = authResult.scope || requestedScopes || '';

  // ...
  localStorage.setItem('scopes', JSON.stringify(scopes));

Add a function called userHasScopes which will check for a particular scope in local storage. This function should take an array of strings and check whether the array of scopes saved in local storage contains those values. The function can be used to conditionally hide and show various UI elements and to limit route access.

// app.js

function userHasScopes(scopes) {
  var savedScopes = JSON.parse(localStorage.getItem('scopes'));
  if (!savedScopes) return false;
  var grantedScopes = savedScopes.split(' ');
  for (var i = 0; i < scopes.length; i++) {
    if (grantedScopes.indexOf(scopes[i]) < 0) {
      return false;
  return true;

Conditionally Dislay UI Elements

The userHasScopes function can now be used alongside isAuthenticated to conditionally show and hide certain UI elements based on those two conditions.

// app.js

// ...
function displayButtons() {
  // ...
  if (!isAuthenticated || !userHasScopes(['write:messages'])) { = 'none';
  } else { = 'inline-block';

Protect Client-Side Routes

Limiting access to client-side routes can be done by checking which scopes the user has. This can be done with the userHasScopes function created in the previous step.

The way that the userHasScopes function gets applied to protect various client-side routes depends on the routing library being used. The examples presented here don't assume any particular router.

Some routing libraries provide hooks which will run a function before the route is activated. This kind of hook might be called something like beforeEnter or onEnter. This is a good place to run the userHasScopes function to check whether the user has the scopes required to enter the route.

Conditionally Assign Scopes to Users

The default behavior when registering scopes in you API settings is that all of those scopes become immediately available and can be requested by any user. To properly handle access control, you will need to create policies which stipulate the conditions under which users can be granted certain scopes. This can be done with Rules. See the documentation for how to use Rules to create scope policies.

Considerations for Client-Side Access Control

In the context of access control on the client-side, it's important to note that any scope values that end up in local storage are simply a clue that the user has that particular set of scopes. There is nothing stopping a user from manually adjusting the scopes in local storage in an attempt to give themselves a higher level of access. Doing so, a user could force their way to a client-side route that they shouldn't have access to.

So how are you supposed to create a secure application if client-side routes are so easily hackable? The answer is to remember that browsers are public clients and that they must be treated as such. Any and all sensitive data which powers your application needs to be kept on your server instead of being included directly in your client-side SPA because your server is the only place that can act as a secure gatekeeper for that data.

If a user wants to get access to the data on your server, they will require a valid access_token to do so. Any attempt to modify an access_token will invalidate it. This means that if a user tried to edit the payload of their access_token to include different scopes, the token would lose its integrity and would be rendered useless.

It would be easy for a user to modify the scopes array in local storage and thus be able to navigate to a client-side route that they shouldn't be at, but it wouldn't do them much good. If the data required for a given route is retrieved from your server (as it should be), the only thing the user would see on the page is an empty shell.

Previous Tutorial
3. Calling an API
Next Tutorial
5. Token Renewal
Use Auth0 for FREECreate free Account