SCIM APIチュートリアル

このチュートリアルでは、SCIMAPIを介してユーザーを管理するためのいくつかの一般的な手順について説明します。SCIM APIを使用すると、ユーザー管理UIの外部で、ユーザーとグループをプログラムで表示、作成、更新、および削除できます。

要件

このチュートリアルを使用する前に、読むことをお勧めします。

その他の関連資料

最も関連性の高いInternet Engineering Task ForceのSCIM 2.0 RFC文書として、 RFC 7643 - SCIM Core Resources and Extensions 、 RFC 7643 - JSON Representation 、 RFC 7644 - SCIM Protocol があります。

概要

このチュートリアルでは、ID プロバイダサービスから New Relic にユーザーを追加し、そこからユーザーを管理するために必要な、最も一般的なタスクのいくつかを実行する方法を紹介します。これは、主要な SCIM API リソースを補完することを目的としています。

自動ユーザー管理を使用すると、ユーザーのグループがNew Relicにインポートされることに注意してください。つまり、ユーザー管理のUIを使ってユーザーをグループに追加することはできません。グループはお客様のIDプロバイダー側で作成、管理されます。

ユーザーグループを New Relic に取り込んだら、 Access management UI を使用して、それらのグループにロールとアカウントへのアクセス権を付与する必要があります。詳細については、「ユーザー管理の概念」を参照してください。

SCIM用の認証ドメインの設定

SCIM API を使用する前に、まず認証ドメインで SCIM を有効にする必要があります。なお、APIアクセストークンは設定を保存した後に一度だけ表示されるので、後のユーザーのために安全な場所に保存しておいてください。

ヒント

後でベアラートークンを表示する必要がある場合は、新しいベアラートークンを生成するしかありませんが、その場合、古いトークンは無効になり、古いトークンを使用した統合も無効になります。

システムにユーザーとユーザーグループを作成する

SCIM APIは一般的に、データベースやNew Relic用の設定があらかじめ用意されていないサードパーティのIDプロバイダーからNew Relicにユーザーやグループをインポートするスクリプトで使用されます。

SCIM APIをカスタムアプリケーションやアドホックなリクエストに使用したい場合は、SCIM APIへの接続方法に進んでください。

SCIM APIへの接続

SCIM API はhttps://scim-provisioning.service.newrelic.com/scim/v2で利用可能であり、この URL は認証ドメイン設定ページで確認できます。 SCIM API にアクセスするには、クライアントは各リクエストにbearer tokenを含める必要があります。認証ドメインの設定を保存すると、トークンが表示されます。

サードパーティの ID プロバイダーを使用している場合は、 Bearer token authorizationを使用するように構成し、API アクセストークンを入力します。これを構成する方法については、ID プロバイダーのドキュメントを参照してください。設定が完了すると、ユーザーとグループをインポートする準備が整います。

SCIMプロトコルのRFC全体を読むのではなく、価値のある3つの特定のセクションがあります。 RFC 7643 - SCIM Core Resources and Extensions と RFC 7643 - JSON Representation を参照してください。このチュートリアルで使われているプロトコルについては、 RFC 7644 - SCIM Protocol を参照してください。

SCIM APIへのすべてのリクエストでは、 Authorizationヘッダーにベアラトークンを指定する必要があります。 curlの例を次に示します。

bash

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

API アクセストークンが見つからないか無効な場合、このチュートリアルの残りのリクエストはすべて401 Unauthorized応答を受け取ります。

回答例

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

認証ドメインでのユーザー作成

SCIM API を使用して、 POSTリクエストを/scim/v2/Usersに送信し、ユーザーを作成できます。次のユーザー属性はrequiredです:

userName この識別子mustは認証ドメイン内で一意である必要があります。ユーザーのメールアドレスを使用します。
emails userNameと同じです。ユーザーのメールアドレス。（ emailsと呼ばれていますが、この手順では1つだけ入力してください。）
active NewRelic内でユーザーをアクティブにするか非アクティブにするかを示すブール値。

最高のユーザー体験のために、以下の属性を提供することをお勧めします。

name.givenName ユーザーの名または名。
name.familyName ユーザーの姓または家族の名前。
timezone IANAタイムゾーンデータベース形式のユーザーのタイムゾーン。

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

重要

返されたユーザーidに注意してください。将来ユーザーを更新するには、リクエストと同じIDを指定する必要があります。

回答例

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

認証ドメインでのグループ作成

SCIM API を使用して、 POSTリクエストを/scim/v2/Groupsに送信し、グループを作成できます。唯一のグループ属性requiredは次のとおりです:

displayName グループ名。

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

重要

返されたグループidに注意してください。将来、グループまたはそのメンバーを更新するには、リクエストで同じIDを指定する必要があります。

回答例

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

認証ドメイン内のユーザーとグループの表示

