User Management

1 - User Management

Introduction

In this section you will learn how to create accounts, users, and role assignment with the Anchore Enterprise UI.

Assumptions

• You have a running instance of Anchore Enterprise and access to the UI.
• You have the appropriate permissions to create accounts, users, and roles. This means you are either a user in the admin account, or a user that already is a member of the account-users-admin role for your account.

For more information on accounts, users, roles, and permissions see: Role Based Access Control

Navigation

• After a successful login, navigate to the configuration tab on the main menu.

Creating Accounts

In order to create accounts, navigate to the accounts tab from inside the configuration view and select “Create New Account”.

Upon selection, a popup window will display asking for two items:

• Account Name (required)
• Email In the following example I’ve created a ‘security’ account:

Now that a group has been created, I can begin to add users to it.

Viewing Role Permissions

To view the permissions associated with a specific role using the UI, select an account, and navigate to the roles tab:

To view the members in the account assigned to a specific role, select the ‘View’ button on the right-hand side.

Creating Users and assigning Roles

Upon immediate creation of an account, there will, by default be zero users. To add users, select the edit button corresponding the account you would like to add users to. This will bring you to the account page, where you can add your first user by selecting the “Let’s add one!” button.

Upon selection, a popup window will display asking for three items:

• Username (required)
• Password (required)
• Assign Role(s)
  • Note that you can assign more than one role to a user. For a normal user with full access to add, update, and evaluate images, we recommend assigning the read-write role. The other roles are for specific use-cases such as CI/CD automation, and read-only access for reporting. See: Role Based Access Control from more details on the roles and their capabilities.

In this case I’ve assigned three roles to the user:

Once ‘OK’ is selected, the user will be created and you will be able to edit or remove the user as needed.

Deleting and Disabling Accounts

In order to delete an account, disable the account by sliding the button under the ‘Active’ column for the corresponding account, then select the ‘Remove’ button on the right-hand side.

A few notes to keep in mind when deleting accounts:

• The ‘admin’ account is locked and cannot be deleted.
• Once deletion is in progress, all resources (users, images, automated tasks, etc) will start a garbage collection process and won’t be viewable. Although it will still be present in the list to prevent admins from adding an account with the same name.
• Once deleted, an account and their associated resources can’t be recovered.

A couple notes on disabling accounts:

• Disabling accounts is a way for administrators to freeze an account while still keeping any associated analysis info intact.
• Any automated tasks associated with the disabled account will be frozen.

Switching Account Data Context

System administrator users are able to view another account’s data context using the dropdown located at the top-right:

Generating API Keys

Enterprise release 5.1 adds support for API keys for various operations. This is to facilitate use-cases where the user does not want to expose their main credentials e.g. integrations can switch to using API keys instead of username/password credentials.

In order to generate an API key, navigate to the Enterprise UI and click on the top right button and select ‘API Keys’:

Clicking ‘API Keys’ will present a dialog that lists your active, expired and revoked keys:

To create a new API key, click on the ‘Create New API Key’ and this will open another dialog where it asks you for relevant details for the API key:

You can specify the following fields:

• Name: The name of your API key. It is mandatory and unique i.e. you cannot have two API keys with the same name.
• Description: An optional text descriptor for your API key.
• Expiry Date: An expiry date for your API key, you cannot specify a date in the past and it cannot exceed 365 days by default.

Click save to save your API key, the UI will display the output of the operation:

NOTE!: Make sure you copy the value that’s output, there is no way to get this key value back.

Revoking API keys

If there is a situation where you feel your API key has been compromised, you can revoke an active key. This prevents the key from being used for authentication. To revoke a key, click on the ‘Revoke’ button next to a key:

NOTE: Be careful revoking a key, this is an irreversible operation i.e. you cannot mark it active later.

The UI by default only displays active API keys, if you want to see your revoked and expired keys, check the toggle to ‘Show only active API keys’:

Managing API Keys as an Admin

As an account admin you can manage API keys for all users in the account you are admin in. A global admin can manage API keys across all accounts and all users.

To access the API keys as an admin, click on the ‘System’ icon and navigate to ‘Accounts’:

Click ‘Edit’ for the account you want to manage keys for and click on the ‘Tools’ button against the user you wish to manage keys for:

