Manage Users and Access
This is a guide for Administrators to using role-based authorization configuration (RBAC) for projects and resources in SENSA Fabric.
For additional information view the CLI Reference Guide.
Introduction to Auth
In SENSA 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
- A system administrator for the Customer IDP adds the user to that system and assigns them to a Customer IDP system role.
- Through DEX the user is assigned a corresponding Cortex role and all of the permissions and access afforded to that role.
- 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.
After users have been added to Fabric, SENSA Fabric Administrators can manage their access and permissions using RBAC rules and commands.
Default SENSA 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.
| Role | Description | Data Sources | Profiles | Campaigns | Models | Agents | Connections | Secrets |
|---|---|---|---|---|---|---|---|---|
| administrator | Users with this role can create projects, add users to projects, grant and revoke roles for users within projects. This role cannot be deleted | ALL | ALL | ALL | ALL | ALL | ALL | ALL |
| ai-developer | Users with this role can create and manage Campaigns and Agents | NONE | NONE | ALL | ALL | ALL | READ | READ |
| data-engineer | Users with this role can create and manage Data Sources and profiles | ALL | ALL | NONE | NONE | NONE | ALL | READ |
| data-scientist | Users with this role work with Models and Experiments. | NONE | NONE | NONE | ALL | NONE | NONE | NONE |
| business-user | Users with this role can create campaigns and dashboards | NONE | NONE | ALL | NONE | NONE | NONE | NONE |
User authorization experience
In SENSA 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.
If you do not see a page or section of Console that you expect to see, it's likely that you do not have the appropriate grants for access. Check your permissions following the instructions below.
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 SENSA 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.
- Creating a grant with project = '*' creates a template which can be used by any project the entity is assigned to
- Creating a grant with project = 'something other than *' will automatically assign the entity to that project
To assign users or roles to Projects an Administrator must authenticate to the SENSA 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 SENSA 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
If a user is assigned grants to a Project, they are automatically assigned to the Project.
To remove a user or a role from having access to a Project, you MUST explicitly remove the project, removing grants will NOT remove Project access.
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-nameor--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.
DO NOT assign * to a RESOURCE for non-admin users. This will give them the ability to alter ROLES and USERS.
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
Deny overrides all grants with one exception: If a role is assigned to a Project and a user is assigned to that role but is not assigned directly to the Project, the role's grants maintain priority over a DENY flag. To deny the user access you must add a deny flag to the role or assign the user to the project and then deny the user (if you don't want everyone with the role to be denied access).
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 SENSA Fabric CLI.
In general the commands are structured as:
cortex roles [command] [options] and cortex users [command] [options]
| Action | Description | Command |
|---|---|---|
| List roles | Returns a list of Cortex roles configured in the system | cortex roles list |
| Describe role | Returns the action, resources, and projects configured and/or a list of users assigned to the specified role | cortex roles describe role-name --grants --users |
| Create roles | Creates a role and the grants associated with the role | cortex roles create role-name --project project-name --resource resource-name --actions actions-list |
| Delete roles | Deletes the role specified. When a role is deleted all mappings, grants, and users are removed from the role. | cortex roles delete role-name |
| Grant roles | Assigns (or deletes) additional grants for an existing role | cortex roles grant role-name --project project-name --resource resource-name --actions actions-list |
| Assign roles | Provides a way to assign a role to users | cortex roles assign role-name --users user-email-list |
| Describe user | Returns 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 role | Returns a list of user emails for a role or project (or both) | cortex describe users --role roleName or cortex describe users --project projectName |
| Grant user | Provides 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 |
| Get user PAT | Provides a way to get personal access token (PAT) for a specified user (default: current user) | cortex users get-pat --user user-email |
| Reset user PAT | Provides a way to reset personal access token (PAT) for a specified user (default: current user) | cortex users reset-pat --user user-email |
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": [
"*"
]
},
}
]
}
]
}
]
}
Query your own Personal Access Token (PAT)
Note: Commands reset-pat & get-pat don't require --project parameter
cortex users get-pat
Example response:
{
"jwk": {
"crv": "Ed25519",
"d": "6UwxVGv3I8dzo74",
"x": "Xe9m6_-FtAxL1Y9pxjDfs",
"kty": "OKP",
"kid": "KrxrPTmZQNztZg",
"alg": "EdDSA"
},
"issuer": "tecnotree.com",
"audience": "sensa",
"username": "9bf6d47c-ed2d-1234-1234-f1812146bab3",
"url": "https://host.example.com"
}
Create custom groups
Changes to external groups take place in real-time and user access is changed immediately upon executing the following commands.
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