Version: 6.3.3

Manage Users and Access

This is a guide for Administrators to using role-based authorization configuration (RBAC) for projects and resources in Cortex Fabric.

For additional information view the CLI Reference Guide.

Introduction to Auth

In Cortex Fabric a combination of authentication and authorization is used to provide system security and user access.

Authentication and broad role-mapped authorization is managed through the customer IDP, which, using Dex, is configured to work with Fabric during instantiation. Customers manage Cortex users through their own IDPs.

During system installation IDP-established user-groups are mapped to general Fabric roles (e.g. administrator, developer, business user, and data engineer) to provide authentication and the first layer of authorization. In order to authenticate to Fabric Console, CLI, Python Libraries, and APIs a user must be in at least one group that is mapped to a Cortex role.

In addition a second more granular level of authorization can be configured by Cortex administrators using CLI RBAC commands to manage roles and grant or deny permissions to projects and/or resources. This page provides instructions for using the RBAC CLI commands.

Add Users to Fabric

  1. A system administrator for the Customer IDP adds the user to that system and assigns them to a Customer IDP system role.
  2. Through DEX the user is assigned a corresponding Cortex role and all of the permissions and access afforded to that role.
  3. The customer's Fabric Administrator assigns the user to one or more Projects. New users must be assigned to Projects in order to authenticate to Fabric.

add user flow

After users have been added to Fabric, Cortex Fabric Administrators can manage their access and permissions using RBAC rules and commands.

Default Cortex Fabric Roles

The following table shows the grants for Fabric default roles for some of the key resources.

In addition to these roles Fabric allows for custom roles and permissions to be created.

RoleDescriptionData SourcesProfilesCampaignsModelsAgentsConnectionsSecrets
administratorUsers with this role can create projects, add users to projects, grant and revoke roles for users within projects. This role cannot be deletedALLALLALLALLALLALLALL
ai-developerUsers with this role can create and manage Campaigns and AgentsNONENONEALLALLALLREADREAD
data-engineerUsers with this role can create and manage Data Sources and profilesALLALLNONENONENONEALLREAD
data-scientistUsers with this role work with Models and Experiments.NONENONENONEALLNONENONENONE
business-userUsers with this role can create campaigns and dashboardsNONENONEALLNONENONENONENONE

User authorization experience

In Cortex Fabric Console

  • A user with no projects will still be able to login and see Dashboard, Assessments, and Settings pages (as these are outside of Project scoping).
  • A user with projects will be able to select a project from a list of projects they have been granted access to.
  • After a project is selected users will "see" the resources that they have grants to and they will be able to perform the actions they have grants to perform.

Using CLI, Python Libs, and APIs

If you attempt to use a command or make an API call that you do NOT have grants for an error message is displayed.

Access denied: no ACTION access on PROJECT || RESOURCE

Example:

Access denied: no READ access on roles

Assign users/roles to Projects

A Cortex Fabric Administrator can grant access to Project for either users or roles. If a user belongs to a role that is given access to a project, the user is automatically granted access to the project.

To assign users or roles to Projects an Administrator must authenticate to the Cortex Fabric CLI and run:

cortex roles project projectName --roles rolename

or

cortex users project projectName --users user1@email.com user2@email.com user3@email.com

To remove users/roles from Projects an Administrator must authenticate to the Cortex Fabric CLI and run the assign projects command appended with --delete:

cortex roles project projectName --roles roleName --delete

or

cortex users project projectName --users user1@email.com user2@email.com --delete

RBAC grant commands

RBAC CLI commands and returned JSON are structured to provide the following information.

Grant command components

When you execute a command related to grants the following elements are specified in this order:

  • Subject: --roles role-name or --users user@email.com
  • Project: --project project-name
  • Resource: --resource resource-name (e.g. agents)
    • agents
    • campaigns
    • connections
    • console:agents
    • console:profiles
    • console:connections
    • console:secrets
    • console:datasources
    • console:dashboard
    • console:settings
  • Action(grants): --actions actions-list
    • read - view-only permission
    • write - permission to make additions and changes to a resource
    • execute - permission to use the resource, but not change it

You may specify a wildcard (wrapped) for any component to include all items '*'. Wildcards must be wrapped in single quotes.

Deny flag

A Deny flag may be added to any of Grant commands.

DENY overrides any grants on the Resource/Action that may exist for the user or role.

For example: If a user with the developer role has been granted the ability to create agents, and the admin wants to deny that grant on a specific project, they would configure the denial as follows: cortex users grant user-email --project projectA --resource agents --actions WRITE --deny

Role commands

Default Cortex Roles are:

  • Administrator
  • Developer
  • Data Engineer
  • Business User

CLI commands for Roles are structured as follows:

cortex roles (command) (options)

Example: An Admin creates a role named "devops" with access to a project named "projectA" with the ability to read and write to all resources:

cortex roles create devops --project projectA --resource '*' --actions read write

User commands

Users are identified by email address.

CLI commands for users are structured as follows:

cortex users (command) (options)

