Manage user access to Cloud projects

You manage access to Adobe Commerce on cloud infrastructure projects and certain environment types by adding users and assigning roles. Project level roles provide access to the entire project.

Adobe Commerce on cloud infrastructure consists of three environments types: Production, Staging, and Integration. Access to an environment is granted by assigning a user the Admin, Contributor, Viewer, or None role.

Role Scope Access
Account owner Project Perform any task in any project or environment, including deleting it.
Adobe assigns this role to the License Owner associated with the email address, name, and information of the person who registered the Adobe Commerce on cloud infrastructure account. You submit a Adobe Commerce Support ticket to modify settings or change the Account owner.
Super User Project Administrator access to all project settings and Cloud environments. Super users can change settings and perform tasks on any environment, including creating and restoring snapshots and managing users.
Project viewer Project View access to all project environments. Users with this role cannot perform tasks on any environment. However, you can configure environment-level permissions for users with this role to permit write access to a specific environment.
Admin Environment Change settings, push code, perform tasks and branch environments, including merging with the parent environment; SSH access
Contributor Environment Cannot change settings or execute actions; Can push code and branch the environment; SSH access
Viewer Environment View-only access to an environment; No SSH access
None Environment No access to an environment; No SSH access

Add user authentication requirements

For added security, Adobe provides project-level multi-factor authentication (MFA) enforcement to require two-factor authentication (2FA) for SSH access to Adobe Commerce on cloud infrastructure project source code and environments. See Enable MFA for SSH.

When MFA enforcement is enabled on a Adobe Commerce on cloud infrastructure project, all users with SSH access to an environment in that project must enable 2FA on their Adobe Commerce on cloud infrastructure account. For automated processes, users must create an API token that machine users can use to authenticate from the command line. See Enable user accounts for 2FA and SSH access.

Add users and manage access

You add users and assign roles using the magento-cloud CLI or the Project Web Interface.

Changing user configuration on an Adobe Commerce on cloud infrastructure environment requires a site deployment for the changes to take effect, which takes your site offline until the deployment completes. For Production environments, Adobe recommends completing user administration tasks during off-peak hours to prevent service disruptions.

Prerequisites:

  • To add a user to a project or environment, you need the email address associated with an existing Adobe Commerce on cloud infrastructure account. New users can register for an account and provide the associated email address after completing account validation.

  • Users assigned the Admin role cannot manage users using the magento-cloud CLI. Only users that are granted the Super User or Account Owner role can manage users.

Manage users with the magento-cloud CLI

Use the Adobe Commerce on cloud infrastructure magento-cloud CLI to manage users and integrate with automated systems.

Available commands:

  • magento-cloud user:add–add a user to the project
  • magento-cloud user:delete–delete a user
  • magento-cloud user:list [users]–list project users
  • magento-cloud user:role–view or change the user role
  • magento-cloud user:update–update user role on a project

The magento-cloud list command displays all the magento-cloud CLI commands. To view the command and parameters for a specific command and not the entire list, append the command with a -help. For example, magento-cloud environment:list, you run magento-cloud environment:list -help.

The following examples use the magento-cloud CLI to add a user, configure roles, modify project assignments, and assign user roles.

Add a user and assign roles

To add a user and assign roles:

  1. Use the magento-cloud CLI to add the user.

    1
    
    magento-cloud user:add
    
  2. Follow the prompts to specify the user email address, set the project and environment type roles, and add the user:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    
    Enter the user's email address: alice@example.com
    
    Email address: alice@example.com
    
    The user's project role can be admin (a) or viewer (v).
    
    Project role (default: viewer) [a/v]: viewer
    
    The user's environment type role(s) can be admin (a), viewer (v), contributor (c) or none (n).
    
    Role on type development (default: none) [a/v/c/n]: none
    Role on type production (default: none) [a/v/c/n]: admin
    Role on type staging (default: none) [a/v/c/n]: admin
    
    Adding the user alice@example.com to (project_id):
    Project role: viewer
      Role on type production: admin
      Role on type staging: admin
    
    Adding users can result in additional charges.
    
    Are you sure you want to add this user? [Y/n] y
    Adding the user to the project
    

    This operation triggers the Cloud build and deploy process, which takes your site offline until deployment completes. For Production environments, we recommend completing this operation during off-peak hours to prevent service disruptions.

    After you add the user, Adobe sends an email to the specified address with instructions for accessing the Adobe Commerce on cloud infrastructure project.

View a user’s project role

To view a user’s project role:

1
2
magento-cloud user:get user@example.com

Sample response:

1
2
Current role(s) of User (user@example.com) on Production (project_id):
  Project role: admin

Add a user to multiple environments

To add a user as a viewer on a Production environment, and as a contributor on an Integration environment:

1
2
magento-cloud user:add user@example.com -r production:v -r integration:c

Update user environment permissions

To update user environment permissions to admin on the Production environment:

1
magento-cloud user:update user@example.com -r production:a

Manage users from the Project Web UI

You add project-level and environment-level permissions from the Project Web UI, and use the Edit feature to modify permissions for an existing user.

After you add a user, the user receives an email inviting them to join the Adobe Commerce on cloud infrastructure project.

Add users from the Project Web UI

To add users from the Project Web UI:

  1. Log in to your Adobe Commerce on cloud infrastructure account.

  2. Click the Projects tab.

    Click the projects tab to access your Cloud project

  3. Click your project name to open the Cloud project portal (Onboarding UI).

  4. Click Infrastructure access, and then click Project Access (Web UI).

    Cloud project portal

  5. In the Project Web UI, add project-level users and environment-level users as needed.

