SCIM APIチュートリアル

このチュートリアルでは、 New Relic One のユーザーモデルにおいて、SCIM API を使ってユーザーを管理するための一般的な手順を説明します。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への取り込みが完了したら、 Organization and access UIを使用して、アクセスグラントを作成する必要があります。アクセスグラントは、グループに特定のロールやアカウントへのアクセス権を与えるものです。詳しくは、 user management concepts をご覧ください。

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 にアクセスするためには、クライアントは各リクエストに ベアラートークン を含める必要があります。トークンは、Authentication Domain の設定を保存した後に表示されます。

サードパーティの 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 による例です:

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

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

回答例

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

SCIM API を使用して、 POST リクエストを /scim/v2/Users に送信し、ユーザを作成することができます。以下のユーザ属性は 必須です 。

userName この識別子は、認証ドメイン内で一意でなければなりません。ユーザーの電子メールアドレスを使用します。
emails userName と同じです。ユーザーの電子メールアドレスです。( emails と呼ばれているにもかかわらず、この手順では1つだけ入力します)。
active ユーザーがNew Relic内でアクティブであるべきか、非アクティブであるべきかを示すブール値。

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

name.givenName ユーザーのファーストネームまたはギルドネームです。
name.familyName ユーザーのラストネームまたはファミリーネームです。
timezone IANAタイムゾーンデータベース形式のユーザーのタイムゾーン。

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 に送信し、グループを作成することができます。必要なグループ属性はだけです。

displayName グループ名です。

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 を参照してください。

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

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 リクエストを /scim/v2/Groups に filter クエリパラメータを付けて送信し、名前でグループを取得します。

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 の両方の方法をサポートしています。 SCIM API supported actions and RFC 7644 PATCH の使用に関する詳細はこちらを参照してください。このチュートリアルでは、 PUT メソッドを使ってユーザの属性を更新する方法を説明します。

New Relic は ****すべてのユーザー属性をリクエストボディに含める必要はなく、更新したい属性のみが必要です。 PUT リクエストを /scim/v2/Users/${ID} に送信します。 ユーザーを更新します。

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 メソッドを使ってグループのメンバーを更新する方法を説明します。 SCIM API supported actions and RFC 7644 PUT の使用に関する詳細を参照してください。

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

op set to Add
パス に設定 メンバー
値 リストに設定された {"値":"${USER_ID}を表示します。"} グループに追加する各ユーザーIDと一緒に

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

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 set to Remove
パス に設定 メンバー
値 リストに設定された {"値":"${USER_ID}を表示します。"} グループから削除する各ユーザーIDを設定

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} に送信します。 。

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} に送信します。 。

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 を使用することもできます。これを行うには、認証ドメインの設定を更新して、ユーザータイプの制御を委任するをアイデンティティプロバイダーまたはカスタムアプリケーションに設定します。

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

nrUserType の有効な値は以下の通りです。

フルユーザー
コアユーザー
ベーシックユーザー

新しい Basic ユーザー を作成するには、 POST リクエスト /scim/v2/Users を送信し、New Relic のカスタムスキーマエクステンションを含めます。

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} を送信します。 、カスタム New Relic スキーマ拡張を含めます。

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

本書は、お客様のご参考のために原文の英語版を機械翻訳したものです。

要件

概要

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