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

SCIM API tutorial

This tutorial will walk you through some common procedures for managing users via our SCIM API. The SCIM API allows you to view, create, update, and delete users and groups programmatically, outside of the User management UI.

Requirements

This tutorial applies to users on our newer user model and not our original user model.

Before using this tutorial, we recommend you read:

Other related resources:

Overview

This tutorial shows you how to accomplish some of the most common tasks needed for adding users to New Relic from an identity provider service and managing them from there. It is meant to supplement our primary SCIM API resource.

Note that using automated user management means that your groups of users are imported into New Relic. This means that you can't use our user management UI to add users to groups. The groups are created and managed from your identity provider side.

Once you're done with getting your user groups into New Relic, you must use our Access management UI to give those groups access to roles and accounts. For more information, see user management concepts.

Configure your authentication domain for SCIM

Before you can use the SCIM API, you must first enable SCIM for your authentication domain. Note that the API access token is displayed only once after you save the configuration, so save it somewhere safe for later user.

Tip

If you need to view a bearer token later, the only way to do this is to generate a new one, and that will invalidate the old one and any integrations using the old token.

Create users and user groups in your system

The SCIM API is typically used by scripts for importing users and groups into New Relic from a database or a third-party identity provider that doesn't have pre-configured configs for New Relic.

If you want to use the SCIM API custom application or for ad-hoc requests, proceed to learn how to connect to the SCIM API.

Connect to the SCIM API

The SCIM API is available at https://scim-provisioning.service.newrelic.com/scim/v2 and this URL is viewable in the authentication domain settings page. To access the SCIM API, your client must include a bearer token with each request. The token is displayed after saving your Authentication Domain configuration.

If you're using a third-party identity provider, configure it to use Bearer token authorization and plug in your API access token. Refer to your identity provider's documentation for help configuring this. Once configured, you're all set to import users and groups.

Rather than reading the entire SCIM protocol RFCs, there are three specific sections you may find valuable: See RFC 7643 - SCIM Core Resources and Extensions and RFC 7643 - JSON Representation for the specifics. Refer to RFC 7644 - SCIM Protocol for more information about the protocol used in this tutorial.

For all requests to the SCIM API, you must provide the bearer token in an Authorization header. Here's an example with curl:

curl -X 'GET' -H 'Accept: application/json' -H "Authorization: Bearer $TOKEN" 'https://scim-provisioning.service.newrelic.com/scim/v2/Users'

Any request in the rest of this tutorial will receive a 401 Unauthorized response if the API access token is missing or invalid.

Example response:

Create users in your authentication domain

You can use the SCIM API to send a POST request to /scim/v2/Users to create a user. The following user attributes are required:

  • userName This identifier must be unique within an authentication domain. Use the user's email address.
  • emails Same as userName. The email address of the user. (Despite it being called emails, for this procedure enter only one.)
  • active Boolean indicating whether or not the user should be active or inactive within New Relic.

We recommend providing the following attributes for the best user experience:

  • name.givenName The user's first or given name.
  • name.familyName The user's last or family name.
  • timezone The user's time zone in IANA Time Zone database format.
curl -X 'POST' -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" 'https://scim-provisioning.service.newrelic.com/scim/v2/Users' --data-binary @- <<EOF
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"userName": "bjensen@example.com",
"name": {
"familyName": "Jensen",
"givenName": "Barbara"
},
"emails": [
{
"primary": true,
"value": "bjensen@example.com"
}
],
"active": true,
"timezone": "America/Los_Angeles"
}
EOF

Important

Take note of the returned user id. To update a user in the future you'll need to supply the same ID with the request.

Example responses

Create groups in your authentication domain

You can use the SCIM API to send a POST request to /scim/v2/Groups to create a group. The only group attribute required is:

  • displayName The group name.
curl -X 'POST' -H 'Content-Type: application/json' -H "Authorization: Bearer $YOUR_TOKEN" 'https://scim-provisioning.service.newrelic.com/scim/v2/Groups' --data-binary @- <<EOF
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"displayName": "Example Group"
}
EOF

Important

Take note of the returned group id. To update a group or its members in the future you will need to supply the same ID with the request.

Example responses

View users and groups in your authentication domain

After you've created some users and groups you'll see them in the User management UI. You can also retrieve them from the SCIM API.

In this tutorial, you'll be searching for specific users and groups, but that's not the only way to view users and groups. Refer to the SCIM API reference and RFC 7644 for all the available query options.

To retrieve a user by email, send a GET request to /scim/v2/Users with a filter query parameter. The filter parameter must be URL encoded.

curl -X 'GET' -H 'Accept: application/json' -H "Authorization: Bearer $YOUR_TOKEN" 'https://scim-provisioning.service.newrelic.com/scim/v2/Users' --get --data-urlencode 'filter=userName eq "bjensen@example.com"'

Example response:

Similarly, send a GET request to /scim/v2/Groups with a filter query parameter to retrieve a group by name.

curl -X 'GET' -H 'Accept: application/json' -H "Authorization: Bearer $YOUR_TOKEN" 'https://scim-provisioning.service.newrelic.com/scim/v2/Groups' --get --data-urlencode 'filter=displayName eq "Example Group"'

