역할 매핑 API를 위한 타사 인증

페더레이션 인증(Federated Authentication) 메커니즘을 사용할 경우 이 API를 이용하여 Datadog 내에서 ID 제공업체(Identity Provider)가 전송하는 속성을 사용하여 사용자 그룹을 역할에 자동으로 매핑할 수 있습니다. API를 사용하여 인증 매핑(Authentication Mapping)을 생성하고 관리하려면, 액세스 관리(Access Management) 권한을 받은 소유자가 보유한 애플리케이션 키를 사용해야 합니다.

참조: SAML 사용자로서 기존 베타 페더레이션 매핑(Federated Mapping) 메커니즘(roles_v2_saml)을 사용하는 경우, 이 API를 사용하실 것을 강력하게 권장합니다.

Datadog UI(User Management의 Mappings 탭)에서도 매핑을 생성하거나 관리할 수 있습니다. 자세한 내용은 SAML 속성의 Datadog 역할 매핑을 참조해주세요.

요청

아래의 모든 API 엔드포인트는 다음의 호스트 엔드포인트를 사용합니다.

  • Datadog 지역

새 인증 매핑 생성하기

AuthN Mapping을 JSON 본문에서 새롭게 생성합니다. 새로 생성된 AuthN Mapping을 반환합니다.

방법엔드포인트 경로필수 페이로드
POST/v2/authn_mappingsJSON
인수
  • role["data"]["id"] [필수, 기본 설정 없음]: 매핑할 역할의 ID. Roles API를 사용해 Datadog 역할, 역할에 부여하는 글로벌 권한, 해당 역할에 속하는 사용자를 생성하고 관리할 수 있습니다. 참조 : 이 속성은 요청된 role 관계 블록의 일부로 제시되어야 합니다. 자세한 예시는 아래에서 찾아보실 수 있습니다. 생성하는 역할에는 ID가 할당됩니다. 매핑할 역할의 ID를 찾는 방법을 자세히 알아보려면 Role API 문서를 참조하시기 바랍니다.
  • attributes["attribute_key"] [필수, 기본 설정 없음]: attribute_key는 ID 제공업체에서 송신하는 속성을 나타내는 키/값(key/value) 쌍의 키 부분입니다. 각 사용자의 사용 사례에 맞추어 이 2가지를 정의할 수 있습니다. 예를 들어 attribute_keymember-of로, attribute_valueDevelopment로 정의할 수 있습니다.
  • attributes["attribute_value"] [필수, 기본 설정 없음]: attribute_value는 ID 제공업체에서 송신하는 속성을 나타내는 키/값(key/value) 쌍의 값 부분입니다. 각 사용자의 사용 사례에 맞추어 이 2가지를 정의할 수 있습니다. 예를 들어 attribute_keymember-of로, attribute_valueDevelopment로 정의할 수 있습니다.
