Skip to content

Latest commit

 

History

History
797 lines (653 loc) · 18.2 KB

scim-support-automated-user-management.mdx

File metadata and controls

797 lines (653 loc) · 18.2 KB
Raw
title tags metaDescription redirects
Automated user management: SCIM API
Accounts
Accounts and billing
Automated user management
New Relic has a SCIM service provider to easily manage the users in your New Relic account.
/docs/scim-support-automated-users
/docs/scim-support-automated-user-management

If you want to implement New Relic's automated user management (AUM) and import your users from an identity provider, first read Introduction to AUM to learn about supported identity providers and when you'd want to use our SCIM API, documented below.

Requirements

Before using our SCIM API, you must first enable SCIM for an authentication domain.

Note that after you enable SCIM, there are necessary next steps to do, including downgrading some users to basic users, and granting user groups access to New Relic accounts.

SCIM service provider [#scim-provider]

New Relic’s 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 is done using a bearer token. This bearer token is specific to your New Relic 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:

  <th>
    Description
  </th>
</tr>

  <td>
    **Required.** Name of the group.
  </td>
</tr>

<tr>
  <td>
    `members`
  </td>

  <td>
    List of users in the group.
  </td>
</tr>
SCIM Field Name
`displayName`

User:

  <th>
    Description
  </th>
</tr>

  <td>
    Unique identifier for the user used by your system.
  </td>
</tr>

<tr>
  <td>
    `userName`
  </td>

  <td>
    **Required.** Unique identifier for the user within New Relic’s system. Use the user’s email address.
  </td>
</tr>

<tr>
  <td>
    `name.familyName`
  </td>

  <td>
    Last name of the user.
  </td>
</tr>

<tr>
  <td>
    `name.givenName`
  </td>

  <td>
    First name of the user.
  </td>
</tr>

<tr>
  <td>
    `emails` or `emails.value`
  </td>

  <td>
    **Required.** Email address of the user.
  </td>
</tr>

<tr>
  <td>
    `timezone`
  </td>

  <td>
    Time zone of the user in IANA Time Zone database format, also known as the "Olson" time zone database format (e.g., "America/Los_Angeles").
  </td>
</tr>

<tr>
  <td>
    `active`
  </td>

  <td>
    **Required.** Boolean indicating whether or not the user should be active or inactive within New Relic.
  </td>
</tr>

<tr>
  <td>
    `members`
  </td>

  <td>
    List of groups to which the user belongs.
  </td>
</tr>
SCIM Field Name
`externalId`

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": []
}
```

<Collapser id="get-group" title="Get group"

Example request:

```
GET /Groups/<var>YOUR_GROUP_ID</var>
```

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": []
}
```

<Collapser id="get-group-query" title="Get group by query"

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": []
  }]
}
```

<Collapser id="update-group-put" title="Update group with PUT"

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/<var>YOUR_GROUP_ID</var>

{
  "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": []
}
```

<Collapser id="update-group-patch-non-member" title="Update group with PATCH (Non-member fields)"

Example request:

```
PATCH /Groups/<var>YOUR_GROUP_ID</var>

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

Example response:

```
204 No Content
```

<Collapser id="update-group-patch-add-members" title="Update group with PATCH (Add members)"

Example request:

```
PATCH /Groups/<var>YOUR_GROUP_ID</var>

{
  "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
```

<Collapser id="update-group-patch-remove-members" title="Update group with PATCH (Remove members)"

Example request:

```
PATCH /Groups/<var>YOUR_GROUP_ID</var>

{
  "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
```

<Collapser id="delete-group" title="Delete group"

Example request:

```
DELETE /Groups/<var>YOUR_GROUP_ID</var>
```

Example response:

```
204 No Content
```

<Collapser id="create-user" title="Create user"

Example request:

```
POST /Users

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

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@test.com",
  "name": {
    "familyName": "User 1",
    "givenName": "Example"
  },
  "emails": [{
    "value": "example-user-1@test.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"
  },
  "members": []
}
```

<Collapser id="get-user" title="Get user"

Example request:

```
GET /Users/<var>YOUR_USER_ID</var>
```

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@test.com",
  "name": {
    "familyName": "User 1",
    "givenName": "Example"
  },
  "emails": [{
    "value": "example-user-1@test.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"
  },
  "members": []
}
```

<Collapser id="get-user-query" title="Get user by query"

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@test.com",
    "name": {
      "familyName": "User 1",
      "givenName": "Example"
    },
    "emails": [{
      "value": "example-user-1@test.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"
    },
    "members": []
  }]
}
```

<Collapser id="update-user-put" title="Update user with PUT"

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

```
PUT /Users/<var>YOUR_USER_ID</var>

{
  "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@test.com",
  "name": {
    "familyName": "User 1A",
    "givenName": "Example"
  },
  "emails": [{
    "value": "example-user-1@test.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"
  },
  "members": []
}
```

<Collapser id="update-user-patch" title="Update user with PATCH"

Example request:

```
PATCH /Users/<var>YOUR_USER_ID</var>

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

Example response:

```
204 No Content
```

<Collapser id="delete-user" title="Delete user"

Example request:

```
DELETE /Users/<var>YOUR_USER_ID</var>
```

Example response:

```
204 No Content
```

Deviations from the RFC [#rfc-deviations]

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.

  <th style={{ width: "100px" }}>
    RFC section number
  </th>

  <th>
    Deviation description
  </th>
</tr>

  <td>
    [3.3.](https://tools.ietf.org/html/rfc7644#section-3.3)
  </td>

  <td>
    * The `meta.location` field is not set.
  </td>
</tr>

<tr>
  <td>
    Filtering
  </td>

  <td>
    [3.4.2.2.](https://tools.ietf.org/html/rfc7644#section-3.4.2.2)
  </td>

  <td>
    * 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.
  </td>
</tr>

<tr>
  <td>
    `/Me` Authenticated Subject Alias
  </td>

  <td>
    [3.11.](https://tools.ietf.org/html/rfc7644#section-3.11)
  </td>

  <td>
    * `GET` with the `/Me` resource returns a `404 Not Found`.
  </td>
</tr>

<tr>
  <td>
    Service Provider Configuration Endpoints
  </td>

  <td>
    [4.](https://tools.ietf.org/html/rfc7644#section-4)
  </td>

  <td>
    * The service provider feature discovery endpoints do not support filtering.
  </td>
</tr>

<tr>
  <td>
    Bearer Token and Cookie Considerations
  </td>

  <td>
    [7.4.](https://tools.ietf.org/html/rfc7644#section-7.4)
  </td>

  <td>
    * Bearer tokens do not have a set expiration date.
  </td>
</tr>
RFC section name
Creating Resources

Next steps when you're done [#next-steps]

Downgrade users

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

Users provisioned via your identity provider start out as full users. If your organization is on New Relic One pricing, these users are billable. To convert users to free basic users, use the User management UI.

Assign access grants

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: