SCIM API 튜토리얼

이 튜토리얼은 SCIM API를 통해 사용자를 관리하기 위한 몇 가지 일반적인 절차를 안내합니다.SCIM API를 사용하면 사용자 관리 UI 외부에서 프로그래밍 방식으로 사용자 및 그룹을 보고, 만들고, 업데이트하고, 삭제할 수 있습니다.

요구 사항

이 튜토리얼은 원래 사용자 모델이 아닌 새로운 사용자 모델 의 사용자에게 적용됩니다.

이 자습서를 사용하기 전에 다음 내용을 읽는 것이 좋습니다.

• 자동화된 사용자 관리 및 SCIM API 사용에 대한 요구 사항 .
• 중요한 사용자 관리 개념
• 기본 SCIM API 참조

기타 관련 리소스:

• 가장 관련성이 높은 Internet Engineering Task Force의 일부 SCIM 2.0 RFC 문서: RFC 7643 - SCIM 핵심 리소스 및 확장 , RFC 7643 - JSON 표현 및 RFC 7644 - SCIM 프로토콜 .

개요

이 튜토리얼은 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 토큰 인증 을 사용하도록 구성하고 API 액세스 토큰을 연결합니다. 이를 구성하는 데 도움이 필요하면 ID 공급자의 설명서를 참조하십시오. 구성이 완료되면 사용자 및 그룹을 가져올 수 있습니다.

전체 SCIM 프로토콜 RFC를 읽는 대신 가치 있는 세 가지 특정 섹션이 있습니다. 자세한 내용은 RFC 7643 - SCIM 핵심 리소스 및 확장 및 RFC 7643 - JSON 표현 을 참조하세요. 이 튜토리얼에서 사용되는 프로토콜에 대한 자세한 정보는 RFC 7644 - SCIM 프로토콜 을 참조하십시오.

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 임에도 불구하고 이 절차에서는 하나만 입력하십시오.)
• 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

예시 응답

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

인증 도메인의 사용자 및 그룹 보기

일부 사용자와 그룹을 만든 후에는 사용자 관리 UI 에 표시됩니다. SCIM API에서 검색할 수도 있습니다.

이 자습서에서는 특정 사용자와 그룹을 검색하지만 이것이 사용자와 그룹을 보는 유일한 방법은 아닙니다. 사용 가능한 모든 쿼리 옵션은SCIM API 참조 및 RFC 7644 를 참조하십시오.

이메일로 사용자를 검색하려면 filter 쿼리 매개변수를 사용하여 /scim/v2/Users 에 GET 요청을 보냅니다. 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": []
    }
  ]
}

마찬가지로 filter 쿼리 매개변수를 사용하여 /scim/v2/Groups 에 GET 요청을 보내 이름으로 그룹을 검색합니다.

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 사용에 대한 자세한 내용은 SCIM API 지원 작업 및 RFC 7644 를 참조하세요. 이 가이드는 PUT 메서드를 사용하여 사용자의 속성을 업데이트하는 방법을 보여줍니다.

New Relic은 모든 사용자 속성이 요청 본문에 포함될 필요가 없으며 업데이트하려는 속성만 필요합니다. 사용자를 업데이트하려면 /scim/v2/Users/${ID} 에 PUT 요청을 보냅니다.

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 사용에 대한 자세한 내용은 SCIM API 지원 작업 및 RFC 7644 를 참조하세요.

PATCH 요청에 전체 구성원 목록을 지정할 필요 없이 그룹 구성원을 추가하거나 제거하는 데 편리합니다. 그룹에 사용자를 추가하려면 다음 작업 매개변수를 사용하십시오.

• op 로 설정 Add
• path 로 설정 members
• value 그룹에 추가할 각 사용자 ID와 함께 {"value": "${USER_ID}"} 목록으로 설정

그룹 구성원을 업데이트하려면 /scim/v2/Groups/${ID} 에 PATCH 요청을 보냅니다.

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

사용자 및 그룹 삭제

인증 도메인에서 사용자를 제거하려면 /scim/v2/Users/${ID} 에 DELETE 요청을 보냅니다.

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 사용자는 기본적으로 기본 사용자 로 시작하며 업그레이드할 수 있는 옵션이 있습니다. 자세한 내용은 사용자 유형 관리 를 참조하십시오.
• SAML SSO를 설정합니다 .
• 사용자 그룹이 New Relic에 있으면 특정 역할과 특정 계정을 할당해야 합니다. 사용자 액세스 작동 방식에 대해 자세히 알아보세요.

선택 사항: 사용자 유형 관리

SCIM API 통합이 완료되면 New Relic에 가져온 모든 사용자는 기본 사용자로 시작합니다. 사용자 관리 UI 를 사용하는 기본 사용자 유형 관리 방법을 사용할 수 있습니다. 선택적으로 SCIM API를 대신 사용할 수 있습니다. 이렇게 하려면 인증 도메인 구성 업데이트 를 사용자 유형 제어를 ID 공급자 또는 사용자 지정 응용 프로그램에 위임 하도록 설정할 수 있습니다.

사용자의 유형 속성은 사용자 정의 스키마 urn:ietf:params:scim:schemas:extension:newrelic:2.0:User 에 정의되어 있습니다. 이 스키마와 nrUserType 문자열 속성을 생성 또는 업데이트 요청에 포함하여 사용자 유형을 설정합니다.

nrUserType 에 유효한 값은 다음과 같습니다.

• Full User
• Core User
• Basic User

새 Basic user 을 만들려면 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"
  }
}

{
  "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} 을 보내고 맞춤 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"
  }
}

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