curl -X POST \
    "https://api.<YOUR_DD_SITE>/api/v2/authn_mappings" \
    -H "Content-Type: application/json" \
    -H "DD-API-KEY: <YOUR_DATADOG_API_KEY>" \
    -H "DD-APPLICATION-KEY: <YOUR_DATADOG_APPLICATION_KEY>" \
    -d '{
            "data": {
                "type": "authn_mappings",
                "attributes": {
                    "attribute_key": "member-of",
                    "attribute_value": "Development"
                },
                "relationships": {
                    "role": {
                        "data": {
                            "id": "123e4567-e89b-12d3-a456-426655445555",
                            "type": "roles"
                        }
                    }
                }
            }
        }'
  • <YOUR_DATADOG_API_KEY><YOUR_DATADOG_APPLICATION_KEY>를 해당하는 귀 조직의 API 및 애플리케이션 키로 바꿉니다.
  • <YOUR_DD_SITE>로 바꿉니다.
{
    "data": {
        "attributes": {
            "created_at": "2019-11-04 17:41:29.015504",
            "modified_at": "2019-11-04 17:41:29.015504",
            "role_uuid": "00000000-0000-0000-0000-000000000000",
            "saml_assertion_attribute_id": 0
        },
        "type": "authn_mappings",
        "id": "123e4567-e89b-12d3-a456-426655440000",
        "relationships": {
            "saml_assertion_attribute": {
                "data": {
                    "id": 0,
                    "type": "saml_assertion_attributes"
                }
            },
            "role": {
                "data": {
                    "id": "123e4567-e89b-12d3-a456-426655440000",
                    "type": "roles"
                }
            }
        }
    },
    "included": [
        {
            "data": {
                "id": "123e4567-e89b-12d3-a456-426655440000",
                "type": "roles",
                "attributes": {
                    "created_at": "2019-11-04 17:41:29.015504",
                    "modified_at": "2019-11-06 17:41:29.015504",
                    "name": "Developer Role"
                },
                "relationships": {
                    "permissions": {
                        "data": [
                            {
                                "id": "123e4567-e89b-12d3-a456-426655441000",
                                "type": "permissions"
                            }
                        ]
                    }
                }
            }
        },
        {
            "data": {
                "id": 6,
                "type": "saml_assertion_attributes",
                "attributes": {
                    "id": 6,
                    "attribute_key": "member-of",
                    "attribute_value": "Development"
                }
            }
        }
    ]
}

전체 AuthN 매핑 가져오기

AuthN 매핑 목록을 반환합니다

방법엔드포인트 경로필수 페이로드
GET/v2/authn_mappings부수적인 쿼리 파라미터
인수
  • sort [optional, default=created_at]: 속성을 지정한 방향으로 정렬합니다. 기본 설정에서는 오름차순으로, ‘-‘를 지정하면 내림차순으로 정렬합니다. 또, 관련 속성인 -<attribute> sorts in descending order. Can also sort on relationship attributes role.name, saml_assertion_attribute.attribute_key, saml_assertion_attribute.attribute_value에서도 정렬이 가능합니다.
  • page[number] [선택 사항, 기본 설정=0, 최솟값=0]: 반환할 결과의 페이지 수입니다.
  • page[size] [선택 사항, 기본 설정=10]: 각 페이지에서 반환할 결과 수입니다.
  • filter [선택 사항, 기본 설정=none]: 스트링별로 태그를 필터링합니다. 예를 들면 Billing Users가 있습니다.
curl -X GET "https://api.<YOUR_DD_SITE>/api/v2/authn_mappings" \
     -H "DD-API-KEY: <YOUR_DATADOG_API_KEY>" \
     -H "DD-APPLICATION-KEY: <YOUR_DATADOG_APPLICATION_KEY>"
  • <YOUR_DATADOG_API_KEY><YOUR_DATADOG_APPLICATION_KEY>를 해당하는 귀 조직의 API 및 애플리케이션 키로 바꿉니다.
  • <YOUR_DD_SITE>로 바꿉니다.
{
    "data": [
      {
        "type": "authn_mapping",
        "id": "123e4567-e89b-12d3-a456-426655440000",
        "relationships": {
          "saml_assertion_attribute": {
            "data": {"id": 0, "type": "saml_assertion_attributes"}
          },
          "role": {
            "data": {
              "id": "123e4567-e89b-12d3-a456-426655440000",
              "type": "roles"
            }
          }
        },
        "attributes": {
          "created_at": "2019-11-04 17:41:29.015504",
          "modified_at": "2019-11-04 17:41:29.015504",
          "saml_assertion_attribute_id": 0
        }
      }
    ],
    "included": [
      {
        "data": {
          "id": "123e4567-e89b-12d3-a456-426655440000",
          "type": "roles",
          "attributes": {
            "created_at": "2019-11-04 17:41:29.015504",
            "modified_at": "2019-11-06 17:41:29.015504",
            "name": "Developer Role"
          },
          "relationships": {
            "permissions": {
                "data": [
                  {
                    "id": "123e4567-e89b-12d3-a456-426655440000",
                    "type": "permissions"
                  }
                ]
            }
          }
        }
      },
      {
        "data": {
          "id": 6,
          "type": "saml_assertion_attributes",
          "attributes": {
            "id": 6,
            "attribute_key": "member-of",
            "attribute_value": "Developer"
          }
        }
      }
    ],
    "meta": {
      "page": {
        "total_count": 1,
        "total_filtered_count": 1,
      }
    }
}

