Okta SCIM/SSO application configuration

Our automated user management allows you to import and configure your New Relic users and groups from your identity provider via SCIM. This guide provides Okta specific details on how to configure the New Relic Okta SCIM/SSO application.

Requirements

Before using this guide, read the automated user management requirements.

Note that these instructions require going back and forth between your identity provider and New Relic.

Step 1. Create authentication domain and enable SCIM

To get to the New Relic authentication domain UI: From one.newrelic.com, click the user menu, click Access management, and then click Authentication domains.

If you don't already have one, create a new authentication domain for your SCIM-provisioned users by clicking + Add new.

For that authentication domain, under Source of users, select SCIM. Copy and save the API token for later use. Note that this will be shown only once.

Step 2. Set up Okta's New Relic app

Next, set up Okta's New Relic SCIM/SSO application:

1. Go to okta.com/ and sign in with an account that has administrator permissions.
2. From the Okta home page, click on Admin.
3. From the Okta admin Dashboard, choose the Applications page.
4. Click Browse app catalog and search for "New Relic by organization" (not "New Relic by account") and choose that from the results.
5. From the New Relic by Organization page, click on Add.
6. From the Add New Relic by organization page, check the two Application visibility "Do not display..." checkboxes and click on Done. We will make the application visible later after configuration is complete and provisioning has begun.

Step 3. Configure provisioning

Configure Okta's New Relic SCIM/SSO application to automatically provision your users to New Relic:

1. From the app, click on the Provisioning tab.
2. From the Integration form, click on Configure API integration and check the Enable API integration checkbox.
3. Take the API token you saved in Step 1 and input it in the Okta New Relic app's API token field.
4. Optional: click on Test API credentials to verify a SCIM connection can be established to New Relic. If a connection can be established, a success message is displayed. If a connection was not established, re-enter the API Token and try the test again.
5. Click Save. Note that the save process does a test of the API credentials. If a connection is not established to New Relic, the save will fail.
6. On the newly displayed To App form, click on Edit.
7. Check the Enable checkbox in the Create users, Update user attributes, and Deactivate users sections.
8. Click Save.
9. Go to the Sign on tab. In the authentication domain field, input your authentication domain ID, which you'll find in our authentication domain UI.

Step 4. Assign users and groups

If you don't already have your user groups set up in Okta, you'll need to create them. These will be the groups that you'll later assign role and account access to in New Relic. To learn how to create groups, see Okta's documentation on groups.

Assignments tab

Next, you'll assign users. Assigning users is done using two different tabs in the app. We recommend having your New Relic users selected on the Assignments tab and their associated groups selected on the Push groups tab.

1. In the app, click on the Assignments tab.
2. From the Assignments form, click on Assign.
3. From the pop up menu, click on Assign to groups.
4. From the Assign ... to groups form, click on Assign for the group you wish to assign to the application.
5. Highly recommended: Configure the time zone for your users in Okta. That will determine how dates/times for your users are displayed in New Relic. If you don't set a time zone, we use UTC time for those users unless they've set their own time zone. Time zone is specified in IANA Time Zone database format, also known as the "Olson" time zone database format (for example, "America/Los_Angeles"). There are several ways in Okta to configure time zone settings, so consult the Okta docs if more detail is needed. Here's one way to do this in the Assignments tab:
   • In the Time zone field, enter the default time zone for members of the group.
6. Click on Save and go back.
7. Repeat the steps to add a group until all desired groups have been assigned to the application.
8. Click Done.

Push groups tab

1. In the app, click on the Push groups tab.
2. From the Push groups form, click on Push groups.
3. From the pop up menu, click on Find groups by name.
4. From the Push groups to... form, in the search field enter the first few characters of the name of the group you want to send to New Relic. Leave the Push group memberships immediately checkbox checked.
5. Click on your group in the pop up search results list.
6. In the Match result & push action section, No match found should be displayed, meaning that the group does not yet exist at New Relic. Leave the selector set to Create group and leave the default name for the group. The intent here is to have a group of the same name created at New Relic.
7. If this is the last group you wish to send to New Relic, click on Save. Otherwise, if you have more groups to configure, click on Save & add another and repeat the steps to add a group.

When you've added one or more groups, you should be able to see the users you've added by going to the User management UI page.

Step 5. Set your users' user type

When your users are provisioned in New Relic, you're able to see them in the User management UI.

If you're adding users to New Relic via SCIM but not managing their user type via SCIM, they start out as basic users. To upgrade users, you have two options:

• Use the User management UI to edit users.
• Manage user type from Okta (described below).

To manage your users' user type from Okta:

1. Go to the New Relic authentication domain UI and click Enable Manage user type with SCIM. Note that when this is enabled, you can’t manage user type from the New Relic UI and can only manage it from Okta.

2. Go into your Okta instance. The rest of these instructions are done from Okta.

3. Next, you'll configure Okta to be able to send a new attribute nrUserType. Steps:

   • Go to the Profile editor. In the Attributes section, click Add attribute.
   • Set your settings to match the screenshot below. The only two fields that must match exactly are External name (value: nrUserType) and External namespace (value: urn:ietf:params:scim:schemas:extension:newrelic:2.0:User). The variable value can be any value.
   

4. Next, you'll configure your Okta user profile to have this field. Steps:

   • In the Profile editor, go to Users and click the User (default) profile.
   • Add a new New Relic user type attribute to that profile (see Okta user profile instructions). How you set this will depend on your own setup and preferences for defining user type. Note that the expected values for user type are Basic User, Core User, and Full User. Below is an example with information filled in.

5. In the People section, define the user type for your users. How you do this will depend on your setup and preferences. For example, you may choose to set this manually by setting each user’s user type, or you may use Okta to manage these in bulk.

6. Next, you’ll set up mapping for that attribute. Steps:

   • In the app's Provisioning section, click Unmapped attributes.
   • Go into edit mode for the unmapped New Relic user type attribute.
   • Configure it based on how you want to set the user type. To learn about choosing user type, see User type. Learn more about Okta attribute mappings.

Step 6. Assign group access

Once these steps are completed, you're able to see your users in New Relic by going to the User management UI. Now that your users are present in New Relic, you must grant them access to specific roles on specific accounts. If this is not done, your users don't yet have access to New Relic. To learn how to do this, see:

• How user access works
• The user management tutorial

Step 7. Configure SAML SSO

To enable SAML SSO, see the SAML instructions.

Additional considerations

In this section we discuss other important things to know when using the New Relic SCIM/SSO application. This section includes tips to work around potential issues that could cause undesired results when integrating between Okta and New Relic.

Moving users between groups

When moving a user between groups, you must manually synchronize the old group's membership with New Relic. This is because Okta does not send a SCIM request to remove a user from a group. So, the admin needs to push the old group's membership to New Relic manually to inform New Relic that the user is no longer a member of the old group.

Here are the steps to manually synchronize a group's membership:

1. From the New Relic SCIM/SSO application page, click on the Push groups tab.
2. From the Push groups form, open the pick list on the desired group's button under the Push Status column.
3. From the displayed pick list on the button, click Push now. This causes an immediate synchronization of the group's membership with New Relic.