Example: An Admin grants swinchester@email.com read access to all resources on all projects:

cortex users grant swinchester@email.com --project '*' --resource '*' --actions read

RBAC CLI commands

RBAC commands may be executed by administrators using the Cortex Fabric CLI.

In general the commands are structured as:

cortex roles [command] [options] and cortex users [command] [options]

ActionDescriptionCommand
List rolesReturns a list of Cortex roles configured in the systemcortex roles list
Describe roleReturns the action, resources, and projects configured and/or a list of users assigned to the specified rolecortex roles describe role-name --grants --users
Create rolesCreates a role and the grants associated with the rolecortex roles create role-name --project project-name --resource resource-name --actions actions-list
Delete rolesDeletes the role specified. When a role is deleted all mappings, grants, and users are removed from the role.cortex roles delete role-name
Grant rolesAssigns (or deletes) additional grants for an existing rolecortex roles grant role-name --project project-name --resource resource-name --actions actions-list
Assign rolesProvides a way to assign a role to userscortex roles assign role-name --users user-email-list
Describe userReturns a list of grants assigned to the user as well as the roles and role-based grants assigned to a specified user. Any user can check their access using this command.cortex users describe --user user-email
Describe users who have access to a project or who are assigned a roleReturns a list of user emails for a role or project (or both)cortex describe users --role roleName or cortex describe users --project projectName
Grant userProvides a way to assign grants directly to a user (rather than through a role)cortex users grant user-name --project project-name --resource resource-name --actions actions-list

RBAC command rules

  • Users are identified by email address.
  • If the email is not attached to a mapped customer IDP group, the user will not be authenticated and will be denied access to Cortex.
  • A user must be assigned to a project before the roles associated with that project become active.
  • Users may be assigned multiple roles with a variety of access levels.
  • The highest level of access is granted.
  • DENY supersedes all other levels of access.
  • Delete grants or users by adding --delete to Grant user, Assign roles, and Grant roles (the options specified are deleted).
  • The Administrator role cannot be deleted.
  • Fabric-default grants that are defined for the default roles cannot be deleted, but they may be denied.

Query your own system permissions

Users with any role may query their own permissions using:

cortex users describe --user my-user@email.com

Example response: Lists in this order your user-email, projects, all grants, all roles, and all external groups

{
"user": "swinchester@email.com",
"projects": [
"myProj"
],
"grants": [],
"roles": [
{
"role": "developer",
"projects": [
"myProjRole"
],
"grants": [
{
"project": "*",
"resource": "actions",
"effect": "allow",
"actions": [
"*"
]
},
{
"project": "*",
"resource": "skills",
"effect": "allow",
"actions": [
"*"
]
},0
}
]
},
{
"role": "administrator",
"projects": [
"*"
],
"grants": [
{
"project": "*",
"resource": "*",
"effect": "allow",
"actions": [
"*"
]
}
]
}
],
"externalGroups": [
{
"externalGroup": "CognitiveScale:cortex-developers",
"roles": [
{
"role": "developer",
"projects": [
"myProjRole"
],
"grants": [
{
"project": "*",
"resource": "actions",
"effect": "allow",
"actions": [
"*"
]
},
{
"project": "*",
"resource": "types",
"effect": "allow",
"actions": [
"*"
]
},
}
]
}
]
}
]
}

Create custom groups

Administrators may create custom groups for authentication mapping from external sources. These are considered types of roles.

When an external provider's groups are mapped to Cortex roles, an attempt is made initially to make a logical mapping using the information returned from the provider. For example if a GitHub provider has a group named "A1" and all the users are labelled developers, Cortex automatically maps "A1" users to the Fabric developer role.

List external roles mappings

Administrators are able to view the external roles and how they are mapped to Fabric roles using the CLI by running.

cortex roles list-external

Example response:

[
{
"group": "cortex-admins",
"roles": [
"developer"
]
},
{
"group": "CognitiveScale:cortex-developers",
"roles": [
"developer"
]
}
]

Describe external roles

Administrators are able to get more information about the external provider roles using the CLI to run:

cortex roles describe-external cortex-admins --users --roles

Where: --users: returns a list of users assigned the role --roles: returns the permissions assigned to the role

Example response:

{
"externalGroup": "cortex-admins",
"roles": [
{
"role": "administrator",
"projects": [
"*"
],
"grants": [
{
"project": "*",
"resource": "*",
"effect": "allow",
"actions": [
"*"
]
}
]
}
],
"users": [
"cortex@example.com"
]
}

Assign an external group to a role

Administrators are able to assign an external group to a role using the CLI to run:

cortex roles assign-external --externalGroup externalGroupName --role roleName

Example response: External group cortex-admins mapped to role administrator

Unassign an external group to a role

Administrators are able to unassign an external group to a role using the CLI to run the assign command appended by --delete:

cortex roles assign-external --externalGroup externalGroupName --role roleName --delete

Example response: External group cortex-admins removed from role business_user

Remove an external group from the system

Administrators are able to remove an external group from the system using the CLI to run:

cortex roles delete-external externalGroup