특정 AuthN 매핑 가져오기

UUID를 활용해 특정 AuthN 매핑을 반환합니다.

방법엔드포인트 경로필수 페이로드
GET/authn_mappings/{authn_mapping_id}URL 파라미터
인수
  • {authn_mapping_id} [필수, 기본 설정 없음]: {authn_mapping_id}를 조회할 AuthN 매핑 ID로 바꿉니다.
curl -X GET "https://api.<YOUR_DD_SITE>/api/v2/authn_mappings/{authn_mapping_id}" \
     -H "DD-API-KEY: <YOUR_DATADOG_API_KEY>" \
     -H "DD-APPLICATION-KEY: <YOUR_DATADOG_APPLICATION_KEY>"
  • <YOUR_DATADOG_API_KEY><YOUR_DATADOG_APPLICATION_KEY>를 해당하는 귀 조직의 API 및 애플리케이션 키로 바꿉니다.
  • <YOUR_DD_SITE>로 바꿉니다.
{
    "data": {
        "attributes": {
            "created_at": "2019-11-04 17:41:29.015504",
            "modified_at": "2019-11-04 17:41:29.015504",
            "uuid": "123e4567-e89b-12d3-a456-426655440000",
            "saml_assertion_attribute_id": 0
        },
        "type": "authn_mappings",
        "id": "123e4567-e89b-12d3-a456-426655440000",
        "relationships": {
            "saml_assertion_attribute": {
                "data": {
                    "id": 0,
                    "type": "saml_assertion_attributes"
                }
            },
            "role": {
                "data": {
                    "id": "123e4567-e89b-12d3-a456-426655440000",
                    "type": "roles"
                }
            }
        }
    },
    "included": [
        {
            "data": {
                "id": "123e4567-e89b-12d3-a456-426655440000",
                "type": "roles",
                "attributes": {
                    "created_at": "2019-11-04 17:41:29.015504",
                    "modified_at": "2019-11-06 17:41:29.015504",
                    "uuid": "123e4567-e89b-12d3-a456-426655440000",
                    "name": "Developer Role"
                },
                "relationships": {
                    "permissions": {
                        "data": [
                            {
                                "id": "123e4567-e89b-12d3-a456-426655440000",
                                "type": "permissions"
                            }
                        ]
                    }
                }
            }
        },
        {
            "data": {
                "id": 6,
                "type": "saml_assertion_attributes",
                "attributes": {
                    "id": 6,
                    "attribute_key": "member-of",
                    "attribute_value": "Developer"
                }
            }
        }
    ]
}

매핑 업데이트

AuthN 매핑 role, saml_assertion_attribute_id, 또는 둘 모두를 JSON 본문에서 업데이트합니다. 업데이트된 AuthN 매핑을 반환합니다.

