Restrict Application or User Requests for API Scopes

By default, any user associated with an Auth0 application can request any custom API scopes that have been created. Sometimes you may not want to allow an application to request certain scopes, though. For example, you may want to restrict access to an API's scopes based on the calling application or a user's role or location. To do so, we use rules.

Example: Deny access to anyone calling the API

In this example, we want to deny access to all users who are calling the API. To do this, we create a rule to deny access depending on the audience parameter. In this case, the audience value for our API is http:://todoapi2.api, so this is the audience we will refuse.

The value of an API's audience is displayed in the API Audience field in the APIs section of the Auth0 Dashboard.

When a restricted user attempts to access the API, they will receive an HTTP 401 response.

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);
}

Example: Deny access to users from a specific calling application

In this example, we want to deny access to all users who are accessing the API from a specific calling application. To do this, we create a rule to deny access depending on the client_id parameter. This is equivalent to disabling all connections for an application.

The value of an application's client_id is displayed in the Client ID field in the Applications section of the Auth0 Dashboard.

When a restricted user attempts to access the API, they will receive an HTTP 401 response.

function (user, context, callback) {

  /*
   *  Denies access to user-based flows based on client ID
   */

  var client_id = '';
  client_id = context.clientID;

  if (client_id === 'CLIENT_ID') {
    return callback(new UnauthorizedError('end_users_not_allowed'));
  }

  return callback(null, user, context);
}

Example: Deny access to users based on a role

To limit a user's scopes, you can assign them a role so that requests on their behalf are limited to just the scopes assigned to that role. To do this, you can use the Authorization Extension and a custom Rule.

We discuss this approach in more depth in our SPA+API Architecture Scenario. Specifically, you can review the Configure the Authorization Extension section to learn how to configure the Authorization Extension and create a custom Rule that will ensure scopes are granted based on a user's role.