Sample Use Cases: Rules with Authorization

Learn how to use rules with roles-based access control (RBAC). For use with our Authorization Core feature set.

The End of Life (EOL) date of Rules and Hooks will be November 18, 2026, and they are no longer available to new tenants created as of October 16, 2023. Existing tenants with active Hooks will retain Hooks product access through end of life.

We highly recommend that you use Actions to extend Auth0. With Actions, you have access to rich type information, inline documentation, and public npm packages, and can connect external integrations that enhance your overall extensibility experience. To learn more about what Actions offer, read Understand How Auth0 Actions Work.

To help with your migration, we offer guides that will help you migrate from Rules to Actions and migrate from Hooks to Actions. We also have a dedicated Move to Actions page that highlights feature comparisons, an Actions demo, and other resources to help you on your migration journey.

To read more about the Rules and Hooks deprecation, read our blog post: Preparing for Rules and Hooks End of Life.

With rules, you can modify or complement the outcome of the decision made by the pre-configured authorization policy to handle more complicated cases than is possible with role-based access control (RBAC) alone. Based on the order in which they run, rules can change the outcome of the authorization decision prior to the permissions being added to the Access Token. They can also allow you to customize the content of your tokens.

Allow access only on weekdays for a specific application

Let’s say you have an application that you want to make sure is only accessible during weekdays. To do this, you would create the following rule:

function (user, context, callback) {

  if (context.clientName === 'APP_NAME') {
    const d = Date.getDay();

    if (d === 0 || d === 6) {
      return callback(new UnauthorizedError('This app is only available during the week.'));
    }
  }

  callback(null, user, context);
}

If a user attempts to access the application during the weekend, access will be denied, even if they authenticate and have the appropriate privileges.

Allow access only to users who are inside the corporate network

Let’s say you want to allow access to an application, but only for users who are accessing the application from inside your corporate network. To do this, you would create the following rule:

function (user, context, callback) {
  const ipaddr = require('ipaddr.js@1.9.0');
  const corp_network = "192.168.1.134/26";
  const current_ip = ipaddr.parse(context.request.ip);

  if (!current_ip.match(ipaddr.parseCIDR(corp_network))) {
    return callback(new UnauthorizedError('This app is only available from inside the corporate network.'));
  };

  callback(null, user, context);
}

If the user is outside the corporate network, they will be denied access even if they successfully authenticate and have the appropriate privileges.

Deny access to anyone calling an API

Let’s say you want to deny access to all users who are calling an API. This means that you need to deny access depending on the audience value for your API, which you can find in the API Audience field of your API in Dashboard > Applications > APIs. To do this, you would create the following rule:

function (user, context, callback) {
  /*
   *  Denies access to user-based flows based on audience
   */
  var audience = '';
  audience = audience
              || (context.request && context.request.query && context.request.query.audience)
              || (context.request && context.request.body && context.request.body.audience);
  if (audience === 'http://todoapi2.api' || !audience) {
    return callback(new UnauthorizedError('end_users_not_allowed'));
  }
  return callback(null, user, context);
}

In this case, the audience value for the API is http:://todoapi2.api, so this is the audience we will refuse. If anyone tries to access the API with this audience value, they will be denied access and receive an HTTP 401 response.

Add user roles to tokens

If you enable RBAC for APIs along with “Add Permissions in the Access Token” (or enable RBAC via the Management API and set the Token Dialect to access_token_authz), you will receive user permissions in your Access Tokens. To add user roles to tokens, you would use the context.authorization object when you create the following rule:

function (user, context, callback) {
  const namespace = 'http://demozero.net';
  const assignedRoles = (context.authorization || {}).roles;

  let idTokenClaims = context.idToken || {};
  let accessTokenClaims = context.accessToken || {};

  idTokenClaims[`${namespace}/roles`] = assignedRoles;
  accessTokenClaims[`${namespace}/roles`] = assignedRoles;

  context.idToken = idTokenClaims;
  context.accessToken = accessTokenClaims;

  callback(null, user, context);
}

Manage Delegated Administration Extension roles using the Authorization Core feature set

Although the Delegated Administration Extension (DAE) and the Authorization Core feature set are completely separate features, you can use the Authorization Core feature set to create and manage roles for the DAE if you use a rule.

1. Create DAE roles using the Authorization Core feature set. The names of the roles you create must match the names of the pre-defined DAE roles.
2. Assign the DAE roles you created to the appropriate users using the Authorization core feature set.
3. Add user roles to the DAE namespace in the ID Token. To do so, create the following rule, remembering to replace the CLIENT_ID placeholder value with your application’s Client ID:

function (user, context, callback) {
    if (context.clientID === 'CLIENT_ID') {
        const namespace = 'https://example.com/auth0-delegated-admin';
        context.idToken[namespace] = {
            roles: (context.authorization || {}).roles
        };
    }
    callback(null, user, context);
}

Auth0 returns profile information in a structured claim format as defined by the OpenID Connect (OIDC) specification. This means that custom claims added to ID tokens or access tokens must conform to guidelines and restrictions to avoid possible collisions.