SCIM APIチュートリアル

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

要件

このチュートリアルは、元のユーザーモデルではなく、新しいユーザーモデルのユーザーに適用されます。

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

• 自動化されたユーザー管理のための要件とSCIM APIの使用.
• ユーザー管理の重要なコンセプト
• プライマリSCIM APIリファレンス

その他の関連資料

• 最も関連性の高い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 に追加したら、アクセス管理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にアクセスするには、クライアントは各リクエストにベアラートークンを含める必要があります。トークンは、認証ドメイン構成を保存した後に表示されます。

サードパーティの 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 レスポンスを受け取ります。

回答例

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

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

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

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

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

• 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

回答例

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

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:Error"
  ],
  "scimType": "invalidValue",
  "detail": "Validation failed: Username can't be blank",
  "status": "400"
}

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:Error"
  ],
  "scimType": "uniqueness",
  "detail": "Resource already exists",
  "status": "409"
}

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

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

回答例

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

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:Error"
  ],
  "scimType": "invalidValue",
  "detail": "Validation failed: Display name can't be blank",
  "status": "400"
}

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:Error"
  ],
  "scimType": "uniqueness",
  "detail": "Resource already exists",
  "status": "409"
}

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

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

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

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

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}に送信して、ユーザーを更新します。

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

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:Error"
  ],
  "scimType": "uniqueness",
  "detail": "Resource already exists",
  "status": "409"
}

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

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

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

• op に設定 Add
• path に設定 members
• value グループに追加する各ユーザーIDを持つ{"value": "${USER_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 に設定 Remove
• path に設定 members
• value グループから削除する各ユーザーIDを持つ{"value": "${USER_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 を使用することもできます。これを行うには、認証ドメインの設定を更新して、 ユーザータイプの制御を委任する をアイデンティティプロバイダーまたはカスタムアプリケーションに設定します。

ユーザーの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スキーマ拡張機能を含めます。

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

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:Error"
  ],
  "scimType": "uniqueness",
  "detail": "Resource already exists",
  "status": "409"
}

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:Error"
  ],
  "scimType": "invalidValue",
  "detail": "Validation failed: Username can't be blank",
  "status": "400"
}

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

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

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:Error"
  ],
  "scimType": "invalidValue",
  "detail": "Validation failed: invalid nrUserType value provided",
  "status": "400"
}