Automated user management: SCIM API

To set up the provisioning and management of your New Relic users from an identity provider, we provide a SCIM API for the identity providers that don't already have New Relic-specific apps and implementations.

Who should use the SCIM API?

If you have an identity provider that has a New Relic app (Azure AD, Okta, and OneLogin), see the guides for those. The SCIM API is meant for organizations that either aren't using those identity providers, or that want to use the SCIM API for additional configuration not available with the apps (for example, managing user type). Additional restrictions:

Ping Identity's PingOne is not supported because it doesn't allow provisioning of groups.

Before using our SCIM API, you should first set up an authentication domain with SCIM enabled. The authentication domain UI will give you values that you can use to integrate with your identity provider.

Note that after you set up an integration with the SCIM API, there are next steps to do, including downgrading some users to basic users, and granting user groups access to New Relic accounts.

Our SCIM API tutorial

This doc contains technical information about our SCIM API. For detailed instructions on using it, see the SCIM API tutorial.

SCIM service provider

Our SCIM service provider follows the SCIM 2.0 API as described in RFCs 7643 and 7644. You do not need to implement all aspects of the SCIM 2.0 specification to integrate your user information with New Relic. In fact, the New Relic service provider itself does not implement all aspects of the specification. This document describes the features from the specification available for an integration with New Relic.

Authentication

Authentication requires a bearer token. This bearer token is specific to your New Relic authentication domain and is displayed when first enabling SCIM for an authentication domain.

Supported resources

The New Relic service provider supports the following SCIM resources: Group , User , Service provider config , Resource type and Schema. Bulk and Search are not supported. For more information on how the RFC describes the resource endpoints, see RFC 7644 SCIM Protocol Specification.

Schemas

New Relic uses a subset of the available fields in the SCIM core schema. Other SCIM fields are ignored if they are included in incoming requests. The fields used by New Relic are:

Group:

SCIM field name	Description
`displayName`	Required. Name of the group.
`members`	List of users in the group.

User:

SCIM Field Name	Description
`externalId`	Unique identifier for the user used by your system.
`userName`	Required. Unique identifier for the user within New Relic’s system. Use the user’s email address.
`name.familyName`	Last name of the user.
`name.givenName`	First name of the user.
`emails` or `emails.value`	Required. Email address of the user.
`timezone`	Time zone of the user in IANA Time Zone database format, also known as the "Olson" time zone database format (for exmaple, "America/Los_Angeles").
`active`	Required. Boolean indicating whether or not the user should be active or inactive within New Relic.
`groups`	List of groups to which the user belongs.

New Relic user type (basic, core, or full) schema

This is an optional schema extension for New Relic-specific user attributes. Currently this provides control only over a user's user type. For a tutorial showing how to use this, see the SCIM API tutorial.

urn:ietf:params:scim:schemas:extension:newrelic:2.0:User:

SCIM field name	Description
`nrUserType`	The user type: `full user`, `core user`, or `basic user`.

Supported actions

SCIM provides several options for manipulating groups and users. The New Relic service provider supports the following options.

When configuring, be aware that:

Only simple filtering is supported. The eq operator may be used with a basic filter expression. For example, “displayName eq "Example Group 1”. Other operators are not supported.
PUT updates do not require that all fields be included. Fields that are not included will not be changed. When doing a PUT, if a required field already has the appropriate value, it is not necessary to include the field.

Supported actions are:

Example request:

POST /Groups

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "displayName": "Example Group 1",
  "members": []
}

Example response:

201 Created

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "id": "d0652232-b14f-434d-9c6f-36de7e1ab010",
  "displayName": "Example Group 1",
  "meta": {
    "resourceType": "Group",
    "created": "2019-11-08T21:33:13.055Z",
    "lastModified": "2019-11-08T21:33:13.055Z"
  },
  "members": []
}

Example request:

GET /Groups/YOUR_GROUP_ID

Example response:

200 OK

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "id": "d0652232-b14f-434d-9c6f-36de7e1ab010",
  "displayName": "Example Group 1",
  "meta": {
    "resourceType": "Group",
    "created": "2019-11-08T21:33:13.055Z",
    "lastModified": "2019-11-08T21:33:13.055Z"
  },
  "members": []
}

