| description |
|---|
This page explains how to setup and manage the Authorization Extension v2. |
::: panel-warning Notice This page explains how to use version 2 and later of the Authorization Extension, click here for documentation of version 1.
Click here for information about upgrading your Authorization Extension version :::
The Auth0 Authorization Extension provides user authorization support in Auth0. Currently the extension supports authorizations for Users using Groups, Roles and Permissions.
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.
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.
::: panel-warning Notice One of the major changes of the v2 of the Authorization Extension is that the Applications section has been removed. The driving factor for this change is complexity: Defining a policy when someone can or cannot access an application depends on different factors (roles, groups, time of day, MFA, ...). This is why the desired approach for this use case is rules. :::
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.
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:
Storing Additional Data in Tokens:
If you want to store data on Groups, Roles, or Permissions of a user in the token, use the toggle buttons to add the desired data pieces.
::: panel-warning Notice Storing too much data in the token can cause performance issues or even prevent the token to be issued. Make sure you only choose to store the data that you'll really need. If this data can grow too large, consider using persistence instead of adding it to the token. :::
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.
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 /tokeninfo endpoint to retrieve this information after the user has logged in.
Once you have the extension configured you can start to configure Groups, Roles and Permissions for your Users in the Authorization Extension dashboard.
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.
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
- Accounting
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:
- Open up the top-level Group (in the example above, this would be the Example Company Group);
- Click on the Nested Groups tab;
- Click on the ADD NESTED GROUP button. Then 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 allow you to dynamically "add" users to different Groups based on the users' Connections.
For example, suppose your company has the following Groups of users:
- Americas - West, which consists of users who connect via google-oauth2;
- Europe - West, which consists of users who connect via google-oauth2.
With Group Mappings, you can consolidate these Groups and the permissions allotted to the included users into one larger group, such as Overall Company Group. Similar to nested Groups, the memberships of the users in Overall Company Group is not explicit, but dynamic, and are calculated at runtime. Such memberships will appear listed as such under the Groups page.
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 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
- Permissions:
-
Role: Expense Admin
- Permissions:
- Approve expenses
- View all user expenses
- Delete expenses
- Add a new expense
- Permissions:
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 ddescription and select the application for which this permission applies.
Once you have your permissions created, you can associate them with Roles.
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.
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:
- Determine the user's group membership, roles and permissions using information provided by the Extension;
- Optionally store the user's groups, roles and permissions info as part of the
app_metadata, to enable this see details below; - Add the user's groups, roles and permissions to the outgoing token (which can be requested via the OpenID Groups scope) see details below;
Note: Since this 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 will only be reflected within Auth0 after this user logs in again (eg: in the user's
app_metadataor when calling the/userinfoendpoint).
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.
- For example, you can have required_roles:
Timesheet User,Timesheet Admin
Then 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);
}Note: For this to work you must enable "Roles" under the "Token Contents" section and publish the rule. Then add this rule after the generated "auth0-authorization-extension" rule.
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.
The extension uses the internal Webtask storage capabilities, which are 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.
Think you need more? Contact support.
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.
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.