Adding roles and permissions to a JWT access token in Auth0

Click here to jump to the TL;DR

User management and authentication is a complex, yet ubiquitous requirement of web applications. On smaller projects or MVPs we often advise our clients not to roll their own unless absolutely necessary. The development costs and potential for introducing vulnerabilities into your application if you get it wrong make it almost always the right decision to let someone else handle it.

There are a bunch of excellent products available (Stormpath — now part of Okta, Daily Cred and AWS Cognito to name a few) but the one we’re most familiar with is Auth0. A fantastic suite of tooling, a generous free tier but their documentation and community support is often lacking (hence this post).

Groups, Roles and Permissions in Auth0

Auth0 provide an Authorization Extension for creating and managing Groups, Roles and Permissions. This is fairly well-trodden ground, but at its simplest: Roles are assigned permissions, Users (and Groups) are assigned Roles and Users are assigned to Groups. E.g. You might assign an Admin role to individual users, but it may be better to instead create an Admins group and then assign users to that (to avoid having to add and remove Roles to individual users).

We’re going to assume you’ve gone through the basics of Auth0, have setup and configured a Client, and have installed the Authorization Extension. (Note: The Authorization Extension is not available on the free tier, but we’ll follow up later with a way of assigning roles to users without using the extension).

Once you’ve set up your Groups, Roles and Permissions, you’ll need to configure the Authorization Extension to attach the additional information it provides to your users metadata. To do this, you’ll need to find the well hidden configuration menu by going to Extensions > Installed Extensions > Auth0 Authorization, then in the top right select Configuration from the dropdown:

We didn’t realise opening extensions takes you out of your application, so finding this wasn’t immediately obvious.

From there you’ll need to switch on the following options, then select Publish Rule. This will decorate your user with Groups, Roles and Permissions you assign them:

Note that Token Contents is hugely misleading. Switching these options on does not in fact add this information to the access or ID tokens, but does include it in the user data that we’ll be reading from later in our Rule.

Rules

Extending Auth0 with your own custom behaviour is achieved with Rules. Rules are a series of Javascript functions that allow you to intercept an authorization response and apply some additional logic or decorate it before returning it to the requester (i.e. your app). You can think of them as similar to middleware in Express.

After selecting Publish Rule from the previous step, you should have a new rule to play with under Rules called auth0-authorization-extension. This rule will decorate your user objects with the additional Groups, Roles and Permissions.

You now have two options to add the Groups, Roles and Permissions to your users. You can either edit the rule created by the Authorization Extension or, create a new rule to execute after the Authorization Extension’s rule. We like following the single responsibility principle and will opt for a new Rule.

Create a new Rule using the Empty Rule template and you should see something like this:

Empty Rule template

Note: We don’t recommend storing (or editing) the source code for your rules within Auth0. The code isn’t versioned or backed up, so if you make a mistake you’re stuck. We suggest using one of the Deployment extensions such as Github Deploy to populate your Rules code from source control.

Inside this function you’ll simply need to append the Groups, Roles and Permissions values from the user object, to a namespaced key within the idToken property of the context:

Appending the groups, roles and permissions.

Note: The key you use to append the data to theaccessToken must be a URL but can be whatever you want it to be. We went with https://tojs.io/user_authorization but it could also just be http://example.com/test.

Once you’re done, hit Save and login with a user to whom you’ve assigned a Group, Role and Permission. Decode the JWT and you should see something like this:

Example of decoded JWT

TL;DR

After you’ve added the Authorization Extension and generated their auto-created rule, create your own custom rule and add this code to it.

Final note

The Authorization Extension isn’t available as part of Auth0 free tier, but it is still possible to add these classifications to your users without the extension provided you don’t mind manually adding this information to your users (handy if you don’t have many users or you’re on a tight budget). We’ll follow up soon with a post on how to do that.

If you’re looking for help making better hiring decisions, check out my latest project Evidenced, a platform that gives your teams the tools to deliver consistent, fair and measurable interviews, driven by data.