방법엔드포인트 경로필수 페이로드
PATCH/v2/authn_mappings/{authn_mapping_id}URL 파라미터, JSON
인수
  • {authn_mapping_id} [필수, 기본 설정 없음]: {authn_mapping_id}를 업데이트할 AuthN 매핑 ID로 바꿉니다. 이때 요청 경로와 요청 본문 모두가 필요합니다.
  • role["data"]["id"] [선택 사항, 기본 설정=none]: 매핑할 역할의 ID. Roles API를 사용해 Datadog 역할, 역할에 부여하는 글로벌 권한, 해당 역할에 속하는 사용자를 생성하고 관리할 수 있습니다. 참조 : 이 속성은 요청된 role 관계 블록의 일부로 제시되어야 합니다. 자세한 예시는 아래에서 찾아보실 수 있습니다. 생성하는 역할에는 ID가 할당됩니다. 매핑할 역할의 ID를 찾는 방법을 자세히 알아보려면 Role API 문서를 참조하시기 바랍니다.
  • attributes["attribute_key"] [선택 사항, 기본 설정=none]: attribute_key는 ID 제공업체에서 송신하는 속성을 나타내는 키/값(key/value) 쌍의 키 부분입니다. 각 사용자의 사용 사례에 맞추어 이 2가지를 정의할 수 있습니다. 예를 들어 attribute_keymember-of로, attribute_valueDevelopment로 정의할 수 있습니다.
  • attributes["attribute_value"] [선택 사항, 기본 설정=none]: attribute_value는 ID 제공업체에서 송신하는 속성을 나타내는 키/값(key/value) 쌍의 값 부분입니다. 각 사용자의 사용 사례에 맞추어 이 2가지를 정의할 수 있습니다. 예를 들어 attribute_keymember-of로, attribute_valueDevelopment로 정의할 수 있습니다.
curl -X PATCH \
    "https://api.<YOUR_DD_SITE>/api/v2/authn_mappings/{UUID}" \
    -H "Content-Type: application/json" \
    -H "DD-API-KEY: <YOUR_DATADOG_API_KEY>" \
    -H "DD-APPLICATION-KEY: <YOUR_DATADOG_APPLICATION_KEY>" \
    -d '{
            "data": {
                "type": "authn_mappings",
                "id": "{authn_mapping_id}",
                "attributes": {
                    "attribute_key": "member-of",
                    "attribute_value": "Developer"
                }
                "relationships": {
                "role": {
                    "data": {
                            "id": "123e4567-e89b-12d3-a456-426655440000",
                            "type": "roles"
                        }
                    }
                }
            }
        }'
  • <YOUR_DATADOG_API_KEY><YOUR_DATADOG_APPLICATION_KEY>를 해당하는 귀 조직의 API 및 애플리케이션 키로 바꿉니다.
  • <YOUR_DD_SITE>로 바꿉니다.
{
    "data": {
        "attributes": {
            "created_at": "2019-11-04 17:41:29.015504",
            "modified_at": "2019-11-04 17:41:29.015504",
            "saml_assertion_attribute_id": 0
        },
        "type": "authn_mappings",
        "id": "123e4567-e89b-12d3-a456-426655440000",
        "relationships": {
            "saml_assertion_attribute": {
                "data": {
                    "id": 0,
                    "type": "saml_assertion_attributes"
                }
            },
            "role": {
                "data": {
                    "id": "123e4567-e89b-12d3-a456-426655440000",
                    "type": "roles"
                }
            }
        }
    },
    "included": [
        {
            "data": {
                "id": "123e4567-e89b-12d3-a456-426655440000",
                "type": "roles",
                "attributes": {
                    "created_at": "2019-11-04 17:41:29.015504",
                    "modified_at": "2019-11-06 17:41:29.015504",
                    "uuid": "123e4567-e89b-12d3-a456-426655440000",
                    "name": "Developer Role"
                },
                "relationships": {
                    "data": [
                        {
                            "id": "123e4567-e89b-12d3-a456-426655440000",
                            "type": "permissions"
                        }
                    ]
                }
            }
        },
        {
            "data": {
                "id": 6,
                "type": "saml_assertion_attributes",
                "attributes": {
                    "id": 6,
                    "attribute_key": "member-of",
                    "attribute_value": "Developer"
                }
            }
        }
    ]
}

매핑 삭제

특정 AuthN 매핑을 삭제합니다.

