• Log in

Migrate your users to our newer user model

Starting April 12, 2021, we're allowing some customers who have users on our original user model to migrate those users to be on our newer user model.


On July 30, 2020, we released a new, improved user model (sometimes referred to as the New Relic One user model). This newer user model offers a simpler, more efficient way to manage users and their access to roles and accounts.

At first, this new model was available mainly to new customers, while users in pre-existing New Relic organizations remained on our original user model. But now some original-user-model organizations that meet some requirements can use a migration wizard to migrate their users to the new model. When that migration process is complete, your users are on our newer user model and you'll have new procedures for managing your users and their access to accounts.


When you migrate your users to this model, benefits include:

  • Viewing and managing all users from multiple accounts in one place.
  • Fewer steps to add and manage users.
  • Flexible authentication options.
  • More granular roles for user management.
  • For Pro and Enterprise customers: access to automated user management via identity providers.

Learn more about the benefits of our new user model.


Requirements include:

  • You and your users must be on the original user model. If you aren't sure which you are, see Determine user model.
  • To use the user migration wizard, you must have the Owner role and be a full platform user.
  • If your users must have permissions set up to give them specific roles and specific accounts, you will need to set up permissions for them and should understand the new user management concepts before starting (more on that below).

Determine if you should migrate users

We have some recommendations below that apply to organizations who choose to do the user migration on their own. These considerations won't apply if you're being helped by a New Relic representative; in that case, your account representative will give you guidance.

We recommend not using the user migration wizard in these circumstances:

  • If you think any of the new user model impacts and limitations might affect you negatively.
  • If you require account-level roles for user management capabilities. Roles related to user management (ability to add and update users, change user type, create access grants) currently apply across an entire organization and can't be assigned to specific accounts.

If you have questions about whether you should use the user migration wizard, talk to your New Relic account representative.

Optional: review your users' user type

For organizations on our usage-based pricing model, your users' user type is a billing factor.

Whether you're currently on our usage-based pricing model, or plan to soon switch to that pricing model, it may make sense to edit your users' user type before doing the user migration. One reason for that is that the original Users and roles UI allows you to see the time of your users' last use of New Relic (the new UI does not yet have this), and that can be useful for determining which user type to make them. For tips on how to do this, see Edit user type.

Recommended for large organizations: Understand user management concepts

If you need to control your users' access to specific accounts and/or specific roles (as opposed to just granting all your users access to everything), you'll need to learn some basics about the new user management concepts, which are quite different from the old concepts. Your users' existing roles and permissions won't be carried over to their new user records, so part of the user migration process will require you to set up those permissions using what we call "access grants."

Here are some of the most important concepts about how the new user model works:

  • Users are in a container called an "authentication domain". This domain governs how users are added to New Relic: manually (from the UI) or automatically (via SCIM). It also governs how users log in: manually (with email/password) or using SAML SSO. Most organizations will have just one or two authentication domains: one for the default manual settings and another for the more automatic methods.
  • Users can be assigned to one or more groups (for example, our default Admin group or a custom group like Contractors). For large organizations, users are often assigned to multiple groups.
  • When you want to give a user group access to a specific role and a specific account, you must create an access grant. For example, you may give a Contractors group access to our default All product admin role on one or more of your accounts, or give that group a custom role.

To learn more:

Step 0: Find and start the migration wizard

Before you start, be sure you've read the requirements and the other recommendations above. To start using the wizard:

  1. From one.newrelic.com, click Apps in the top navigation.
  2. In the table of apps, click the User migration walkthrough app.
  3. If you want more help and context, see the sections below for tips about specific migration wizard pages. If you find something in this doc confusing, please send us feedback using the Create issue button on this page.

Step 1: Create admins

On this page, you'll select the admins you want to migrate. This step will create user records on the new model for the chosen admins and assign them to the Admin group. Once done, the chosen admins will have a new user record available upon logging in to New Relic (see image below), and will have access to both the old and new user records until the migration wizard process is completed. The admins you choose here will have the ability to use the migration wizard from their new user record: this may be helpful if you want to choose other team members to finish the migration for you.

Note that you can always add more admins, or remove and edit existing admins, after you complete the migration process. This may be a reason to bring over many or all your admins now and adjust settings later.

Here are some tips about using the Add admins page:

  • You should ensure you understand the accounts that the migration is being done for. The user migration will only apply to the parent account selected (visible in the Accounts included dropdown) and its children accounts (visible using the View all associated accounts button). If you don't see all accounts you expect, it may be because your organization has multiple parent/child account structures, and that would mean you'd have to do the migration process more than once.

  • If you plan on migrating only a portion of your users to the new user model to start, we recommend leaving some original user model admins so that you have an admin to manage your original user model users.

    If a user on the new model has been created and the migration process hasn't been completed, they may have access to both the original user record and the new user records.

Step 2: Set up organization

You may choose a) a guided setup that allows more configuration options, or b) an automatic setup with fewer steps. Some tips on choosing this:

  • If you're not using SAML SSO or SCIM for the users you're migrating, and are okay giving all of your migrated users access to all accounts, we recommend using the automatic setup option. (Note that you can always do more partitioning of user access to accounts later.)
  • Regarding SCIM provisioning: If you're planning in the near future to manage your New Relic users via SCIM provisioning, you should consider waiting to migrate them so that you can migrate them with SCIM enabled. This is because once users are migrated, they reside in a specific authentication domain and the domain can't toggle between SCIM and non-SCIM (Manual) once users are added to that domain.

