Relic Solutions: Tips and Tricks for a Successful Migration

Howdy y’all and welcome! My name is Pete and I’m here to share some helpful tips and tricks to make your organization’s migration from our Legacy User Model to our New Relic One User Model a more seamless experience for both you and your users. Internally we use the terms version1 (v1) and version2 (v2) to describe these user models so I’m going to continue that tradition in this post - consider yourself an insider :slight_smile: Also, if you’re planning on using SSO/SAML and/or SCIM, please read all the way to the bottom – I promise it will be worth your while.

First, what does the migration wizard actually do?

  1. Transfers user assets (API keys, timezone preferences, favorites, passwords, dashboards etc.) from your v1 user record to your newly provisioned v2 user record

  2. Removes your v1 user record after the successful migration of assets

Some important things worth mentioning:

  • The v1 account owner of the top level account from your organization must kick off the migration. For most of you this means the owner of the parent account. For some of our larger enterprise customers, this means the owner of the Partnership Owner Account

  • When the v1 owner kicks off the migration, this creates a v2 user record for that user along with any other Admins the owner selects. These folks now belong to the Admin Group in the Default Authentication Domain

A Group is a collection of users that you intend will all have the same permissions across your accounts and/or organization. These permissions are configured using Access Grants, which are essentially a role + account (Read-only for Account 12345). Groups can and will usually have many access grants if you have many accounts in your organization.

Authentication Domains are your mechanism to govern a group of Groups by configuring:

  1. User Provisioning - are you going to be manually creating your users or are you going to use SCIM?

  2. Authentication - are your users going to be authenticating using email/password or SSO/SAML?

  3. User type governance - do you want your users to be able to self upgrade to be Core or Full or would you like your Admins to review these requests?

Important notes about Authentication Domains

  • User records are tied to auth domains. What this means is that if you add a person to multiple auth domains, each of those instances will be their own distinct user record. For this reason it’s possible to have a user with the same email address but with multiple user records, each having their own assets and Role Based Access Controls.

  • As I’m writing this, there is no way to delete an Authentication Domain. Please be mindful of this and don’t go wild when creating test auth domains. Most of you will need one or two auth domains maximum – one for email/password authentication and manual user provisioning, and possibly one for manual/SCIM provisioning and SSO/SAML authentication. If you end up creating an auth domain you won’t be using, please rename it something obvious like “TEST DO NOT USE”. The ability to delete auth domains is coming soon I promise.

  • You currently can not move users and or their assets between auth domains – this is so incredibly important so please ensure you are creating your users in the auth domain you intend to use. The ability to move users and their assets between auth domains is also coming soon, I swear on my dog Nala (love you baby girl).

  • You currently can not adjust how you provision users in your auth domain (you can’t switch from manual provisioning to SCIM). Some folks end up adding all of their users to the Default auth domain which uses manual provisioning of users and email/password for authentication. Awesome, but if you’re planning on using SSO and or SCIM, please don’t do that and keep reading :panda_face:

Remember before when I said the migration wizard transfers assets from your v1 user record to your v2 user record? If you add all of your users to the default authentication domain, all of your users will be governed by that configuration (manual provisioning and email/password authentication). If you run the migration wizard in this state, all of your users’ assets will be transferred to user records that use email/password and you’ll need to manage them manually. If you’re planning on using SSO and or SCIM please keep reading

Since users and their assets can not be moved between authentication domains, please ensure you have created a new SSO and/or SCIM auth domain, created groups, added users to those groups, and configured access grants to those groups before running the migration wizard.

Here’s what your flow may look like if you want to use manual provisioning and SSO:

  1. Have the v1 owner of the top level account in your organization kick off the migration. This creates a v2 user record for that person along with any admins they select

  2. Login as your newly provisioned v2 user record (you may need to create a password if you haven’t or don’t remember it for your v1 user). *Please note logging in via email/password won’t be the final state for you and your users - this is just so you can login as your v2 user and configure SSO for all the users in your organization including yourself.

  3. Configure a new auth domain which uses manual provisioning and SSO authentication

  4. Create groups and add users to those groups

  5. Configure access grants for those groups (All Product Admin for account 23456, Read-only for account 12345)

  6. Finish the migration and transfer your users’ assets to these manually provisioned, SSO/SAML authenticating users

Here’s what your flow may look like if you want to use SCIM and SSO

  1. Have the v1 owner of the top level account in your organization kick off the migration. This creates a v2 user record for that person along with any admins they select

  2. Login as your newly provisioned v2 user record (you may need to create a password if you haven’t or don’t remember it for your v1 user). *Please note logging in via email/password won’t be the final state for you and your users - this is just so you can login as your v2 user and configure SSO for all the users in your organization including yourself.

  3. Configure a new auth domain which uses SCIM provisioning and SSO authentication

  4. Create groups and add users to those groups within your Identity Provider and push those groups and users to New Relic

  5. Configure access grants for those groups (All Product Admin for account 23456, Read-only for account 12345)

  6. Finish the migration and transfer your users’ assets to these newly provisioned SCIM managed SSO/SAML authenticating users

Here are a few things I’ve seen recently which are worth mentioning:

When you kicked off the migration, we created a user record for you which lived in our pre-configured Admin Group in the Default auth domain which can do all the things, however, you’re going to be creating yourself a new user record in your new auth domain which does not have the same permissions.

Please ensure whatever new group you’re creating for yourself and your other admins in your SSO/SCIM auth domain has the necessary roles to carry out your administrative duties. These roles are: “Organization Manager” and “Authentication Domain Manager” - these are organizational scoped roles meaning they don’t allow you access or permissions in a specific account, but rather they allow you to manage users and configure their access. You’ll also want to add “Billing User” and “All Product Admin” to whatever account(s) you’re going to need to access. Please note that if you only configure organizational scoped roles and not account scoped roles, you’ll be able to login but see a blank page.

Please clean up your users before running the migration. If you finish the migration and you get a message that there are more users to migrate, this probably means that you have v1 users in your organization that don’t map to the v2 users you’ve created in your new auth domain.

Use the live metadata url from your Identity Provider if it’s available. For whatever reason, I’ve been on a few calls recently where we ran into issues with SAML certificates. Using the live metadata url seems to be less problematic, so please use this if you have it available. Also, please be sure to test that a few users can login using your new SAML configuration before finishing the migration.

Optional: Remove users from your default auth domain after testing your authentication and running the migration. This will ensure that you don’t have multiple user records and maintain a seamless auth experience for yourself and the other admins you provisioned in step one of the migration

That’s it. You did it. I mean it when I say it – I’m proud of you.

15 Likes

Can we share this with customers pretty much as is? Thx!

1 Like

Please do this is a public facing forum for that reason specifically

Hi ppodrid, great post, it helped me out a lot to understand the migration flow. What is the best way to get notified when the migrate users between auth domains feature is available? Thanks.