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

Before using this tutorial, we recommend you read:

Other related resources:

Some SCIM 2.0 RFC documents from the Internet Engineering Task Force that are most relevant: RFC 7643 - SCIM Core Resources and Extensions, RFC 7643 - JSON Representation, and RFC 7644 - SCIM Protocol.

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:

bash

$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:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "detail": "invalid authentication token",
  "status": "401"
}

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.

bash

$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

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "5a1d580f-323c-450c-8c62-479b5c9085d6",
  "externalId": null,
  "userName": "bjensen@example.com",
  "name": {
    "familyName": "Jensen",
    "givenName": "Barbara"
  },
  "emails": [
    {
      "value": "bjensen@example.com",
      "primary": true
    }
  ],
  "timezone": "America/Los_Angeles",
  "active": true,
  "meta": {
    "resourceType": "User",
    "created": "2021-07-20T21:32:58.167Z",
    "lastModified": "2021-07-20T21:32:58.167Z"
  },
  "groups": []
}

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.

bash

$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

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "id": "df2b9a04-0426-4a3e-bf5f-54d5341f4e5b",
  "displayName": "Example Group",
  "meta": {
    "resourceType": "Group",
    "created": "2021-07-20T22:41:50.414Z",
    "lastModified": "2021-07-20T22:41:50.414Z"
  },
  "members": []
}

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.

bash

$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:

{
  "totalResults": 1,
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "Resources": [
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
      "id": "5a1d580f-323c-450c-8c62-479b5c9085d6",
      "externalId": null,
      "userName": "bjensen@example.com",
      "name": {
        "familyName": "Jensen",
        "givenName": "Barbara"
      },
      "emails": [
        {
          "value": "bjensen@example.com",
          "primary": true
        }
      ],
      "timezone": "America/Los_Angeles",
      "active": true,
      "meta": {
        "resourceType": "User",
        "created": "2021-07-20T21:32:58.167Z",
        "lastModified": "2021-07-20T21:32:58.167Z"
      },
      "groups": []
    }
  ]
}

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

bash

$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:

{
  "totalResults": 1,
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "Resources": [
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
      "id": "df2b9a04-0426-4a3e-bf5f-54d5341f4e5b",
      "displayName": "Example Group",
      "meta": {
        "resourceType": "Group",
        "created": "2021-07-20T22:41:50.414Z",
        "lastModified": "2021-07-20T22:41:50.414Z"
      },
      "members": []
    }
  ]
}

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.

bash

$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

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "5a1d580f-323c-450c-8c62-479b5c9085d6",
  "externalId": null,
  "userName": "bjensen@example.com",
  "name": {
    "familyName": "Jensen",
    "givenName": "Barbara"
  },
  "emails": [
    {
      "value": "bjensen@example.com",
      "primary": true
    }
  ],
  "timezone": "America/Chicago",
  "active": true,
  "meta": {
    "resourceType": "User",
    "created": "2021-07-20T21:32:58.167Z",
    "lastModified": "2021-07-21T02:12:05.348Z"
  },
  "groups": []
}

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.

bash

$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:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "id": "df2b9a04-0426-4a3e-bf5f-54d5341f4e5b",
  "displayName": "Example Group",
  "meta": {
    "resourceType": "Group",
    "created": "2021-07-20T22:41:50.414Z",
    "lastModified": "2021-07-20T22:41:50.414Z"
  },
  "members": [
    {
      "type": "User",
      "value": "5a1d580f-323c-450c-8c62-479b5c9085d6"
    }
  ]
}

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

bash

$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:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "id": "df2b9a04-0426-4a3e-bf5f-54d5341f4e5b",
  "displayName": "Example Group",
  "meta": {
    "resourceType": "Group",
    "created": "2021-07-20T22:41:50.414Z",
    "lastModified": "2021-07-20T22:41:50.414Z"
  },
  "members": []
}

Delete users and groups

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

bash

$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}.

bash

$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:

Your New Relic users will by default start out as basic users and you have the option to upgrade them. For more information, see Manage user type.
Set up SAML SSO.
Once your user groups are in New Relic, you'll need to assign them specific roles and specific accounts. Learn more about how user access works.

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:

bash

$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

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:newrelic:2.0:User"
  ],
  "id": "8ab6c464-983c-4bb4-9507-720f28763a43",
  "externalId": null,
  "userName": "jbenson@example.com",
  "name": {
    "familyName": "Benson",
    "givenName": "James"
  },
  "emails": [
    {
      "value": "jbenson@example.com",
      "primary": true
    }
  ],
  "timezone": "America/Chicago",
  "active": true,
  "meta": {
    "resourceType": "User",
    "created": "2021-07-21T19:53:33.470Z",
    "lastModified": "2021-07-21T19:53:33.470Z"
  },
  "groups": [],
  "urn:ietf:params:scim:schemas:extension:newrelic:2.0:User": {
    "nrUserType": "Basic User"
  }
}

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

bash

$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

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:newrelic:2.0:User"
  ],
  "id": "8ab6c464-983c-4bb4-9507-720f28763a43",
  "externalId": null,
  "userName": "jbenson@example.com",
  "name": {
    "familyName": "Benson",
    "givenName": "James"
  },
  "emails": [
    {
      "value": "jbenson@example.com",
      "primary": true
    }
  ],
  "timezone": "America/Chicago",
  "active": true,
  "meta": {
    "resourceType": "User",
    "created": "2021-07-21T19:53:33.470Z",
    "lastModified": "2021-07-21T20:15:56.718Z"
  },
  "groups": [],
  "urn:ietf:params:scim:schemas:extension:newrelic:2.0:User": {
    "nrUserType": "Full User"
  }
}

Requirements

Overview

Configure your authentication domain for SCIM

Tip

Create users and user groups in your system

Connect to the SCIM API

401 Unauthorized

Create users in your authentication domain

Important

Example responses

201 Created

400 Bad Request

409 Conflict

Create groups in your authentication domain

Important

Example responses

201 Created

400 Bad Request

409 Conflict

View users and groups in your authentication domain

200 OK

200 OK

Update a user's attributes

Example responses

200 OK

409 Conflict

Update a group's members

200 OK

200 OK

Delete users and groups

Next steps

Optional: Manage user type

Example responses

200 OK

409 Conflict

400 Bad Request

Example responses

200 OK

400 Bad Request

SCIM API tutorial

Requirements .css-21sua1{background:none;border:none;width:0;padding:0;}

Overview

Configure your authentication domain for SCIM

Tip

Create users and user groups in your system

Connect to the SCIM API

401 Unauthorized

Create users in your authentication domain

Important

Example responses

201 Created

400 Bad Request

409 Conflict

Create groups in your authentication domain

Important

Example responses

201 Created

400 Bad Request

409 Conflict

View users and groups in your authentication domain

200 OK

200 OK

Update a user's attributes

Example responses

200 OK

409 Conflict

Update a group's members

200 OK

200 OK

Delete users and groups

Next steps

Optional: Manage user type

Example responses

200 OK

409 Conflict

400 Bad Request

Example responses

200 OK

400 Bad Request

Requirements