Auth0 Authorization Extension v2

The Auth0 Authorization Extension provides user authorization support in Auth0. Currently the extension supports authorizations for Users using Groups, Roles and Permissions.

How to Install

First make sure you have a Client created that can support the Authorization extension. Supported client types for the Authorization extension are: Native, Single Page Web Applications and Regular Web Applications. Clients with no type assigned or non-interactive clients are not supported.

To install the Authorization extension, click on the "Auth0 Authorization" box on the main Extensions page of the Management Portal. You will be prompted to install the app. You will also need to choose where to store the data which is documented under Storage Types.

Once installed, you will see the app listed under Installed Extensions.

When you click on the link to open the extension for the first time, you will be prompted to provide permission for the extension to access your Auth0 account. Then you will be redirected to the Authorization Dashboard.

Migration from v1 to v2 (breaking changes)

Upgrade the Extension Version

To upgrade your existing version of the Authorization Extension, go to Extensions section of the dashboard, then click Installed Extensions.

Next to the Authorization Extension, you should see a link to upgrade to the latest version.

Configure the Extension

The extension needs to be configured before it can enforce your authorization logic.

Click Configuration on the dropdown on the top right of the Authorization Dashboard.

This will bring you to the Rule Configuration section of the Configuration page.

Here you can configure:

Token Contents

Storing Additional Data in Tokens

If you want to store the data for the Groups, Roles, or Permissions of a user in the token, use the toggle buttons to add the desired data pieces.

Please note however that if your are using OIDC Conformant Authentication, the custom attributes added to the token by the Authorization Extension will not be added to the id_token due to the fact that custom claims need to be namespaced.

If you therefore choose to enable this option, you will also need to manually add an extra Rule which will add namespaced claims for these attributes. An example of such a Rule can be seen below:

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

It is important that this Rule must run after the Authorization Extension Rule, so be sure to place it below the Authorization Extension Rule.

Passthroughs

If you have users that receive groups from the Identity Provider (such as Active Directory) then you can merge these groups (in order to preserve them) with the groups defined in your Authorization Extension. Use the toggle buttons to choose which to merge of Groups, Roles and Permissions.

Persistence

You can also store the authorization context information in the user profile. The data will be stored in the user's app_metadata and you can then use the Management API or the /userinfo endpoint to retrieve this information after the user has logged in.

Setup the Authorization Extension

Once you have the extension configured you can start to configure Groups, Roles and Permissions for your Users in the Authorization Extension dashboard.

Users

The Users section lists all the current users of your applications. Here you can search your users and select a specific user. You can then view their profile, edit or view their groups, and edit or view their roles.

Groups

To create and manage the Groups with which you will use to manage users' settings, click on the "Groups" link in the Authorization Dashboard.

When creating a Group, you will provide a name for the group, as well as a description of what that Group does.

There are two ways for you to manage users and their Group memberships:

• Opening the group and managing the group's users;

  

• Opening the user and managing the user's group membership.

  

The Groups that you will create are dependent on the needs of your business process. For example, you might have a Group for your users in Finance, a group for your users in IT, and so on. Additionally, you may create nested groups, similar to the following:

• Example Company
  • Accounting
    • External Accountants
  • Human Resources
  • Finance
    • Finance IT Support
  • Management

To create nested Groups, you must first create all of the individual groups via the CREATE button on the Groups page of the Authorization Dashboard.

To nest the groups:

1. Open up the top-level Group (in the example above, this would be the Example Company Group)
2. Click on the Nested Groups tab
3. Click on the ADD NESTED GROUP button. You will be presented with a list of Groups that can be added to the primary Group. To select a particular Group, click on the check box to the left of the name. After each selection, you will be returned to the primary Group page. Continue this process until you have included all the Groups you need.