방법엔드포인트 경로필수 페이로드
DELETE/v2/authn_mappings/{authn_mapping_id}URL 파라미터
인수
  • {authn_mapping_id} [필수, 기본 설정 없음]: {authn_mapping_id}를 삭제할 AuthN 매핑 ID로 바꿉니다.
curl -X DELETE "https://api.<YOUR_DD_SITE>/api/v2/authn_mappings/{UUID}" \
         -H "Content-Type: application/json" \
         -H "DD-API-KEY: <YOUR_DATADOG_API_KEY>" \
         -H "DD-APPLICATION-KEY: <YOUR_DATADOG_APPLICATION_KEY>"
  • <YOUR_DATADOG_API_KEY><YOUR_DATADOG_APPLICATION_KEY>를 해당하는 귀 조직의 API 및 애플리케이션 키로 바꿉니다.
  • <YOUR_DD_SITE>로 바꿉니다.
HTTP/2 204

AuthN 매핑 활성화 가져오기

AuthN 매핑의 활성화 여부를 점검합니다.

방법엔드포인트 경로필수 페이로드
GET/v1/org_preferences없음
curl -X GET \
         "https://api.<YOUR_DD_SITE>/api/v1/org_preferences" \
         -H "Content-Type: application/json" \
         -H "DD-API-KEY: <YOUR_DATADOG_API_KEY>" \
         -H "DD-APPLICATION-KEY: <YOUR_DATADOG_APPLICATION_KEY>" \
  • <YOUR_DATADOG_API_KEY><YOUR_DATADOG_APPLICATION_KEY>를 해당하는 귀 조직의 API 및 애플리케이션 키로 바꿉니다.
  • <YOUR_DD_SITE>로 바꿉니다.
{
  "data": {
    "attributes": {
        "preference_data": "saml_authn_mapping_roles",
        "preference_type": true
    },
    "type": "org_preferences",
    "id": 1,
  },
}

전체 매핑의 활성화/비활성화

매핑을 활성화하면 SAML로 로그인한 모든 사용자의 역할이 지워지고 각 SAML의 어셔션(Assertion) 값을 기반으로 역할이 재할당됩니다. 매핑 기능을 활성화하기 전에 로그인을 통해 원하는 SAML 어셔션을 수신하고 있는지 반드시 확인하시기 바랍니다.

전체 AuthN 매핑의 실행을 활성화/비활성화합니다.

방법엔드포인트 경로필수 페이로드
POST/v1/org_preferencesJSON
인수
  • {preference_type} [필수, 기본 설정 없음]: 업데이트할 설정으로, 값은 “saml_authn_mapping_roles"입니다.
  • {preference_data} [필수, 기본 설정 없음]: 설정을 업데이트할 데이터로, 참 또는 거짓이어야 합니다. 참(true)인 경우 전체 매핑을 활성화하며, 거짓(false)인 경우 비활성화합니다.
curl -X POST \
    "https://api.<YOUR_DD_SITE>/api/v1/org_preferences" \
    -H "Content-Type: application/json" \
    -H "DD-API-KEY: <YOUR_DATADOG_API_KEY>" \
    -H "DD-APPLICATION-KEY: <YOUR_DATADOG_APPLICATION_KEY>" \
    -d '{
        "data": {
            "type": "org_preferences",
            "attributes": {
                "preference_type": "saml_authn_mapping_roles",
                "preference_data": true
            }
        }
    }'
`
  • <YOUR_DATADOG_API_KEY><YOUR_DATADOG_APPLICATION_KEY>를 해당하는 귀 조직의 API 및 애플리케이션 키로 바꿉니다.
  • <YOUR_DD_SITE>로 바꿉니다.
{
  "data": {
    "attributes": {
        "preference_type": "saml_authn_mapping_roles",
        "preference_data": true
    },
    "type": "org_preferences",
    "id": 1,
  },
}

참고 자료

Additional helpful documentation, links, and articles: