Manage user access to Cloud projects

You can manage access to Magento Commerce Cloud projects by adding users and assigning roles. Assign project-level roles to provide access to the entire project, and environment-level roles to set permissions per available environment.

Role Scope Access
Account owner Project Perform any task in any project or environment, including deleting it.
Magento assigns this role to the License Owner associated with the email address,
name, and information of the person who registered the Magento Commerce Cloud account.

You must submit a Magento 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.
Project reader 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 and perform tasks on an environment, including merging with the parent environment
Contributor Environment Push code and branch the environment
Reader Environment View-only access to an environment

Add user authentication requirements

For added security, Magento provides project-level MFA enforcement to require two-factor authentication for SSH access to Magento Commerce Cloud project source code and environments. See [MFA enforcement for SSH].

When MFA enforcement is enabled on a Magento Commerce Cloud project, all users with SSH access to an environment in that project must enable two-factor authentication (TFA) on their Magento Commerce Cloud 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 TFA and SSH access.

Add users and manage access

You can add users and assign roles using the Magento CLI or the Project Web Interface.

Changing user configuration on a Magento Commerce Cloud environment triggers a site deployment, which takes your site offline until deployment completes. For Production environments, we recommend 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 Magento Commerce Cloud account. New users can register for an account and provide the associated email address after completing account validation.

Manage users with the CLI

You can use the Magento Commerce Cloud command line client to manage users and integrate this with any other automated system.

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

The following examples use the CLI to add a user, configure roles, and modify project assignments and assigned user roles.

To add a user and assign roles:

  1. Use the 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 roles, and add the user:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    
    Enter the user's email address: alice@example.com
    
    Email address: alice@example.com
    
    The user's project role can be 'viewer' ('v') or 'admin' ('a').
    Project role [V/a]: a
    The user's environment-level roles can be 'viewer', 'contributor', or 'admin'.
    development environment role [V/c/a]: c
    Summary:
      Email address: alice@example.com
      Project role: contributor
    Adding users can result in additional charges.
    Are you sure you want to add this user? [Y/n]
    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, Magento sends an email to the specified address with instructions for accessing the Magento Commerce Cloud project.

The following example changes the environment-level role that is assigned to a user:

1
magento-cloud user:role alice@example.com --level environment --environment development --role admin

The magento-cloud list command displays all the magento-cloud CLI commands.

Manage users from the Project Web UI

You can add project-level and environment-level users 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 Magento Commerce Cloud project.

Access the Project Web UI to add users:

  1. Log in to your Magento Commerce Cloud 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:

  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 Reader (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 the redeploy automatically.

Add an environment-level user:

  1. In the Project Web UI, select the environment. Then, click Configure environment.

    Configure the environment

  2. Click the Users tab, and then click Add User.

  3. Complete the Add User form:

    Add the user

    • Enter the user email address.

    • Select the user role from the dropdown menu: Admin, Contributor, or Reader.

    • Click Add User.

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 settings and add the following security configuration as needed:

  • Enable two-factor authentication (TFA)

    Magento recommends adding two-factor authentication to all accounts to meet security and compliance standards. Projects configured with MFA enforcement require two-factor authentication for all accounts that require SSH access to Magento Commerce Cloud projects.

  • Enable SSH keys

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

  • Create an API token

    You can generate an API token on your account that can be used for secure 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 to bypass authentication workflows which require two-factor authentication.

Enable TFA for Cloud accounts

Magento Commerce Cloud supports two-factor authentication using any of the following applications:

Instructions for installing the authenticator application and enabling two-factor authentication (TFA) are available on the Magento Commerce Cloud Account settings page in the Cloud Project Web UI.

To enable TFA on your Magento Commerce Cloud user account:

  1. Log in to the Magento Commerce Cloud user account.

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

    Cloud projects page

  3. Click Security to access the TFA 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 Magento Commerce Cloud account to the authenticator app.

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

      For example, for Google Authenticator, click the + sign in the app. Then, enter the text code from Magento in the app, or scan the QR code to enable Magento Commerce Cloud TFA.

      Cloud 2FA app device setup

    • On the TFA set up - Application page, type the two-factor authentication 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, Magento sends a notification to the account email address confirming that the account now has two-factor authentication.

  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 TFA setup - Recovery codes page, copy and save the recovery codes so that you can log into your Magento Commerce Cloud project when you cannot access your mobile device or authentication app.

    Cloud TFA recovery codes

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

    • 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 TFA and have no recovery codes, you must contact your project administrator, or submit a Magento support ticket to reset the TFA application.

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

  10. Authenticate your current session with two-factor authentication.

    • Log out of your account.

    • Log in with your username and password.

    • When prompted, enter the two-factor authentication code for the magento.cloufrom the authenticator application on your mobile device

Manage TFA configuration and recovery codes

You can manage the TFA configuration for a Magento Commerce Cloud account from the Security section on the Account settings page.

  1. Log in to the Magento Commerce Cloud user account.

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

  3. Click Security to view the TFA configuration options.

    Cloud manage TFA config

  4. Use the available links to update the two-factor authentication settings for your Magento Commerce Cloud account:

    • Disable two-factor authentication
    • Reset the authenticator application
    • Add or remove trusted browsers
    • View or refresh TFA 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 secure 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 Magento Commerce Cloud 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 will use the API token.

    Cloud create API token

  5. Click Create API token to generate the token.

    Cloud generate API token