외부 호출
외부 호출을 사용하면 Microsoft Dynamics 365 Fraud Protection 외부의 API에서 데이터를 수집한 다음 해당 데이터를 사용하여 실시간으로 정보에 입각한 결정을 내릴 수 있습니다. 예를 들어 타사 주소 및 전화 확인 서비스 또는 사용자 지정 점수 매기기 모델은 일부 이벤트의 위험 수준을 결정하는 데 도움이 되는 중요한 입력을 제공할 수 있습니다. 외부 호출을 사용하여 API 엔드포인트에 연결하고, 필요에 따라 규칙 내에서 해당 엔드포인트에 요청을 수행하고, 해당 엔드포인트의 응답을 사용하여 결정을 내릴 수 있습니다.
참고 항목
모든 이벤트에 이 추가 데이터가 필요한 경우 평가 스키마의 일부로 보낼 수도 있습니다. API 요청의 일부로 사용자 지정 데이터를 보내는 방법에 대한 자세한 내용은 사용자 지정 데이터 샘플을 참조하세요.
외부 호출에 사용할 수 있는 API 유형
외부 호출을 만들기 전에 다음 제한 사항에 대해 알아야 합니다.
- 사기 방지는 현재 익명 및 AAD 인증 방법만 지원합니다.
- 사기 방지는 현재 GET 및 POST와 같은 HTTP 방법만 지원합니다.
외부 호출 만들기
Fraud Protection 포털의 왼쪽 탐색 영역에서 외부 호출을 선택한 다음 새 외부 호출을 선택합니다.
필요에 따라 다음 필드를 검토하고 설정합니다.
이름 – 규칙에서 외부 호출을 참조하는 데 사용할 이름을 입력합니다. 이름에는 숫자, 문자 및 밑줄만 포함될 수 있습니다. 숫자로 시작할 수 없습니다.
참고 항목
규칙에서 외부 호출을 사용한 후에는 외부 호출의 이름을 변경할 수 없습니다.
설명 – 팀이 외부 통화를 빠르게 식별하는 데 도움이 되는 설명을 추가합니다.
웹 요청 – 적절한 HTTP 메서드(GET 또는 POST)를 선택한 다음, API 엔드포인트를 입력합니다.
참고 항목
HTTPS 엔드포인트만 지원됩니다.
정기적인 준비 호출 사용 - 외부 호출 엔드포인트에 대한 트래픽이 너무 낮으면 연결이 늦어질 수 있으며 외부 서비스의 응답 대기 시간을 늘릴 수 있습니다. 이 문제를 완화하려면 외부 통화 설정 페이지에서 준비 호출을 사용하도록 설정합니다 . 토글을 사용하여 준비 호출을 사용하도록 설정합니다. 유효한 GET 연결 유지 URL을 제공해야 합니다. 기본 엔드포인트와 마찬가지로 keep-alive 엔드포인트도 테스트 연결을 통과해야 합니다. 준비 호출을 사용하도록 설정하여 외부 통화를 구성하는 경우 트래픽 볼륨이 너무 낮아지면 Fraud Protection은 GET 메서드만 사용하여 keep-alive 엔드포인트에 대한 익명 준비 호출을 자동으로 합니다.
참고 항목
매개 변수, 구성 또는 구성 가능한 헤더는 준비 호출에 사용할 수 없습니다.
인증 – 들어오는 요청을 인증하는 데 사용해야 하는 방법을 선택합니다.
- 익명을 선택하면 권한 부여 헤더가 전송되지 않습니다.
- AAD를 선택하면 테넌트에 Azure AD(Azure Active Directory) 토큰이 생성되고 전달자 <토큰>이 권한 부여 헤더로 사용됩니다.
인증, 권한 부여 및 Azure AD 토큰에 대한 자세한 내용은 이 문서의 뒷부분에 있는 인증 및 권한 부여 이해 섹션을 참조하세요.
대상 그룹 - 인증 방법으로 AAD를 선택하는 경우 대상 그룹을 제공하라는 메시지가 표시됩니다. 기존 Azure 애플리케이션을 대상 그룹으로 사용하거나 Fraud Protection 포털 내의 통합 환경을 통해 새 애플리케이션을 만들 수 있습니다. 대상 그룹에 외부 통화/서비스에 액세스할 수 있는 권한이 있는지 확인합니다. Azure AD(Azure Active Directory) 인증을 구성하는 방법에 대한 자세한 내용은 Azure AD 인증 구성을 참조하세요.
애플리케이션 ID – 또한 Fraud Protection 구독 테넌트 내에서 신규 또는 기존 Azure AD 애플리케이션의 애플리케이션 ID를 제공해야 합니다. Azure Key Vault에서 인증서를 생성합니다. Fraud Protection 앱은 이 Azure Key Vault에 대한 읽기 권한이 있어야 합니다. 이 Azure AD 애플리케이션에 인증서를 로드합니다. Azure AD 애플리케이션을 만들고 관리하는 방법에 대한 자세한 내용은 Azure Active Directory 애플리케이션 만들기를 참조 하세요.
인증서 URL – Azure Key Vault에서 인증서 식별자 URL을 제공합니다. 이전 단계에서 Azure AD 앱에 로드한 것과 동일한 인증서입니다. Azure Key Vault에서 인증서를 생성하는 방법에 대한 자세한 내용은 Azure Key Vault에서 인증서 서명 요청 만들기 및 병합을 참조 하세요.
매개 변수 추가 – 매개 변수를 사용하여 Fraud Protection의 데이터를 API 엔드포인트로 전달할 수 있습니다. 선택한 HTTP 메서드에 따라 이러한 매개 변수는 쿼리 문자열 또는 요청 본문의 일부로 엔드포인트로 전송됩니다.
각 매개 변수에 대한 샘플 값을 추가할 수 있습니다. Fraud Protection은 이러한 매개 변수 값을 사용하여 만들기 전이나 테스트를 선택할 때마다 엔드포인트에 대한 샘플 호출을 만듭니다.
참고 항목
모든 매개 변수 값은 문자열로 해석됩니다.
샘플 요청 – 외부 호출로 전송되는 요청의 예를 제공합니다. 요청에는 지정한 매개 변수 이름과 값이 반영되어야 하며 편집할 수 없습니다.
GET 메서드의 경우 요청 URL이 표시됩니다. POST 메서드의 경우 요청 본문이 표시됩니다.
샘플 요청은 만들기 전이나 테스트를 선택할 때마다 엔드포인트에 대한 샘플 호출을 만드는 데 사용됩니다.
샘플 응답 – API 엔드포인트에서 성공적인 응답으로 반환되는 데이터의 예를 제공합니다. 이 데이터는 JSON(JavaScript Object Notation) 형식이어야 하며 규칙에서 참조할 수 있습니다. 여기에 제공하는 샘플은 규칙을 만들 때 표시됩니다.
테스트를 선택하여 이 필드에 API의 실제 응답을 자동으로 입력합니다.
시간 제한 – 요청이 시간 초과되기 전에 대기해야 하는 시간(밀리초)을 지정합니다. 1에서 1000 사이의 숫자를 지정해야 합니다.
기본 응답 – 요청이 실패하거나 지정된 제한 시간을 초과하는 경우 반환해야 하는 기본 응답을 지정합니다. 값은 유효한 JSON 개체 또는 JSON 요소여야 합니다.
선택 사항: 샘플 요청을 API 엔드포인트로 보내고 응답을 보려면 테스트를 선택합니다. 자세한 내용은 다음 섹션인 외부 호출 테스트 섹션을 참조하세요.
필수 필드 설정을 마치면 만들기를 선택합니다.
외부 호출 테스트
Fraud Protection이 엔드포인트에 연결할 수 있는지 확인하려면 언제든지 연결을 테스트합니다.
새 외부 호출을 만들거나 기존 외부 호출을 편집하는 동안 연결을 테스트하려면 필요한 모든 필드를 설정한 다음 테스트를 선택합니다.
Fraud Protection은 사용자가 제공한 엔드포인트 및 매개 변수를 사용하여 외부 호출에 요청을 보냅니다.
- Fraud Protection이 대상 엔드포인트에 성공적으로 도달하면 패널 맨 위에 녹색 메시지 표시줄이 나타나 연결이 성공했음을 알릴 수 있습니다. 전체 응답을 보려면 응답 세부 정보 참조를 선택합니다.
- Fraud Protection이 대상 엔드포인트에 도달할 수 없거나 지정된 제한 시간 전에 응답을 받지 못하면 패널 맨 위에 빨간색 메시지 표시줄이 나타나고 발생한 오류가 표시됩니다. 오류에 대한 자세한 내용을 보려면 오류 세부 정보 보기를 선택합니다.
외부 호출 모니터링
Fraud Protection 포털에서 외부 호출 모니터링
Fraud Protection은 정의한 각 외부 호출에 대한 세 가지 메트릭을 포함하는 타일을 보여 줍니다.
- 초당 요청 수 - 총 요청 수를 선택한 시간 프레임의 총 시간(분)으로 나눈 값입니다.
- 평균 대기 시간 – 총 요청 수를 선택한 시간 프레임의 총 시간(분)으로 나눈 값입니다.
- 성공률 – 성공한 총 요청 수를 총 요청 수로 나눈 값입니다.
이 타일에 표시되는 숫자와 차트에는 페이지의 오른쪽 위 모서리에 있는 드롭다운 목록에서 선택한 시간 프레임에 대한 데이터만 포함됩니다.
참고 항목
메트릭은 외부 호출이 활성 규칙에서 사용되는 경우에만 표시됩니다.
외부 호출에 대한 데이터를 자세히 알아보려면 타일의 오른쪽 모서리에서 성능을 선택합니다.
Fraud Protection은 메트릭에 대한 자세한 보기를 포함하는 새 페이지를 표시합니다.
지난 3개월 동안의 모든 시간 프레임에 대한 메트릭을 보려면 페이지 맨 위에 있는 날짜 범위 설정을 조정합니다.
앞에서 설명한 세 가지 메트릭 외에도 오류 차트가 표시됩니다. 이 차트에는 오류 유형 및 코드별 오류 수가 표시됩니다. 시간에 따른 오류 수를 보거나 오류 분포를 보려면 원형 차트를 선택합니다.
HTTP 클라이언트 오류(400, 401 및 403) 외에도 다음과 같은 오류가 표시될 수 있습니다.
- 잘못된 애플리케이션 ID - 제공된 애플리케이션 ID가 테넌트에 없거나 유효하지 않습니다.
- AAD 오류 – Azure AD 토큰을 검색할 수 없습니다.
- 정의를 찾을 수 없음 – 외부 호출이 삭제되었지만 여전히 규칙에서 참조됩니다.
- 시간 제한 – 대상에 대한 요청이 지정된 제한 시간보다 오래 걸렸습니다.
- 통신 실패 - 네트워크 문제 또는 대상을 사용할 수 없기 때문에 대상에 연결할 수 없습니다.
- 회로 차단기 – 외부 호출이 지속적으로 실패하고 특정 임계값을 초과하면 모든 추가 호출이 짧은 간격으로 일시 중단됩니다.
- 알 수 없는 오류 – 내부 Dynamics 365 오류가 발생했습니다.
이벤트 추적을 사용하여 외부 호출 모니터링
Fraud Protection의 이벤트 추적 기능을 사용하여 외부 호출과 관련된 이벤트를 Azure Event Hubs 또는 Azure Blob Storage의 자체 인스턴스로 전달할 수 있습니다. Fraud Protection 포털의 이벤트 추적 페이지에서 외부 호출과 관련된 다음 두 이벤트를 구독할 수 있습니다.
- FraudProtection.Monitoring.ExternalCalls
- FraudProtection.Errors.ExternalCalls
외부 호출에 대한 요청이 있을 때마다 이벤트가 FraudProtection.Monitoring.ExternalCalls 네임스페이스로 전송됩니다. 이벤트 페이로드에는 호출 대기 시간, 요청 상태 및 요청이 트리거된 규칙 및 절에 대한 정보가 포함됩니다.
외부 호출이 실패하면 이벤트가 FraudProtection.Errors.ExternalCalls 네임스페이스로 전송됩니다. 이벤트 페이로드에는 외부 호출로 전송된 URI 요청 및 본문과 수신된 응답이 포함됩니다.
이벤트 추적, 이벤트를 구독하는 방법 및 이벤트로 수행할 수 있는 작업에 대한 자세한 내용은 이벤트 추적을 참조하세요.
이 데이터를 조직의 워크플로와 통합하고 사용자 지정 모니터링, 경고 및 보고를 설정하는 방법에 대한 자세한 내용은 Event Hubs를 통한 확장성을 참조하세요.
외부 호출 관리
기존 외부 호출을 편집하려면 카드 헤더에서 편집을 선택합니다.
참고 항목
규칙에서 외부 호출을 사용한 후에는 외부 호출의 이름과 매개 변수를 변경할 수 없습니다.
기존 외부 호출을 삭제하려면 줄임표(...)를 선택한 다음 삭제를 선택합니다.
참고 항목
규칙에서 참조된 외부 호출은 삭제할 수 없습니다.
외부 호출에 대한 자세한 성능 메트릭을 보려면 성능을 선택합니다.
Fraud Protection이 외부 통화에 계속 연결할 수 있는지 테스트하려면 줄임표(...)를 선택한 다음, 연결 테스트를 선택합니다.
규칙에서 외부 호출 사용
외부 호출을 사용하여 결정을 내리려면 규칙에서 참조합니다.
예를 들어 규칙에서 myCall이라는 외부 호출을 참조하려면 다음 구문을 사용합니다.
External.myCall()
myCall에 IPaddress와 같은 매개 변수가 필요한 경우 다음 구문을 사용합니다.
External.myCall(@"device.ipAddress")
규칙 언어 및 규칙에서 외부 호출을 사용하는 방법에 대한 자세한 내용은 언어 참조 가이드를 참조하세요.
참고 항목
규칙에 외부 호출이 사용되는 경우 규칙의 대기 시간이 증가할 수 있습니다.
인증 및 권한 부여 이해
데이터에 안전하게 액세스하기 위해 API는 종종 요청의 발신자를 인증하여 데이터에 액세스할 수 있는 권한이 있는지 확인합니다. Fraud Protection의 외부 호출은 두 가지 인증 방법인 익명 및 AAD를 지원합니다.
익명을 선택하면 대상 엔드포인트에 대한 HTTP 요청의 권한 부여 헤더가 비워 집니다. 대상 엔드포인트에 권한 부여 헤더가 필요하지 않은 경우 이 옵션을 사용합니다. 예를 들어 엔드포인트에서 API 키를 사용하는 경우 웹 요청 필드에 입력하는 요청 URL의 일부로 키-값 쌍을 구성합니다. 그런 다음 대상 엔드포인트는 요청 URL의 API 키가 허용되는지 유효성을 검사한 다음 사용 권한을 부여할지 여부를 결정할 수 있습니다.
AAD를 선택하면 대상 엔드포인트에 대한 HTTP 요청의 권한 부여 헤더에 전달자 토큰이 포함됩니다. 전달자 토큰은 Azure AD에서 발급한 JWT(JSON 웹 토큰)입니다. JWT에 대한 자세한 내용은 Microsoft ID 플랫폼 액세스 토큰을 참조하세요. Fraud Protection은 다음과 같이 토큰 값을 요청 권한 부여 헤더의 필수 형식으로 "전달자" 텍스트에 추가합니다.
전달자 <토큰>
토큰 클레임
다음 표에서는 사기 방지에서 발급한 전달자 토큰에서 기대할 수 있는 클레임을 나열합니다.
| 속성 | 클레임 | 설명 |
|---|---|---|
| 테넌트 ID | tid | 이 클레임은 사기 방지 계정과 연결된 구독의 Azure 테넌트 ID를 식별합니다. Fraud Protection 포털에서 테넌트 ID를 찾는 방법에 대한 자세한 내용은 필수 ID 및 정보를 참조하세요. Azure Portal에서 테넌트 ID를 찾는 방법에 대한 자세한 내용은 Azure Active Directory 테넌트 ID를 찾는 방법을 참조하세요. |
| 대상 | aud | 이 클레임은 토큰의 의도된 수신자를 식별합니다. 이 값은 Fraud Protection 포털에서 외부 통화를 구성할 때 제공한 애플리케이션 ID를 정확하게 반영합니다. |
| 애플리케이션 UI | appid | 이 클레임은 Fraud Protection의 애플리케이션 ID입니다. * bf04bdab-e06f-44f3-9821-d3af64fc93a9*. 이 ID는 사기 방지에 의해서만 소유되며 Microsoft만 대신 토큰을 요청할 수 있습니다. |
API가 토큰을 받으면 토큰을 열고 위의 각 클레임이 해당 설명과 일치하는지 확인해야 합니다.
다음은 JwtSecurityTokenHandler를 사용하여 들어오는 요청을 인증하는 방법을 보여 주는 예제입니다.
string authHeader = "Bearer <token>"; // the Authorization header value
var jwt = new JwtSecurityTokenHandler().ReadJwtToken(token);
string tid = jwt.Claims.Where(c => c.Type == "tid").FirstOrDefault()?.Value;
string aud = jwt.Claims.Where(c => c.Type == "aud").FirstOrDefault()?.Value;
string appid = jwt.Claims.Where(c => c.Type == "appid").FirstOrDefault()?.Value;
if(tid != "<my tenant id>" || aud != "<my application id>" || appid != "bf04bdab-e06f-44f3-9821-d3af64fc93a9")
{
throw new Exception("the token is not authorized.");
}
외부 데이터 사례
귀하는 사기 방지의 외부 호출 기능을 통해 Microsoft에 제공하는 데이터 세트와 관련된 데이터 보호법, 계약 제한 및/또는 정책을 포함하여 모든 관련 법률 및 규정을 준수할 책임이 있음을 인정합니다. 또한 사기 방지 사용은 Microsoft 고객 계약 자세히 설명된 제한 사항을 사용할 수 있음을 인정합니다. 이 제한은 결제 거래를 진행할지 여부를 결정하는 유일한 요인으로 사기 방지(i)를 사용할 수 없음을 명시합니다. (ii) 보험, 주택 또는 고용에 대한 개인의 재무 상태, 재무 기록, 신용도 또는 자격을 결정하는 요인으로; 또는 (iii) 법적 효과를 생성하거나 크게 사람에게 영향을 미치는 결정을 내릴 수 있습니다. 또한 사기 방지의 외부 통화 기능 사용과 관련하여 중요하거나 규제가 높은 데이터 형식을 제공하거나 사용하지 않습니다. 사기 방지의 외부 호출 기능과 함께 사용하기 전에 데이터 세트 또는 데이터 형식을 검토하여 이 프로비저닝을 준수하는지 확인합니다. 또한 Microsoft는 사용자가 이 프로비저닝을 준수하는지 확인할 수 있는 권리를 보유합니다.