With nested Groups, adding a user to a sub-Group also grants the user permissions granted to the Groups that are parents of that Group. For example, adding a user to the External Accountants group automatically makes them a member of the Finance and Company Groups. Please note, however, that the user is only explicitly a member of External Accountants; all other memberships are purely dynamic and are calculated as needed (for example, when loading the user's group memberships).

To prevent confusion, you will be shown both the explicit members AND the "calculated members" that result from nested groups whenever you open a specific Groups page in the Authorization Dashboard.

Group Mappings

Group Mappings allow you to dynamically "add" users to different Groups based on the users' Connections. Essentially, using the Connection and the Groups information provided by the IdP, you can dynamically make the user a member of the group in which you've created the appropriate mapping.

For example, suppose your users are logging in using their Active Directory (AD) credentials. As part of their identity, AD allows users to have group information associated (such as "Administrative" and "Marketing").

You can then configure Group Mappings to look at a user's profile if they're connecting with the Active Directory connection. When the extension sees that the person is a part of the "Administrative" group, it will automatically make the user a member of your company's Admin group.

Roles

The Roles that you will create will depend on the access to certain permissions in your application. For example, let's say that you have an application that allows employees to enter in company expenses. You want all employees to be able to submit expenses, but want certain Finance users to have more admin type of actions such as being able to approve or delete expenses. These actions can be mapped to Permissions and then assigned to a certain Role.

You can create different types of Roles such as: Expense Admins, Expense Manager, and Expense User for your Expense Management Tool.

To add a role, click the CREATE ROLE button from the Roles section of the dashboard. Then choose the application this Role applies to (such as Expense Management Tool) and then add a name of the role (such as Expense Admins) and a description of the role. Then select the permissions you wish to grant to this role. If you haven't yet created your permissions you can add them later to an exisiting Role.

Once you have a Role created, you can add it to a user so they can then have the associated Permissions. To add a role to a user, find the user in the Users section, then click the Roles tab. Then click ADD ROLE TO USER to choose which roles you wish to assign to a user, then click SAVE.

Permissions

Permissions are the actions or functions that can be added to Roles.

Using the previous example of an Expense application, let's look at possible roles and how they can be associated with certain permissions:

• Role: Expense User

  • Permissions:
    • View their own expenses
    • Add a new expense

• Role: Expense Admin

  • Permissions:
    • Approve expenses
    • View all user expenses
    • Delete expenses
    • Add a new expense

To create a new permission, go to the Permissions section of the Authorization Extension dashboard.

Then click the CREATE PERMISSION button. Then enter the name of the permission, the description and select the application for which this permission applies.

Once you have your permissions created, you can associate them with Roles.

Enable API Access

At this point the extension might contain some roles, groups, permissions. Your users might also have been assigned to specific roles and groups.

The Authorization Dashboard can optionally enable API access which will allow you to automate provisioning and query the authorization context of your users in real time.

To get to API section, click API on the dropdown on the top right of the Authorization Dashboard.

Under Settings you can use the toggle to enable API Access.

You can also set the Token Expiration, Token Issuer, Token Audience and Url. Click the SAVE button when finished editing these field.

Click the Explorer section to see the API endpoints that can be called.

Rule Behavior for the Authorization Extension

In addition to API access, you can also deploy a rule that reaches out to the extension each time a user logs in. Once the rule is enabled, it will do the following:

1. Determine the user's group membership, roles and permissions using information provided by the Extension;
2. Optionally store the user's groups, roles and permissions info as part of the app_metadata, to enable this see details below;
3. Add the user's groups, roles and permissions to the outgoing token (which can be requested via the openid groups permissions roles scope), see Token Contents above;

Control Application Access

In addition, you can write your own rules that are applied after the rule that is published by the extension. For example you can write a rule to control application access. One way to achieve this is to use the Application Metadata where you can specify on every client that roles are required.

How to set required_roles

⁠⁠⁠⁠1. To set the context.clientMetadata field with required_roles, first select your client in the dashboard. This will bring you to the client's Settings, scroll down and click on the Show Advanced Settings link 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. Click the CREATE button to add the field.

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

Create a Rule that enforces client roles

After setting required_roles you can write a rule that enforces this logic:

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

Import/Export Authorization Data

You can import new data or export exisiting authorization data with a JSON file. This can be useful when moving over an environment, but remember roles and permissions are linked to specific clients, so you will need to update to the correct applicationId when moving environments.

You can get to the Import/Export section by clicking Configuration on the dropdown on the top right of the Authorization Dashboard.

And then clicking Import/Export.

Use this form to copy and/or paste, or edit JSON data and then click either the IMPORT or EXPORT button when finished, depending on your use case.

Storage Types

Webtask Storage

The extension will use Webtask Storage by default, which is limited to 500 KB. Here are some examples of what this means in terms of scenarios:

• If you have 1000 groups and 3000 users, where each user is member of 3 groups about 475 KB of data would be used.
• If you have 20 groups and 7000 users, where each user is member of 3 groups about 480 KB of data would be used.

Amazon S3

The extension also allows you to config Amazon S3 as a storage provider. In order to use Amazon S3 you will need to:

1. Create an S3 bucket
2. Create an IAM user and get the Key ID and Key for that user
3. Create a policy for the IAM user which allows the user to make changes to the bucket

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:DeleteObject",
                "s3:GetObject",
                "s3:ListBucket",
                "s3:PutObject"
            ],
            "Resource": [
                "arn:aws:s3:::NAME-OF-YOUR-BUCKET/*"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket"
            ],
            "Resource": [
                "arn:aws:s3:::NAME-OF-YOUR-BUCKET"
            ],
            "Condition": {}
        }
    ]
}

Troubleshooting

An authentication results in a token that contains Groups but not Roles or Permissions

If this happens, chances are you created roles and permissions for one application (client) but are authenticating with another. For example, you created all your roles/permissions against Website A but create another website client in Auth0 (Website B) and use its client_id and client_secret in your application. This can also occur if you click the Try button in the Auth0 Dashboard on a Connection that contains one of your users. This will execute an authentication flow using the Auth0 global application, which is not the same as the application you configured in the extension.

My application/client is not shown in the dropdown when setting up the extension

The supported client types for the Authorization extension are: Native, Single Page Web Applications and Regular Web Applications. Clients with no type assigned or non-interactive clients are not supported.