Example request:

GET /Groups?filter=displayName eq "Example Group 1"

Example response:

200 OK

{
  "totalResults": 1,
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "Resources": [{
    "schemas": [
      "urn:ietf:params:scim:schemas:core:2.0:Group"
    ],
    "id": "d0652232-b14f-434d-9c6f-36de7e1ab010",
    "displayName": "Example Group 1",
    "meta": {
      "resourceType": "Group",
      "created": "2019-11-08T21:33:13.055Z",
      "lastModified": "2019-11-08T21:33:13.055Z"
    },
    "members": []
  }]
}

In the request, include the fields that you want to change. If you include the members field, the group’s users will be adjusted to match the contents of the members field. Example request:

PUT /Groups/YOUR_GROUP_ID

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "displayName": "Example Group 1a"
}

Example response:

200 OK

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "id": "d0652232-b14f-434d-9c6f-36de7e1ab010",
  "displayName": "Example Group 1a",
  "meta": {
    "resourceType": "Group",
    "created": "2019-11-08T21:33:13.055Z",
    "lastModified": "2019-11-08T22:47:14.019Z"
  },
  "members": []
}

Example request:

PATCH /Groups/YOUR_GROUP_ID

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [{
    "op": "Replace",
    "path": "displayName",
    "value": "Example Group 1b"
  }]
}

Example response:

204 No Content

Example request:

PATCH /Groups/YOUR_GROUP_ID

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [{
    "op": "Add",
    "path": "members",
    "value": [{
      "value": "f0cbc276-16c9-4d1a-abc0-1856b0c74224"
    }]
  }]
}

Example response:

204 No Content

Example request:

PATCH /Groups/YOUR_GROUP_ID

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [{
    "op": "Remove",
    "path": "members",
    "value": [{
      "value": "f0cbc276-16c9-4d1a-abc0-1856b0c74224"
    }]
  }]
}

Example response:

204 No Content

Example request:

POST /Users

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "externalId": "external-id-1",
  "userName": "example-user-1@example.com",
  "name": {
    "familyName": "User 1",
    "givenName": "Example"
  },
  "emails": [{
    "value": "example-user-1@example.com",
    "primary": true
  }],
  "timezone": "America/Los_Angeles",
  "active": true,
  "groups": []
}

Example response:

201 Created

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "f0cbc276-16c9-4d1a-abc0-1856b0c74224",
  "externalId": "external-id-1",
  "userName": "example-user-1@example.com",
  "name": {
    "familyName": "User 1",
    "givenName": "Example"
  },
  "emails": [{
    "value": "example-user-1@example.com",
    "primary": true
  }],
  "timezone": "America/Los_Angeles",
  "active": true,
  "meta": {
    "resourceType": "User",
    "created": "2019-11-08T22:07:12.477Z",
    "lastModified": "2019-11-08T22:07:12.477Z"
  },
  "groups": []
}

Example request:

GET /Users/YOUR_USER_ID

Example response:

200 OK

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "f0cbc276-16c9-4d1a-abc0-1856b0c74224",
  "externalId": "external-id-1",
  "userName": "example-user-1@example.com",
  "name": {
    "familyName": "User 1",
    "givenName": "Example"
  },
  "emails": [{
    "value": "example-user-1@example.com",
    "primary": true
  }],
  "timezone": "America/Los_Angeles",
  "active": true,
  "meta": {
    "resourceType": "User",
    "created": "2019-11-08T22:07:12.477Z",
    "lastModified": "2019-11-08T22:07:12.477Z"
  },
  "groups": []
}

Example request:

GET /Users?filter=externalId eq "external-id-1"

Example response:

200 OK