Add a project-level user

To add a project-level user:

  1. In the Project Web UI, click the settings icon in the top navigation bar.

    Configure the project

  2. In the Users tab, click Add User.

    Start creating users

  3. Complete the Add User form:

    Add users

    • Enter the user e-mail address.

    • Select the access for the account:

      For a project administrator account, select Super User. This role provides Admin rights to all settings and environments. If not selected, the account has only view options for all project environments.

    • Select permissions per specific environment (or branch) in the Integration environment: No access, Admin (change settings, execute action, merge code), Contributor (push code), or Viewer (view only). When you add active environments, you can modify permissions per user.

  4. Click Add User.

    After adding project-level users, you must redeploy all environments to apply the changes. Adding a project user does not trigger a redeploy automatically.

Only Super Users can manage users in any environment. To grant a user access to the Users tab when configuring the environment, another Super User or the Account Owner must assign that user the Super User role.

This operation triggers the Cloud build and deploy process, which takes your site offline until deployment completes. For Production environments, we recommend completing this operation during off-peak hours to prevent service disruptions.

Update account security settings

After you add a user to a Cloud project, ask the user to review their account security settings and add the following security configuration as needed:

  • Enable 2FA

    Adobe recommends adding 2FA to all accounts to meet security and compliance standards. Projects configured with MFA enforcement require 2FA on accounts that use SSH to access the projects.

  • Enable SSH keys

    Users that require access to Adobe Commerce on cloud infrastructure source code repositories and infrastructure must enable SSH keys on their account. See Enable SSH keys.

  • Create an API token

    Users must generate an API token that is used for SSH access to an environment. You need the token to enable authentication workflows for automated processes.

    On projects with MFA enforcement enabled, you must use the API token to authenticate SSH access requests from automated accounts. The token allows automated processes to bypass authentication workflows which require 2FA.

Enable 2FA for Cloud accounts

Adobe Commerce on cloud infrastructure supports 2FA using any of the following applications:

Instructions for installing the authenticator application and enabling 2FA are available on the Adobe Commerce on cloud infrastructure Account settings page in the Project Web UI.

To enable 2FA on your Adobe Commerce on cloud infrastructure user account:

  1. Log in to the Adobe Commerce on cloud infrastructure user account.

  2. On the Cloud projects page, click the Account settings tab.

    Cloud projects page

  3. Click Security to access the 2FA configuration settings. Then, click Set up application.

    Cloud Security settings

  4. If you do not have an approved authenticator application on your mobile device, use the linked instructions to install one.

    Cloud Security settings

  5. Add your Adobe Commerce on cloud infrastructure account to the authenticator application.

    • On your mobile device, open the authenticator application. Then, add the setup code to the application.

      For example, for Google Authenticator, click the + sign in the application. Then, enter the text code from Adobe in the application, or scan the QR code to enable Adobe Commerce on cloud infrastructure 2FA.

      Cloud 2FA application device setup

    • On the TFA set up - Application page, type the 2FA code from your mobile device in the Application verification code field.

      Cloud 2FA app device setup

    • Click Verify and save.

      If the code is valid, Adobe sends a notification to the account email address confirming that the account now has 2FA.

  6. Optional. Enable Trusted browser settings to cache the authentication code in the browser for 30 days.

    This configuration reduces the number of authentication challenges during project login.

  7. Click Save or Skip.

  8. Save the recovery codes.

    • On the 2FA setup - Recovery codes page, copy and save the recovery codes so that you can log into your Adobe Commerce on cloud infrastructure project when you cannot access your mobile device or authentication application.

    Cloud 2FA recovery codes

    • Copy the recovery codes to another location or write them down in case you lose access to your device or authentication application.

    • Click Save to save the codes to your account so you can view and manage them from your account security settings.

      If you lose access to an account with 2FA and have no recovery codes, you must contact your project administrator, or submit a Support ticket to reset the 2FA application.

  9. After completing the 2FA setup, click Save to update your account.

  10. Authenticate your current session with 2FA.

    • Log out of your account.

    • Log in with your username and password.

    • When prompted, enter the 2FA code for the accounts.magento.cloud entry from the authenticator application on your mobile device.

Manage 2FA configuration and recovery codes

You manage the 2FA configuration for a Adobe Commerce on cloud infrastructure account from the Security section on the Account settings page.

  1. Log in to the Adobe Commerce on cloud infrastructure user account.

  2. On the Cloud projects page, click the Account Settings tab.

  3. Click Security to view the 2FA configuration options.

    Cloud manage 2FA config

  4. Use the available links to update the 2FA settings for your Adobe Commerce on cloud infrastructure account:

    • Disable 2FA
    • Reset the authenticator application
    • Add or remove trusted browsers
    • View or refresh 2FA recovery codes on account

Create an API token

An API token can be exchanged for an OAuth 2 access token, which can then be used to authenticate requests.

On projects that have MFA enforcement enabled, you must have an API token to enable SSH access for machine users and automated processes.

Protect API token values for your account. Do not expose the value in code samples, screen captures, or insecure client-server communications. Also, do not expose the value in source code stored in public repositories.

To create an API token:

  1. Log in to the Adobe Commerce on cloud infrastructure account.

  2. On the Cloud projects page, click the Account settings tab.

    Cloud projects page

  3. On the Account settings tab, expand the API Tokens section. Then, click Create an API token.

    Cloud create API token

  4. Specify an Application name for the token, for example, specify a name that matches the machine user or automated process that uses the API token.

    Cloud create API token

  5. Click Create API token to generate the token.

    Cloud generate API token