いくつかのユーザとグループを作成した後、それらは User management UI で見ることができます。また、SCIM API からそれらを取得することもできます。

このチュートリアルでは、特定のユーザやグループを検索しますが、ユーザやグループを表示する方法はそれだけではありません。利用可能なすべてのクエリオプションについては、 SCIM API reference および RFC 7644 を参照してください。

メールでユーザーを取得するには、 filterクエリパラメータを使用してGETリクエストを/scim/v2/Usersに送信します。 filterパラメータはURLエンコードする必要があります。

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"'

回答例

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

同様に、 GETリクエストをfilterクエリパラメータを使用して/scim/v2/Groupsに送信し、名前でグループを取得します。

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"'

回答例

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

ユーザーの属性の更新

SCIM APIは、ユーザーを更新するためのPUT メソッドとPATCHメソッドの両方をサポートしています。 PATCHの使用の詳細については、SCIMAPIでサポートされているアクションとRFC7644を参照してください。このチュートリアルでは、 PUTメソッドを使用してユーザーの属性を更新する方法を示します。

New Relicでは、すべてのユーザー属性をリクエスト本文に含める必要はありません。更新する属性のみが必要です。 PUTリクエストを/scim/v2/Users/${ID}に送信して、ユーザーを更新します。

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

回答例

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

グループのメンバーの更新

SCIM APIは、グループを更新するためのPUT メソッドとPATCHメソッドの両方をサポートします。このチュートリアルでは、 PATCHメソッドを使用してグループのメンバーを更新する方法を示します。 PUTの使用の詳細については、SCIMAPIでサポートされているアクションとRFC7644を参照してください。

PATCH リクエストで完全なメンバーリストを指定しなくても、グループメンバーを追加または削除するのに便利です。グループにユーザーを追加するには、次の操作パラメーターを使用します。

op に設定 Add
path に設定 members
value グループに追加する各ユーザーIDを持つ{"value": "${USER_ID}"}のリストに設定します

グループメンバーを更新するには、 PATCHリクエストを/scim/v2/Groups/${ID}に送信します。

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

回答例

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

グループからユーザーを削除するには、以下の操作パラメーターを使用します。

op に設定 Remove
path に設定 members
value グループから削除する各ユーザーIDを持つ{"value": "${USER_ID}"}のリストに設定します

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

回答例

{
  "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リクエストを/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'

回答例

204 No Content

同様に、認証ドメインからグループを削除するには、 DELETEリクエストを/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'

回答例

204 No Content

次のステップ

統合が完了すると、次のステップが考えられます。

New Relic のユーザーは、デフォルトではベーシックユーザーとしてスタートしますが、アップグレードすることも可能です。詳しくは、 Manage user type をご覧ください。
Set up SAML SSO.
ユーザーグループを New Relic に配置したら、特定のロールと特定のアカウントを割り当てる必要があります。ユーザーアクセスのしくみについて詳しくは、こちらをご覧ください。

オプションユーザータイプの管理

SCIM API の統合が完了すると、New Relic に導入されたすべてのユーザーは基本ユーザーとしてスタートします。ユーザータイプを管理するために、デフォルトの方法であるユーザー管理 UI を使用することができます。オプションとして、代わりに SCIM API を使用することもできます。これを行うには、認証ドメインの設定を更新して、ユーザータイプの制御を委任するをアイデンティティプロバイダーまたはカスタムアプリケーションに設定します。

ユーザーのtype属性は、カスタムスキーマurn:ietf:params:scim:schemas:extension:newrelic:2.0:Userで定義されています。このスキーマとnrUserType文字列属性を作成または更新リクエストに含めて、ユーザーのタイプを設定します。

nrUserTypeの有効な値は次のとおりです。

Full User
Core User
Basic User

新しいBasic userを作成するには、 POSTリクエスト/scim/v2/Usersを送信し、カスタムのNewRelicスキーマ拡張機能を含めます。

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

回答例

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

ユーザーのタイプを更新するには、 PUTリクエストscim/v2/Users/${ID}を送信し、カスタムのNewRelicスキーマ拡張機能を含めます。

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

回答例

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

この機械翻訳は、参考として提供されています。

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

概要

SCIM用の認証ドメインの設定

ヒント

システムにユーザーとユーザーグループを作成する

SCIM APIへの接続

401 認証されていない

認証ドメインでのユーザー作成

重要

回答例

201 作成

400 Bad Request

409 コンフリクト

認証ドメインでのグループ作成

重要

回答例

201 作成

400 Bad Request

409 コンフリクト

認証ドメイン内のユーザーとグループの表示

200 OK

200 OK

ユーザーの属性の更新

回答例

200 OK

409 コンフリクト

グループのメンバーの更新

200 OK

200 OK

ユーザーとグループの削除

次のステップ

オプションユーザータイプの管理

回答例

200 OK

409 コンフリクト

400 Bad Request

回答例

200 OK

400 Bad Request

要件