User defined permissions

​

Overview

Define roles with 1 or more permissions. Each permission can grant or deny read and write operations on specific resources (e.g. API endpoints). One or more roles can be assigned to 1 or multiple users.

​

Why is this important?

Control which user can perform specific actions at a granular level.

---

​

Features

• Define roles.
• Define permissions.
• Add permissions to 1 or more roles.
• Add roles to 1 or more users.

---

​

How to use

​

Turn on and require user permissions

Set the environment variable named REQUIRE_USER_PERMISSIONS to the value 1.

You may need to restart your Mage application for the environment variable to be updated and for the application to enable user permissions.

​

Create roles

1. Go the the Mage project settings and click on the navigation row labeled Roles.

2. On the roles list page, there is a button labeled Create default roles and permissions. If you click this button, 6 roles and a few hundred permissions will be created.

   The roles are:

   • Admin default permissions
   • Editor default permissions
   • Editor with notebook edit access
   • Editor with pipeline edit access
   • Owner default permissions
   • Viewer default permissions

   Each role will have a set of permissions that match the Mage API policies that are normally used to authenticate operations when the user authentication feature is turned on but the user permissions feature is turned off.

3. Alternatively, click the button Add new role to create a single new role.

4. Enter in a unique name for the role.

5. Click the button Create new role to save the role.

6. Once you create the role, you’ll be taken to the role detail page.

7. From here, you can add existing permissions to the role.

8. From here, you can add existing users to the role. This will grant permissions or deny operations for user.

​

Create permissions

1. Go the the Mage project settings and click on the navigation row labeled Permissions.

2. Click the button Add new permission to create a new permission.

3. Select an entity that these permissions will be applied to. An entity refers to a defined API endpoint that currently exists in the Mage application.

   For example, the entity Pipeline applies to the API endpoints /pipelines.

4. Optionally enter an entity UUID that these permissions are applied to. For example, you can grant or deny permissions to a specific pipeline by selecting the entity Pipeline and entering the entity UUID example_pipeline. This permission will only be applied to the pipeline with the UUID example_pipeline.

5. Under the section labeled Access, toggle 1 or more accesses to grant. For more information on what each access grants or denies, read the permissions documentation.

6. Click the button Create new permission to save the permission.

7. Once you create the role, you’ll be taken to the role detail page.

8. From here, you can edit the permission.

9. From here, you can add this permission to existing roles.

​

Assign roles to users

1. Go the the Mage project settings and click on the navigation row labeled Users.
2. Click on a row for an existing user.
3. From here, you can assign existing roles to the user.
4. Alternatively, you can add a user to a role by following these steps:
   1. Go to the roles list page.
   2. Click on a row for an existing role.
   3. Click the button labeled +Add user.
   4. Select 1 or more users to assign this role to.