Custom RBAC#

Managing RBAC and Organizations for SSO users#

For customers using SSO (on-prem only), Arthur provides the ability to set up a fully customizable RBAC. Please follow the below:

When setting up your identity provider via the YAML configuration, supply a global role name and set of permissions under globalRoleDefs that your identity provider will authenticate users with. This configuration will create the global role in the Arthur authorization system when it is applied. See the Creating Global Roles for Managing Organizations and RBAC Policies Guide for more information.
That global role can then create custom role mappings for each organization:
- During organization creation, include the role configuration JSON (see below for example) in the request body when calling POST /organizations.
- After an organization is created, create or add custom_roles by sending the role configuration JSON (see below for example) in the request body when calling POST /autorization/custom_roles.
Users logging in through your IdP must now have a valid known role in their token when accessing the Arthur Platform. Arthur will use this role to both authenticate that the user is a member of the organization and to determine the permissions they have.

Managing Roles and Permissions#

Steps to create a custom role for your Arthur org#

1. Determine the permissions you need#

Typically, you can start with an existing standard role and add permissions to that role as needed. First, take a look at the list of standard roles. These can serve as a guide for what types of permissions should be given to what types of users. Next, to understand each category of permissions more granularly you can reference the full directory of permissions. While going through these permission sets, look at the associated API endpoints to understand the types of data and actions the user will be able to access if given that permission.

2. Decide how you want to create your custom role#

Once you have determined the permissions you want to utilize, you can create your custom role by inheriting from a standard role, defining a custom permission set, or some combination of both.

To inherit from a standard role, specify the standard role name in the inherited_role_names field in the request:

    {
      "role_name": "new_custom_role_1",
      "inherited_role_names": [
        "Model Reader"
      ]
    }

To create a role using a custom set of permissions, specify the permission as resource acion pairs in the permissions field in the request:

{
      "role_name": "new_custom_role_2",
      "permissions": [
        {
          "resource": "raw_data",
          "action": "write"
        },
        {
          "resource": "raw_data",
          "action": "delete"
        }
      ]
    }

To inherit from a standard role as well as add a set of custom permissions to the role, combine both in the request:

{
      "role_name": "new_custom_role_3",
      "permissions": [
        {
          "resource": "raw_data",
          "action": "write"
        },
        {
          "resource": "raw_data",
          "action": "delete"
        }
      ],
      "inherited_role_names": [
        "Model Reader"
      ]
}

NOTE: Inheriting form a standard role gives your custom role ALL permissions that the standard role has. Grnaular permissions in the reuqest will be additive to those base permissions. You can not remove permissions inherited from the standard role.

3. Create the custom role#

Once you have determined the custom role you want to create, you can create the role either at the time of creating an organization or after the fact using the custom_roles API.

During organization creation, include the role configurations in the roles field in the request body when calling POST /organizations:

{
    "name": "new_organization_with_custom_roles",
    "roles": [
            {
                "role_name": "new_custom_role_1",
                "inherited_role_names": [
                     "Model Reader"
                ]
            }, 
            {
                "role_name": "new_custom_role_2",
                "permissions": [
                  {
                    "resource": "raw_data",
                    "action": "write"
                  },
                  {
                    "resource": "raw_data",
                    "action": "delete"
                  }
                ]
            }
        ]
}

After an organization is created, create or add custom_roles by including the role configurations in the roles field in the request body when calling POST /autorization/custom_roles. Note: this endpoint is additive, if custom roles already exist for this organization, calling this endpoint will add any additional roles and maintain existing roles.

{
    "roles": [
            {
                "role_name": "new_custom_role_1",
                "inherited_role_names": [
                     "Model Reader"
                ]
            }, 
            {
                "role_name": "new_custom_role_2",
                "permissions": [
                  {
                    "resource": "raw_data",
                    "action": "write"
                  },
                  {
                    "resource": "raw_data",
                    "action": "delete"
                  }
                ]
            }
        ]
}

A few notes to recap:

This endpoint only operates on permission scopes within each organization. Permissions that have global scope (such as creating a new organization) cannot be granted via this endpoint, those permissions must be assigned to a role with global privileges via the Arthur IdP configuration YAML. See Creating Global Roles for Managing Organizations and RBAC Policies Guide for more information.
Roles can have a list of permissions to allow and/or a list of other roles to inherit permissions from.
Role names cannot conflict with standard role names.
Supplied permissions must be valid known Arthur permissions.
Roles can inherit the permissions of other roles that are either standard roles, or roles also defined in the same organization. Unknown inherited role names will be rejected.

4. Check & edit the custom role over time as needed#

Get Custom Roles

To retrieve a list of roles defined for an organization, use: GET /autorization/custom_roles.

To filter on specific roles pass a comma separated list of role names in a roles query parameter. For example:/authorization/custom_roles?roles=role1,role2. If you wish to return all roles simply leave out the query parameter or pass "*" as role.

Delete Custom Roles

To delete a role or multiple roles from an organization, use DELETE /autorization/custom_roles. Specify which roles to delete in the JSON request body. For example, to delete a single role:

{
  "roles": [
    "role3"
  ]
}

To delete all roles pass “*”.

Warning

If you do not specify an organization_id and you are a global user, this will delete all custom roles you have created across all organizations.

{
  "roles": [
    "*"
  ]
}