Step 3: Name your organization

Name your organization something descriptive and easily recognizable.

Step 4: Authentication domain settings

This section controls how users are provisioned (added to New Relic) and how they authenticate (log in). Note that choosing SAML SSO or SCIM setup will require you to leave the migration wizard and configure things elsewhere in the New Relic UI and in your identity provider and then return to the wizard.

Here's more detail about the two authentication domain sections:

Managing users (manual vs. identity provider)

For how users are added and managed, you can select Manually or Identity provider (SCIM). The option to use your identity provider to provision users via SCIM is available only if your organization has Pro or Enterprise edition.

If you choose Identity provider, you must follow the steps for automated user management, but skip steps related to setting up access grants, which you'll do later in this process. Once you complete the automated user management steps, return to the migration wizard and these docs.

Once you complete this step, we highly recommend completing the user migration process as quickly as you can. After completing this step, and until you finish the wizard procedure, your users will have two user records associated with the same login (see login screenshot from Step 1) or else may be missing assets they expect to see (like dashboards).

Some tips for syncing your identity provider with New Relic and setting up access grants:

  • If you're already using a New Relic app for either Okta, Azure, or OneLogin, you're likely using an out-of-date version. The out-of-date app is titled "New Relic by account" while the newer, required app is titled "New Relic by organization."
  • Once you complete those steps, new user records are created on the new user model and synced in New Relic based on your identity provider configuration. After you complete provisioning users, confirm that you see those user records in the new User management UI.
  • To access the new New Relic user management UI, you must be logged in via your new user record: this may require logging out, logging back in, and verifying your email to see all the logins associated with your email.

Login methods (manual vs. SSO)

The login method gives you a choice for how those users log in. You can select either a) email/password login or b) single sign on (SSO). Note that SSO is available only for organizations with Pro or Enterprise edition.

If you're using SSO but not SCIM, you must complete additional steps to set up SSO. (If you've already followed the SCIM procedures in the previous step, you should have already set up SAML SSO.)

Some tips for setting up SAML SSO:

  • If you're already using a New Relic app for either Okta, Azure, or OneLogin, you're likely using an out-of-date version. The out-of-date app is titled "New Relic by account" while the newer, required app is titled "New Relic by organization."
  • To access the new New Relic user management UI, you'll have to ensure you're logged in via your new user record. This may require logging out, logging back in, and verifying your email to see all logins associated with that email.
  • You can complete the procedure for setting up SSO, and then come back to the migration wizard to continue the migration process.
  • If you select more than one authentication method, note that you'll need to add a new authentication domain.

Step 5: Import existing users

There are two methods for adding and managing your New Relic users. Select the method you'll be using for instructions and tips:

Step 6: Access settings

This step is about setting what roles and what accounts your user groups have access to. Your users' existing roles and permissions won't be retained. This means that if you need to set up your users to have access to specific accounts or specific roles, then you'll likely want to configure their groups and access grants at this stage.

callout.For SCIM users

SCIM provisioning note: If you're using SCIM to import users and groups from your identity provider, you won't be able to edit roles and permissions in New Relic. All user and group changes are handled from your identity provider service.

You'll need to create an access grant for each account and role that you want a user group to have access to. Resources to help you understand access grants:

Step 7: Migrate user assets

When this step is completed, the personal assets of your users are migrated to the new user records and the original user records are deleted. For users currently logged in to New Relic, once you complete this step, their current New Relic session won't be interrupted until they log out or until their current browser session expires.

User assets that are migrated include:

If a user has access to several organizations that use New Relic (for example, if that user is a contractor), their original user model record won't be fully deleted until all those organizations migrate their users. Such a user will have both an original user record and one or more new user records, and if that's the case, that is displayed upon login (see the login screenshot in Page 1 section).

Step 8: Review and finish

If you're migrating users in segments and not all at once, you can go through the migration workflow several times with different groups of users. You can only click Finish Setup when all users in the organization are migrated.


Some common problems after migration:

  • If you have admin-level roles assigned but get an error message when trying to access New Relic platform features, it may be because you've been assigned organization-scoped roles (Organization manager and/or Authentication domain manager) but not any account-scoped roles. To access New Relic features in a specific account, you'll need at least one account-scoped role (for example, All product admin or a custom role).
  • If you've completed the migration, or are partway through the migration, and still see the original user management UI (the UI accessed through the Account settings tab), this may be because you are still logged in to your original user model record. Some remedies for this:
    • Log out of New Relic and log back in, selecting the Verify email option. When you've verified your email, choose the login option that says "Organization" and not the one that says "Original New Relic account."
    • If you're still having problems, clear your browser cache and attempt logging in again.

After you're done

Once your users are migrated to the new user model, you can find and manage them by clicking the account dropdown, clicking Administration, and using these UI pages:

  • User management: use this to view and add users, change their type (basic versus full), change their group, and approve user upgrade requests.
  • Access management: use this to create access grants (granting groups access to roles and accounts), and configure authentication domains (SAML SSO settings and SCIM settings, and more).

For some tips for planning out access grants, see Tips on access grants.

For more about these tools and concepts, see the user management docs.

Copyright © 2022 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.