{
  "totalResults": 1,
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "Resources": [{
    "schemas": [
      "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "id": "f0cbc276-16c9-4d1a-abc0-1856b0c74224",
    "externalId": "external-id-1",
    "userName": "example-user-1@example.com",
    "name": {
      "familyName": "User 1",
      "givenName": "Example"
    },
    "emails": [{
      "value": "example-user-1@example.com",
      "primary": true
    }],
    "timezone": "America/Los_Angeles",
    "active": true,
    "meta": {
      "resourceType": "User",
      "created": "2019-11-08T22:07:12.477Z",
      "lastModified": "2019-11-08T22:07:12.477Z"
    },
    "groups": []
  }]
}

In the request, include the fields that you want to change. If you include the groups field, the user’s groups will be adjusted to match the contents of the groups field. Example request:

PUT /Users/YOUR_USER_ID

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "name": {
    "familyName": "User 1A",
    "givenName": "Example"
  }
}

Example response:

200 OK

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "f0cbc276-16c9-4d1a-abc0-1856b0c74224",
  "externalId": "external-id-1",
  "userName": "example-user-1@example.com",
  "name": {
    "familyName": "User 1A",
    "givenName": "Example"
  },
  "emails": [{
    "value": "example-user-1@example.com",
    "primary": true
  }],
  "timezone": "America/Los_Angeles",
  "active": true,
  "meta": {
    "resourceType": "User",
    "created": "2019-11-08T22:07:12.477Z",
    "lastModified": "2019-11-08T22:28:33.552Z"
  },
  "groups": []
}

Example request:

PATCH /Users/YOUR_USER_ID

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [{
    "op": "Replace",
    "path": "active",
    "value": "false"
  }]
}

Example response:

204 No Content

Deviations from the RFC

This section describes areas where the New Relic SCIM service provider deviates from the SCIM protocol RFC 7644. Section numbers refer to RFC section numbers.

Items in this section could change as we work to bring our service provider into full compliance with the RFC.

RFC section name	RFC section number	Deviation description
Creating Resources	3.3.	The `meta.location` field is not set.
Filtering	3.4.2.2.	The only currently supported operator is `eq`. Field names are case sensitive. String attributes are compared in a case sensitive manner. Prefixing the field name with the schema is not supported. For example, `filter=urn:ietf:params:scim:schemas:core:2.0:User:userName eq "johnsmith"` will not work.
`/Me` Authenticated Subject Alias	3.11.	`GET` with the `/Me` resource returns a `404 Not Found`.
Service Provider Configuration Endpoints	4.	The service provider feature discovery endpoints do not support filtering.
Bearer Token and Cookie Considerations	7.4.	Bearer tokens do not have a set expiration date.

Next steps when you're done

Next steps:

Adjust your users' user type

When your users are provisioned in New Relic, you can 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.
Use the SCIM API to manage user type.

Assign group access

Once your users are in New Relic, you need to grant them access to specific New Relic accounts, specific groups, and specific roles. Without doing this, your users have no access to New Relic accounts. To learn how to do this, see:

Set up SAML SSO

If you want to set up SAML SSO, which most SCIM users do, see the SAML SSO docs.

Who should use the SCIM API?

Our SCIM API tutorial

SCIM service provider

Authentication

Supported resources

Schemas

New Relic user type (basic, core, or full) schema

Supported actions

Create group

Get group

Get group by query

Update group with PUT

Update group with PATCH (Non-member fields)

Update group with PATCH (Add members)

Update group with PATCH (Remove members)

Delete group

Create user

Get user

Get user by query

Update user with PUT

Update user with PATCH

Delete user

Deviations from the RFC

Next steps when you're done

Adjust your users' user type

Assign group access

Set up SAML SSO

Automated user management: SCIM API

Who should use the SCIM API? .css-21sua1{background:none;border:none;width:0;padding:0;}

Our SCIM API tutorial

SCIM service provider

Authentication

Supported resources

Schemas

New Relic user type (basic, core, or full) schema

Supported actions

Get group

Get group by query

Update group with PUT

Update group with PATCH (Non-member fields)

Update group with PATCH (Add members)

Update group with PATCH (Remove members)

Delete group

Create user

Get user

Get user by query

Update user with PUT

Update user with PATCH

Delete user

Deviations from the RFC

Next steps when you're done

Adjust your users' user type

Assign group access

Set up SAML SSO

Who should use the SCIM API?