• EnglishEspañol日本語한국어Português
  • Log inStart now

Migrate your users to our newer user model

Almost all New Relic users are on our newer user model, which was introduced in July of 2020. This tutorial is for New Relic customers who still have users on our original user model to migrate them to our new user model.


In July of 2020, we released a new, improved 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).

Recommended: review users' user type for billing purposes

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

Some things to consider:

  • Whether you're now on our usage-based pricing model, or plan to soon switch to that model, it may make sense to review and edit your users' user type before migrating your users. One reason for this: our original Users and roles UI lets you see when your users' last use of New Relic was, while the new UI doesn't yet have this, and that original UI can be useful for helping decide which user type to choose. For tips on this, see Edit user type.
  • For our usage-based pricing model, billable users are billable immediately upon being added, no matter if they've ever logged into New Relic before or not. This means that users with Pending invite tags in the UI are still billable if they have a billable user type. For more on this, see Billable users.

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 user groups with the necessary access to roles and accounts.

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 add that to a new or existing group. 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. Go to one.newrelic.com > All capabilities > Apps.
  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 that's done, those 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. Any admin you migrate at this stage can help you complete the migration wizard: that's one benefit to having the admins migrated first. For any user to access the migration wizard after this step is completed, they must sign in with their new user record: this may require signing out of New Relic and re-accessing the log-in screen so that you can see all the log-in options.

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 managed (how they're added to New Relic and updated) and how they authenticate (log in). Important notes about this page:

  • Choosing the SCIM option ("Manage by identity provider") or the SAML SSO option will require you to leave the migration wizard and configure things elsewhere in the New Relic UI and in your identity provider, followed by finishing things in the wizard.
  • If you're using SCIM, be sure to push your groups and users from your identity provider and configure access before the last step of this user migration process where you migrate user assets. This will ensure your users' assets are migrated to the SCIM provisioned user records and that those users have access when logging in.
  • Once you set how an authentication domain is managed (by identity provider or manually), that cannot be changed and adjusting that setting would require creating a new authentication domain and adding new user records. If it's possible you may soon change how your users are managed, that may be a reason to wait to migrate your user records.

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 creating groups, 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 group access:

  • 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 group access at this stage.


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

For each account and role that you want a user group to have access to, you'll have to add that to a new or existing group. Resources to help you understand group access:

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 administration settings (Organization settings and/or Authentication domain settings) but not any roles. To access New Relic features in a specific account, you'll need at least one 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.
  • If you have multiple accounts to choose from when logging in, this could be caused by the following:
    • If a user has been created for you on the new model, but the migration process hasn't been completed, you may have access to both your original user and your new user.
    • If you belonged to multiple organizations, it's possible to see a combination of old logins for unmigrated organizations along with the new user login.
    • Your email address may have multiple user records because you belong to multiple organizations or multiple authentication domains within the same organization.

After you're done

Once your users are migrated to the new user model, you can find and manage them by clicking the user menu, 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 and edit group access, and configure authentication domains (SAML SSO settings and SCIM settings, and more).

For some tips for planning out your group access, see Tips on user management concepts.

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

Copyright © 2024 New Relic Inc.

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