Example response:

Update a user's attributes

The SCIM API supports both PUT and PATCH methods for updating users. Refer to the SCIM API supported actions and RFC 7644 for details on using PATCH. This tutorial demonstrates updating a user's attributes with the PUT method.

New Relic does not require all user attributes be included in the request body, only the attributes you want to update are necessary. Send a PUT request to /scim/v2/Users/${ID} to update the user.

curl -X 'PUT' -H 'Content-Type: application/json' -H "Authorization: Bearer $YOUR_TOKEN" 'https://scim-provisioning.service.newrelic.com/scim/v2/Users/5a1d580f-323c-450c-8c62-479b5c9085d6' --data-binary @- <<EOF
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"timezone": "America/Chicago"
}
EOF

Example responses

Update a group's members

The SCIM API supports both PUT and PATCH methods for updating groups. This tutorial will show how to update a group's members with the PATCH method. Refer to the SCIM API supported actions and RFC 7644 for details on using PUT.

PATCH is convenient for adding or removing group members without needing to specify the full member list in the request. To add a user to a group, use the following operation parameters:

  • op set to Add
  • path set to members
  • value set to a list of {"value": "${USER_ID}"} with each user ID to add to the group

Send a PATCH request to /scim/v2/Groups/${ID} to update group members.

curl -X 'PATCH' -H 'Content-Type: application/json' -H "Authorization: Bearer $YOUR_TOKEN" 'https://scim-provisioning.service.newrelic.com/scim/v2/Groups/df2b9a04-0426-4a3e-bf5f-54d5341f4e5b' --data-binary @- <<EOF
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [{
"op": "Add",
"path": "members",
"value": [{
"value": "5a1d580f-323c-450c-8c62-479b5c9085d6"
}]
}]
}
EOF

Example response:

To remove a user from a group, use the following operation parameters:

  • op set to Remove
  • path set to members
  • value set to a list of {"value": "${USER_ID}"} with each user ID to remove from the group
curl -X 'PATCH' -H 'Accept: application/json' -H "Authorization: Bearer $YOUR_TOKEN" 'https://scim-provisioning.service.newrelic.com/scim/v2/Groups/df2b9a04-0426-4a3e-bf5f-54d5341f4e5b' --data-binary @- <<EOF
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [{
"op": "Remove",
"path": "members",
"value": [{
"value": "5a1d580f-323c-450c-8c62-479b5c9085d6"
}]
}]
}
EOF

Example response:

Delete users and groups

To remove a user from an authentication domain, send a DELETE request to /scim/v2/Users/${ID}.

curl -X 'DELETE' -H 'Accept: application/json' -H "Authorization: Bearer $YOUR_TOKEN" 'https://scim-provisioning.service.newrelic.com/scim/v2/Users/d0f4d8e3-5413-4894-a8f9-de709994e18c'

Example response:

204 No Content

Similarly, to remove a group from your authentication domain, send a DELETE request to /scim/v2/Groups/${ID}.

curl -X 'DELETE' -H 'Accept: application/json' -H "Authorization: Bearer $YOUR_TOKEN" 'https://scim-provisioning.service.newrelic.com/scim/v2/Groups/df2b9a04-0426-4a3e-bf5f-54d5341f4e5b'

Example response:

204 No Content

Next steps

Once your integration is complete, potential next steps include:

Optional: Manage user type

Once your SCIM API integration is complete, all users brought into New Relic start out as basic users. You can use our default method for managing user type, which is using the User management UI. Optionally, you can use our SCIM API instead. To do this, you can set update your authentication domain configuration to Delegate control of user type to your identity provider or custom application.

The user's type attribute is defined in the custom schema urn:ietf:params:scim:schemas:extension:newrelic:2.0:User. Include this schema and the nrUserType string attribute in your create or update request to set a user's type.

Valid values for nrUserType include:

  • Full User
  • Core User
  • Basic User

To create a new Basic user send a POST request /scim/v2/Users and include the custom New Relic schema extension:

curl -X 'POST' -H 'Content-Type: application/json' -H "Authorization: Bearer $YOUR_TOKEN" 'https://scim-provisioning.service.newrelic.com/scim/v2/Users' --data-binary @- <<EOF
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:newrelic:2.0:User"
],
"userName": "jbenson@example.com",
"name": {
"givenName": "James",
"familyName": "Benson"
},
"emails": [{
"primary": true,
"value": "jbenson@example.com",
"type": "work"
}],
"active": true,
"timezone": "America/Chicago",
"urn:ietf:params:scim:schemas:extension:newrelic:2.0:User": {
"nrUserType": "Basic User"
}
}
EOF

Example responses

To update a user's type, send a PUT request scim/v2/Users/${ID} and include the custom New Relic schema extension:

curl -X 'PUT' -H 'Content-Type: application/json' -H "Authorization: Bearer $YOUR_TOKEN" 'https://scim-provisioning.service.newrelic.com/scim/v2/Users' --data-binary @- <<EOF
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:newrelic:2.0:User"
],
"urn:ietf:params:scim:schemas:extension:newrelic:2.0:User": {
"nrUserType": "Full User"
}
}
EOF

Example responses

Copyright © 2024 New Relic Inc.

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