OnAttributeCollectionSubmit 이벤트 참조에 대한 사용자 지정 확장(미리 보기)
적용: 
Workforce 테넌트 
외부 테넌트(자세히 알아보기)
고객 셀프 서비스 등록 사용자 흐름에 대한 등록 환경을 수정하려면 사용자 지정 인증 확장을 만들고 사용자 흐름의 특정 지점에서 호출할 수 있습니다. OnAttributeCollectionSubmit 이벤트는 사용자가 특성을 입력하고 제출한 후에 발생하며 사용자가 제공한 정보의 유효성을 검사하는 데 사용할 수 있습니다. 예를 들어 초대 코드 또는 파트너 번호의 유효성을 검사하거나, 주소 형식을 수정하거나, 사용자가 계속하도록 허용하거나, 유효성 검사 또는 차단 페이지를 표시할 수 있습니다. 다음 작업을 구성할 수 있습니다.
- continueWithDefaultBehavior - 등록 흐름을 계속합니다.
- modifyAttributeValues - 사용자가 등록 양식에서 제출한 값을 덮어씁니다.
- showValidationError - 제출된 값에 따라 오류를 반환합니다.
- showBlockPage - 오류 메시지를 표시하고 사용자가 등록하지 못하도록 차단합니다.
이 문서에서는 OnAttributeCollectionSubmit 이벤트에 대한 REST API 스키마를 설명합니다. (OnAttributeCollectionStart 이벤트 대한 사용자 지정 확장에 관련된 문서도 참조하세요.)
팁
이 기능을 사용해 보려면 Woodgrove Groceries 데모로 이동하여 "등록 특성 유효성 검사" 사용 사례 또는 "사용자가 등록 프로세스를 계속하지 못하도록 차단 "사용 사례를 시작합니다.
REST API 스키마
특성 컬렉션 제출 이벤트에 대한 고유한 REST API를 개발하려면 다음 REST API 데이터 계약을 사용합니다. 스키마는 요청 및 응답 처리기를 디자인하는 계약을 설명합니다.
Microsoft Entra ID의 사용자 지정 인증 확장은 JSON 페이로드를 사용하여 REST API에 대한 HTTP 호출을 수행합니다. JSON 페이로드에는 사용자 프로필 데이터, 인증 컨텍스트 특성 및 사용자가 로그인하려는 애플리케이션에 대한 정보가 포함됩니다. JSON 특성을 사용하여 API에서 추가 논리를 수행할 수 있습니다.
외부 REST API에 대한 요청
REST API에 대한 요청은 아래와 같은 형식입니다. 이 예제에서 요청에는 기본 제공 특성(givenName 및 companyName) 및 사용자 지정 특성(universityGroups, graduationYear 및 onMailingList)과 함께 사용자 ID 정보가 포함됩니다.
요청에는 셀프 서비스 등록 중 컬렉션에 대한 사용자 흐름에서 선택한 사용자 특성(예: givenName 및 companyName)과 이미 정의된 사용자 지정 특성(예: universityGroups, graduationYear 및 onMailingList)이 포함됩니다. REST API는 새 특성을 추가할 수 없습니다.
요청에는 등록하기 위해 확인된 자격 증명으로 사용된 경우 사용자의 이메일을 포함한 사용자 ID도 포함됩니다. 암호가 전송되지 않습니다. 여러 값이 있는 특성의 경우 값은 쉼표로 구분된 문자열로 전송됩니다.
JSON
POST https://exampleAzureFunction.azureWebsites.net/api/functionName
{
"type": "microsoft.graph.authenticationEvent.attributeCollectionSubmit",
"source": "/tenants/aaaabbbb-0000-cccc-1111-dddd2222eeee/applications/<resourceAppguid>",
"data": {
"@odata.type": "microsoft.graph.onAttributeCollectionSubmitCalloutData",
"tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
"authenticationEventListenerId": "00001111-aaaa-2222-bbbb-3333cccc4444",
"customAuthenticationExtensionId": "11112222-bbbb-3333-cccc-4444dddd5555",
"authenticationContext": {
"correlationId": "<GUID>",
"client": {
"ip": "30.51.176.110",
"locale": "en-us",
"market": "en-us"
},
"protocol": "OAUTH2.0",
"clientServicePrincipal": {
"id": "<Your Test Applications servicePrincipal objectId>",
"appId": "<Your Test Application App Id>",
"appDisplayName": "My Test application",
"displayName": "My Test application"
},
"resourceServicePrincipal": {
"id": "<Your Test Applications servicePrincipal objectId>",
"appId": "<Your Test Application App Id>",
"appDisplayName": "My Test application",
"displayName": "My Test application"
},
},
"userSignUpInfo": {
"attributes": {
"givenName": {
"@odata.type": "microsoft.graph.stringDirectoryAttributeValue",
"value": "Larissa Price",
"attributeType": "builtIn"
},
"companyName": {
"@odata.type": "microsoft.graph.stringDirectoryAttributeValue",
"value": "Contoso University",
"attributeType": "builtIn"
},
"extension_<appid>_universityGroups": {
"@odata.Type": "microsoft.graph.stringDirectoryAttributeValue",
"value": "Alumni,Faculty",
"attributeType": "directorySchemaExtension"
},
"extension_<appid>_graduationYear": {
"@odata.type": "microsoft.graph.int64DirectoryAttributeValue",
"value": 2010,
"attributeType": "directorySchemaExtension"
},
"extension_<appid>_onMailingList": {
"@odata.type": "microsoft.graph.booleanDirectoryAttributeValue",
"value": false,
"attributeType": "directorySchemaExtension"
}
},
"identities": [
{
"signInType": "email",
"issuer": "contoso.onmicrosoft.com",
"issuerAssignedId": "larissa.price@contoso.onmicrosoft.com"
}
]
}
}
}
외부 REST API의 응답
Microsoft Entra ID에는 다음 형식의 REST API 응답이 예상됩니다. 응답 값 형식은 요청 값 형식과 일치합니다. 예를 들면 다음과 같습니다.
- 요청에
int64DirectoryAttributeValue의@odata.type이 있는graduationYear특성이 포함된 경우 응답에는2010같은 정수 값이 있는graduationYear특성이 포함되어야 합니다. - 요청에 쉼표로 구분된 문자열로 지정된 여러 값이 있는 특성이 포함된 경우 응답에는 쉼표로 구분된 문자열의 값이 포함되어야 합니다.
continueWithDefaultBehavior 작업은 외부 REST API가 연속 응답을 반환하도록 지정합니다.
HTTP/1.1 200 OK
{
"data": {
"@odata.type": "microsoft.graph.onAttributeCollectionSubmitResponseData",
"actions": [
{
"@odata.type": "microsoft.graph.attributeCollectionSubmit.continueWithDefaultBehavior"
}
]
}
}
modifyAttributeValues 작업은 외부 REST API가 특성을 수집한 후 기본값으로 특성을 수정하고 재정의하는 응답을 반환하도록 지정합니다. REST API는 새 특성을 추가할 수 없습니다. 반환되지만 특성 컬렉션의 일부가 아닌 추가 특성은 무시됩니다.
HTTP/1.1 200 OK
{
"data": {
"@odata.type": "microsoft.graph.onAttributeCollectionSubmitResponseData",
"actions": [
{
"@odata.type": "microsoft.graph.attributeCollectionSubmit.modifyAttributeValues",
"attributes": {
"key1": "value1,value2,value3",
"key2": true
}
}
]
}
}
showBlockPage 작업은 외부 REST API가 차단 응답을 반환하도록 지정합니다.
HTTP/1.1 200 OK
{
"data": {
"@odata.type": "microsoft.graph.onAttributeCollectionSubmitResponseData",
"actions": [
{
"@odata.type": "microsoft.graph.attributeCollectionSubmit.showBlockPage",
"message": "Your access request is already processing. You'll be notified when your request has been approved."
}
]
}
}
showValidationError 작업은 REST API가 유효성 검사 오류와 적절한 메시지 및 상태 코드를 반환하도록 지정합니다.
HTTP/1.1 200 OK
{
"data": {
"@odata.type": "microsoft.graph.onAttributeCollectionSubmitResponseData",
"actions": [
{
"@odata.type": "microsoft.graph.attributeCollectionSubmit.showValidationError",
"message": "Please fix the below errors to proceed.",
"attributeErrors": {
"city": "City cannot contain any numbers",
"extension_<appid>_graduationYear": "Graduation year must be at least 4 digits"
}
}
]
}
}
피드백
출시 예정: 2024년 내내 콘텐츠에 대한 피드백 메커니즘으로 GitHub 문제를 단계적으로 폐지하고 이를 새로운 피드백 시스템으로 바꿀 예정입니다. 자세한 내용은 다음을 참조하세요. https://aka.ms/ContentUserFeedback
다음에 대한 사용자 의견 제출 및 보기