2 - Accounts and Users

System Initialization

When the system first initializes it creates a system service account (invisible to users) and a administrator account (admin) with a single administrator user (admin). The password for this user is set at bootstrap using a default value or an override available in the config.yaml on the catalog service (which is what initializes the db). There are two top-level keys in the config.yaml that control this bootstrap:

• default_admin_password - To set the initial password (can be updated by using the API once the system is bootstrapped). Defaults to foobar if omitted or unset.

• default_admin_email - To set the initial admin account email on bootstrap. Defaults to admin@myanchore if unset

Managing Accounts Using AnchoreCTL

These operations must be executed by a user in the admin account. These examples are executed from within the enterprise-api container if using the quickstart guide:

First, exec into the enterprise-api container, if using the quickstart docker compose. For other deployment types (eg. helm chart into kubernetes), execute these commands anywhere you have AnchoreCTL installed that can reach the external API endpoint for you deployment.

docker compose exec enterprise-api /bin/bash

Getting Account and User Information

To list all the currently present accounts in the system, perform the following command:

# anchorectl account list
 ✔ Fetched accounts
┌──────────┬────────────────────┬──────────┐
│ NAME     │ EMAIL              │ STATE    │
├──────────┼────────────────────┼──────────┤
│ admin    │ admin@myanchore    │ enabled  │
│ devteam1 │ [email protected] │ enabled  │
│ devteam2 │ [email protected] │ enabled  │
└──────────┴────────────────────┴──────────┘

To review the list of users for a specific account, issue the following:

# anchorectl user list --account devteam1
 ✔ Fetched users
┌───────────────┬──────────────────────┬──────────────────────┬────────┬────────┐
│ USERNAME      │ CREATED AT           │ LAST UPDATED         │ SOURCE │ TYPE   │
├───────────────┼──────────────────────┼──────────────────────┼────────┼────────┤
│ devteam1admin │ 2022-08-25T17:43:43Z │ 2022-08-25T17:43:43Z │        │ native │
└───────────────┴──────────────────────┴──────────────────────┴────────┴────────┘

Adding a New Account

To add a new account which, by default, will have no active credentials, issue the following command:

# anchorectl account add devteam1 --email [email protected]
 ✔ Added account
Name: devteam1
Email: [email protected]
State: enabled# 

Note that the email address is optional and can be omitted.

At this point the account exists but contains no users. To create a user with a password, see below in the Managing Users section.

Disabling Account

Disabling an account prevents any of that account’s users from being able to perform any actions in the system. It also disabled all asynchronous updates on resources in that account, effectively freezing the state of the account and all of its resources. Disabling an account is idempotent, if it is already disabled the operation has no effect. Accounts may be re-enabled after being disabled.

# anchorectl account disable devteam1
 ✔ Disabled account
State: disabled

Enabling an Account

To restore a disabled account to allow user operations and resource updates, simply enable it. This is idempotent, enabling an already enabled account has no effect.

# anchorectl account enable devteam1
 ✔ Enabled account
State: enabled

Deleting an Account

Note: Deleting an account is irreversible and will delete all of its resources (images, policies, evaluations, etc).

Deleting an account will synchronously delete all users and credentials for the account and transition the account to the deleting state. At this point the system will begin reaping all resources for the account. Once that reaping process is complete, the account record itself is deleted. An account must be in a disabled state prior to deletion. Failure to be in this state results in an error:

# anchorectl account delete devteam1
error: 1 error occurred:
	* unable to delete account:
{
  "detail": {
    "error_codes": []
  },
  "httpcode": 400,
  "message": "Invalid account state change requested. Cannot go from state enabled to state deleting"
}

So, first you must disable the account, as shown above. Once disabled:

# anchorectl account disable devteam1
 ✔ Disabled account
State: disabled

# anchorectl account delete devteam1
 ✔ Deleted account
No results

# anchorectl account get devteam1
 ✔ Fetched account
Name: devteam1
Email: [email protected]
State: deleting

Managing Users Using AnchoreCTL

Users exist within accounts, but usernames themselves are globally unique since they are used for authenticating api requests. User management can be performed by any user in the admin account in the default Anchore Enterprise configuration using the native authorizer. For more information on configuring other authorization plugins see: Authorization Plugins and Configuration.

Create User in a User-Type Account

To create a new user credential within a specified account, you can issue the following command. Note that the ‘role’ assigned will dictate the API/operation level permissions granted to this new user. See help output for a list of available roles, or for more information you can review roles and associated permissions via the Anchore Enterprise UI. In the following example, we’re granting the new user the ‘full-control’ role, which gives the credential full access to operations within the ‘devteam1’ account namespace.

# ANCHORECTL_USER_PASSWORD=devteam1adminp4ssw0rd anchorectl user add --account devteam1 devteam1admin --role full-control
 ✔ Added user                                                                                                                                                                                                                                                devteam1admin
Username: devteam1admin
Created At: 2022-08-25T17:50:18Z
Last Updated: 2022-08-25T17:50:18Z
Source:
Type: native

# anchorectl user list --account devteam1
 ✔ Fetched users
┌───────────────┬──────────────────────┬──────────────────────┬────────┬────────┐
│ USERNAME      │ CREATED AT           │ LAST UPDATED         │ SOURCE │ TYPE   │
├───────────────┼──────────────────────┼──────────────────────┼────────┼────────┤
│ devteam1admin │ 2022-08-25T17:50:18Z │ 2022-08-25T17:50:18Z │        │ native │
└───────────────┴──────────────────────┴──────────────────────┴────────┴────────┘

That user may now use the API:

# ANCHORECTL_USERNAME=devteam1admin ANCHORECTL_PASSWORD=devteam1adminp4ssw0rd ANCHORECTL_ACCOUNT=devteam1 anchorectl user list
 ✔ Fetched users
┌───────────────┬──────────────────────┬──────────────────────┬────────┬────────┐
│ USERNAME      │ CREATED AT           │ LAST UPDATED         │ SOURCE │ TYPE   │
├───────────────┼──────────────────────┼──────────────────────┼────────┼────────┤
│ devteam1admin │ 2022-08-25T17:50:18Z │ 2022-08-25T17:50:18Z │        │ native │
└───────────────┴──────────────────────┴──────────────────────┴────────┴────────┘

Deleting a User

Using the admin credential, or a credential that has a user management role assigned for an account, you can delete a user with the following command. In this example, we’re using the admin credential to delete a user in the ‘devteam1’ account:

ANCHORECTL_USERNAME=admin ANCHORECTL_ACCOUNT=admin ANCHORECTL_PASSWORD=foobar anchorectl user delete devteam1admin --account devteam1
 ✔ Deleted user
No results

Updating a User Password

Note that only system admins can execute this for a different user/account.

As an admin, to reset another users credentials:

# ANCHORECTL_USER_PASSWORD=n3wp4ssw0rd anchorectl user set-password devteam1admin --account devteam1
 ✔ User password set
Type: password
Value: ***********
Created At: 2022-08-25T17:58:32Z

To update your own password:

# ANCHORECTL_USERNAME=devteam1admin ANCHORECTL_PASSWORD=existingp4ssw0rd ANCHORECTL_ACCOUNT=devteam1 anchorectl user set-password devteam1admin
 ❖ Enter new user password  : ●●●●●●●●●●●
 ❖ Retype new user password : ●●●●●●●●●●●
 ✔ User password set
Type: password
Value: ***********
Created At: 2022-08-25T18:00:35Z

Or, to perform the operation fully-scripted, you can set the new password as an environment variable:

ANCHORECTL_USERNAME=devteam1admin ANCHORECTL_PASSWORD=existingp4ssw0rd ANCHORECTL_ACCOUNT=devteam1 ANCHORECTL_USER_PASSWORD=n3wp4ssw0rd anchorectl user set-password devteam1admin
 ✔ User password set
Type: password
Value: ***********
Created At: 2022-08-25T18:01:19Z

3 - Data Account/Context Switching

Overview

Administrators and specially-entitled standard users are offered the ability to context switch between the image analysis data contexts of different accounts. This capability allows you to view the analysis data held inside a different account while still retaining your own user profile configuration.

When you switch data context, the data-oriented aspects of the application will change but the qualities specific to your original account—herein referred to as your actual account—remain the same. Administrators keep their original permission set and have full control within the switched account. The account availability and associated permission set for standard users is decided by the role configuration of their switching entitlement, and these roles can be additionally set to differ per account.

This feature allows users to gain insights into multiple datasets, can be used by administrators for troubleshooting purposes or to make ad-hoc modifications to the data-oriented aspects of any account, and provides standard users with an additional level and vector of access control.

This following sections in this document describes how to switch and reset data contexts—both as an administrator and as a standard user—and how administrators can assign this capability to standard users.

Administrative Users

Context switching as as an administrator is available without prior configuration, and only requires that an account other than your own be available. When you click the account button in the top-right of the screen you are presented with a menu that contains an entry called Switch Account Data Context, which will be enabled when one or more accounts other than your own are present.

Clicking this item displays a submenu that describes all currently available accounts—both active and disabled—into which you can switch context:

Your home account is represented by the label Actual. If an account is disabled, this is indicated by the label Disabled (note that only administrators can context switch into disabled accounts). The account category—administrator or standard user—is indicated by the user-type icon.

Your current data context is represented by an entry with an emphasized title and checkmark prefix. When you click an entry for a different account, the application view will switch to use the data provided by this new context. The account button and dropdown items are similarly updated to reflect this change:

You will also notice a change to the background color of the main view, which serves as a reminder that your current data context is now different than the one provided by your actual account. In addition, a button is now present on the navigation bar that allows you to immediately revert to your actual data context when clicked (you can of course also use the menu to do this):

In the above example, the analysis information now presented is exactly what a user of the standard account would see in their actual account. As an administrator, you are now free to browse and interact with this data, add tags or repositories for analysis, create policies etc., and there are no permission restrictions on any of these operations.

Note: only the analysis data context has switched, and this new state does not extend to application data items such a private registry configurations.

Standard Users

Non-administrative users can also switch context if this capability has been conferred upon them by an administrator.

When you add a new standard user (or modify an existing one) you can optionally associate them with one or more additional accounts, providing those accounts are not currently disabled. The Add a New User dialog, which is accessed from within the account editor in the Configuration > Accounts view, is shown below:

Note: If an account is currently active and available for addition, but is subsequently disabled, the standard user will not be able to switch into that account.

For each associated account you must also provide one or more RBAC roles that determine how the standard user can interact with that account after they have switched context:

For example, a user may have full-control within their actual account, but could be restricted to read-only operations after switching context. You can provide multiple different roles for different accounts, but you must provide at least one role per account association:

Account associations can also be removed by clicking the X adjacent to each role list, or by removing the labels directly from the Associate Account(s) dropdown control.

Once you are satisfied with the user configuration, click OK to create (or update) these associations. The standard user will now be able to switch account data context using the same procedure as the one described for administrators, presented earlier in this document.

4 - Role-Based Access Control

Overview

Anchore Enterprise includes support for using Role-Based Access Control (RBAC) to control the permissions that a specific user has to a specific set of resources in the system. This allows administrators to configure specific, limited permissions on user enabling limited access usage for things like CI/CD automation accounts, read-only users for browsing analysis output, or security team users that can modify policy but not change image analysis configuration.

Anchore Enterprise provides a predefined of roles. Please see table below for complete list.

The Enterprise UI contains an enumeration of the specific permissions granted to users that are members of each of the roles.

Roles, Users, and Accounts

Roles are applied within the existing account and user frameworks defined in Anchore Enterprise. Resources are still scoped to the account namespace and accounts provide full resource isolation (e.g. an image must be analyzed within an account to be referenced in that account). Roles allow users to be granted permissions in both the account to which they belong as well as external accounts to facilitate resource-sharing.

Terminology

User: An authenticated identity (a principal in rbac-speak).

Account: A resource namespace and user grouping that also defines an authorization domain to which permissions are applied.

Role: A named set of permissions.

Permission: An action to grant an operation on a set of resources.

Action: The operation to be executed, such as listImages, createRegistry, and updateUser.

Target: The resource to be operated on, such as an image digest.

Role Membership: Mapping a username to a role within a specific account. This confers the permissions defined by the role to resources in the specified account to the specified user. The user is not required to be a member of the account itself.

Constraints

1. A user may be a member of a role within one or more accounts.
2. A user may be a member of many roles, or no roles.
3. There is no default role set on a user when a user is created. Membership must be explicitly set.
4. Roles are immutable. The set of actions they grant is static.
5. Creating and deleting accounts is only available to users in the admin account. The scope of accounts and roles is different than other resources because they are global. The authorization domain for those resources is not the account name but rather the global domain: system.

Role Summary and Permissions

Note: All account scoped roles have these roles implicitly granted as well: selfListApiKeys, selfCreateApiKey, selfUpdateApiKey, selfDeleteApiKey, selfGetApiKey, selfGetCredentials, selfAddCredential, selfDeleteCredential

Granting Cross-Account Access

The Anchore API supports a specific mechanism for allowing a user to make requests in another account’s namespace, the x-anchore-account header. By including x-anchore-account: "desiredaccount" on a request, a user can attempt that request in the namespace of the other account. This is subject to full authorization and RBAC.

To grant a username the ability to execute operations in another account, simply make the username a member of a role in the desired account. This can be accomplished in the UI or via API against the RBAC Manager service endpoint. For example, using curl:

curl -u admin:foobar -X POST -H "Content-Type: application/json" -d '{"username": "someuser", "for_account": "some_other_account"}' http://localhost:8229/roles/policy-editor/members

This should be done with caution as there is currently no support for resource-specific access controls. A user will have the permitted actions on all resources in the other account (based on the permissions of the role). For example, making a user a member of policy-editor role for another account will enable full ability to create, delete, and update that account’s policy bundles.

WARNING: Because roles do not currently provide custom target/resource definitions, assigning users to the Account User Admin role for an account other than their own is dangerous because there are no guards against that user then removing permissions of the granting user (unless that user is an ‘admin’ account user), so use with extreme caution.

NOTE: admin account users are not subject to RBAC constraints and therefore always have full access to add/remove users to roles in any account. So, while it is possible to grant them role membership, the result is a no-op and does not change the permissions of the user in any way.

4.1 - User Groups

Overview

User groups are abstractions that allow an administrator to manage permissions for users across the system without having to manage each individual user’s permissions.

Administrators simply have to create a user group, define roles per accounts within the user group and then associate users with it. Users can be associated with multiple user-groups. Each user inherits roles from their user group as well as any explicitly defined roles.

Users can be explicitly added to a User Group (as described above) or SAML users can have an indirect membership of a user group based on their IDP associations.

Note: User Group management is strictly limited to admin users only.

Terminology

• User Group: A basic resource that grants roles and permissions to users on various accounts

        "name": "user-group-engineers",
        "description": "The group permissions for all engineers",

• User Group Roles: A collection of roles associated with a user group, this can span multiple accounts and have multiple roles per account. E.g.

    [  
        {Account: "devs_account",    Roles: [“policy-editor”,”image-analyzer”]},
        {Account: "devops_account",  Roles: [“read-write”]},
        {Account: "preview_account", Roles: [“read-only”]}
    ]

• IDP User Group Mappings: A set of User Groups that are mapped to a single Identity provider. E.g.

    {
        IDP Name: "keycloak", 
        User Groups: [“user-group-engineers”, ”user-group-devsec”, ”user-group-auditors”]}

• User Group Native User Member: A native user who has been explicitly associated with a User Group. This user inherits all roles from the User Group in addition to any roles assigned directly to this user.
• User Group IDP Member: An SAML user who is an indirect member of a User Group. As the SAML user authenticates, the IDP’s User Group Mappings are used to determine if this user should be associated with a User Group.

Native users

Native users are users that are defined in Anchore Enterprise and do not authenticate using an external SSO endpoint. These users can be added to User Groups directly and inherit roles from the User Groups they are members of.

SAML(SSO) users

SAML users are users that authenticate using an external SAML IDP. These users can be associated with User Groups based on their group memberships in the SAML IDP.

SAML users are automatically added to a User Group based on their group memberships in the SAML IDP and the IDP’s User Group associations.

User Group management

User Groups can be managed from the Anchore Enterprise UI or using the Anchore Enterprise API.

AnchoreCTL

User Groups can be managed using the anchorectl CLI tool. The following commands are available for User Group management:

• To create a new User Group, use the following command:

# anchorectl usergroup add development --description "The development team"
 ✔ Added usergroup                                                                                                                                                                                                       
Name: development
Description: The development team
Group Uuid: 4a5d8357-1fc3-44cf-8a1c-9882406df656
Created At: 2024-03-20T15:57:20.086665Z
Last Updated: 2024-03-20T15:57:20.086669Z
Account Roles:
  Items: 

• To list all User Group, use the following command:

# anchorectl usergroup list
┌─────────────┬──────────────────────┬──────────────────────────────────────┐
│ NAME        │ DESCRIPTION          │ GROUP UUID                           │
├─────────────┼──────────────────────┼──────────────────────────────────────┤
│ development │ The development team │ 4a5d8357-1fc3-44cf-8a1c-9882406df656 │
└─────────────┴──────────────────────┴──────────────────────────────────────┘

• To edit the description of a User Group, use the following command:

# anchorectl usergroup update development --description "New development team description"
 ✔ Update usergroup                                                                                                                                                                                                      
Name: development
Description: New development team description
Group Uuid: 4a5d8357-1fc3-44cf-8a1c-9882406df656
Created At: 2024-03-20T15:57:20.086665Z
Last Updated: 2024-03-20T16:00:17.989822Z
Account Roles:
  Items: 

• To delete a User Group, use the following command:

# anchorectl usergroup delete development
 ✔ Deleted usergroup                                                                                                                                                                                                     
No results                                                                                                                                                                                                    

• To add an account role to a User Group, use the following command:

# anchorectl usergroup role add development dev_account --role image-analyzer,image-developer,read-only,repo-analyzer
 ✔ Added account and role(s)                                                                                                                                                                                             
┌────────────────┬───────────────────────────────────────────────────────────┐
│ ACCOUNT/DOMAIN │ ROLES                                                     │
├────────────────┼───────────────────────────────────────────────────────────┤
│ dev_account    │ image-analyzer, image-developer, read-only, repo-analyzer │
└────────────────┴───────────────────────────────────────────────────────────┘

# anchorectl usergroup role add development devops_account --role read-only                                                
 ✔ Added account and role(s)                                                                                                                                                                                             
┌────────────────┬───────────────────────────────────────────────────────────┐
│ ACCOUNT/DOMAIN │ ROLES                                                     │
├────────────────┼───────────────────────────────────────────────────────────┤
│ dev_account    │ image-analyzer, image-developer, read-only, repo-analyzer │
│ devops_account │ read-only                                                 │
└────────────────┴───────────────────────────────────────────────────────────┘

• To list all account roles for a User Group, use the following command:

# anchorectl usergroup role list development                                                                               
 ✔ Fetched usergroups accounts and roles                                                                                                                                                                                 
┌────────────────┬───────────────────────────────────────────────────────────┐
│ ACCOUNT/DOMAIN │ ROLES                                                     │
├────────────────┼───────────────────────────────────────────────────────────┤
│ dev_account    │ image-analyzer, image-developer, read-only, repo-analyzer │
│ devops_account │ read-only                                                 │
└────────────────┴───────────────────────────────────────────────────────────┘

• To remove account role(s) from a User Group, use the following command:

# anchorectl usergroup role delete development dev_account --role image-analyzer,image-developer 
 ✔ Deleted role                                                                                                                                                                                                          
No results

• To add a native user to a User Group, use the following command:

# anchorectl usergroup user add development -u dev_user
 ✔ Added user(s)                                                                                                                                                                                                         
┌──────────┬─────────────────────────────┐
│ USERNAME │ ADDED TO USER GROUP ON      │
├──────────┼─────────────────────────────┤
│ dev_user │ 2024-03-20T16:30:20.092909Z │
└──────────┴─────────────────────────────┘

• To list all members of a User Group, use the following command:

# anchorectl usergroup user list development
 ✔ Fetched users within usergroup                                                                                                                                                                                        
┌──────────┬─────────────────────────────┐
│ USERNAME │ ADDED TO USER GROUP ON      │
├──────────┼─────────────────────────────┤
│ dev_user │ 2024-03-20T16:30:20.092909Z │
└──────────┴─────────────────────────────┘

• To remove a native user from a User Group, use the following command:

# anchorectl usergroup user delete development -u dev_user
 ✔ Deleted user(s)                                                                                                                                                                                                       
No results