Use Rules with the Authorization Extension

You can use Auth0 Rules with the Authorization Extension to do things like:

  • Add custom claims to the issued token.

  • Determine the user's group membership, roles, and permissions.

  • Store the user's groups, roles, and permissions info as part of the app_metadata.

  • Add the user's groups, roles, and permissions to the outgoing token (which can be requested via the openid groups permissions roles scope).

Because the above logic is part of a rule, it will only be executed in the context of a login. If users are added to or removed from a group, this change will only be reflected in Auth0 after the user's next login.

To learn more, read Auth0 Rules.

Add custom claims to the issued token

To add custom claims to your tokens, you can do so by creating an additional rule that allows the Authorization Extension to do so. Custom claims can be namespaced or non-namespaced.

To learn more, read Create Custom Claims.

You should limit the number of claims you add to the token.

function (user, context, callback) {
  var namespace = 'http://yourdomain/claims/'; // You can set your own namespace, but do not use an Auth0 domain

  // Add the namespaced tokens. Remove any which is not necessary for your scenario
  context.idToken[namespace + "permissions"] = user.permissions;
  context.idToken[namespace + "groups"] = user.groups;
  context.idToken[namespace + "roles"] = user.roles;
  callback(null, user, context);

Was this helpful?


This rule must run after the Authorization Extension rule. To make sure this happens, make sure that you place it below the Authorization Extension rule.

When calling the /authorize endpoint or configuring Lock, you'll need to specify the information you want in the scope by indicating groups, permissions and/or roles.

Control app access

You can also write rules that are executed after the Authorization Extension rule to do things like control access to your application. One method of doing this is to specify the roles that are required for each application using the application metadata.

For more details, review Manage Metadata with Rules.

Set app metadata required roles

You can set the app's metadata with roles, which are groups of permissions that you group together to create a specific set of functionality. You can think of this step as "tagging" the app so that the rules you set up know which app to act on.

  1. ⁠⁠⁠⁠To set the context.clientMetadata field with required_roles, select the application you want to work at Auth0 Dashboard > Applications > Applications. This brings you to the application's Settings. Scroll down, and select Show Advanced Settings at the bottom of the page.

  2. Under Application Metadata add an item setting the Key to required_roles and in Value field list your roles in comma separated style. Select + Add to add the field.

    Dashboard - Extensions - Authorization Extension - Advanced Settings - Application Metadata

  3. When finished, select Save Changes. Now, when you log in from this application, in context.clientMetadata, you will have the required_roles with the roles value string you entered.

Create rule enforcing app roles

Now that each app has a role associated with it, you can create the rule executes with this piece of app information in context.

  1. Before creating this rule, enable Roles under the Token Contents and publish the Authorization Extension rule.

  2. Add this rule and make sure it is listed after the generated "auth0-authorization-extension" rule.

  3. After setting required_roles, create a new rule with the following body:

    function (user, context, callback) {
      context.clientMetadata = context.clientMetadata || {};
      if (context.clientMetadata.required_roles && context.clientMetadata.required_roles.length){
        if (user.roles) {
          var _ = require('lodash');
          var roles = context.clientMetadata.required_roles.split(',');
          var matchingRoles =_.filter(user.roles, function(roleName) {
            return _.includes(roles, roleName);
          if (matchingRoles && matchingRoles.length) {
            return callback(null, user, context);
        return callback(new UnauthorizedError('You do not have the required role to access ' + context.clientName));
     callback(null, user, context);

    Was this helpful?


Learn more