OnAttributeCollectionStart 이벤트 참조에 대한 사용자 지정 확장(미리 보기)

적용: 인력 테넌트 외부 테넌트(자세히 알아보기)

고객 셀프 서비스 등록 사용자 흐름에 대한 등록 환경을 수정하려면 사용자 지정 인증 확장을 만들고 사용자 흐름의 특정 지점에서 호출할 수 있습니다. OnAttributeCollectionStart 이벤트는 특성 컬렉션 페이지가 렌더링되기 전에 특성 컬렉션 단계의 시작 부분에서 발생합니다. 이 이벤트를 통해 사용자로부터 특성을 수집하기 전에 작업을 정의할 수 있습니다. 예를 들어 사용자가 페더레이션 ID 이전자 메일에 따라 등록 흐름을 계속하지 못하도록 차단하거나 지정된 값으로 특성을 미리 채울 수 있습니다. 다음 작업을 구성할 수 있습니다.

• continueWithDefaultBehavior - 평소와 같이 특성 컬렉션 페이지를 렌더링합니다.
• setPreFillValues - 등록 양식의 특성을 미리 채웁니다.
• showBlockPage - 오류 메시지를 표시하고 사용자가 등록하지 못하도록 차단합니다.

이 문서에서는 OnAttributeCollectionStart 이벤트에 대한 REST API 스키마를 설명합니다. (OnAttributeCollectionSubmit 이벤트 대한 사용자 지정 확장에 관련된 문서도 참조하세요.)

팁

이 기능을 사용해 보려면 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.attributeCollectionStart",
  "source": "/tenants/aaaabbbb-0000-cccc-1111-dddd2222eeee/applications/<resourceAppguid>",
  "data": {
    "@odata.type": "microsoft.graph.onAttributeCollectionStartCalloutData",
    "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.onAttributeCollectionStartResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionStart.continueWithDefaultBehavior"
      }
    ]
  }
}

setPrefillValues 작업은 외부 REST API가 기본값으로 특성을 미리 채우기 위해 응답을 반환하도록 지정합니다. REST API는 새 특성을 추가할 수 없습니다. 반환되지만 특성 컬렉션의 일부가 아닌 추가 특성은 무시됩니다.

HTTP/1.1 200 OK

{
  "data": {
    "@odata.type": "microsoft.graph.onAttributeCollectionStartResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionStart.setPrefillValues",
        "inputs": {
          "key1": "value1,value2,value3",
          "key2": true
        }
      }
    ]
  }
}

showBlockPage 작업은 외부 REST API가 차단 응답을 반환하도록 지정합니다.

HTTP/1.1 200 OK

{
  "data": {
    "@odata.type": "microsoft.graph.onAttributeCollectionStartResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionStart.showBlockPage",
        "message": "Your access request is already processing. You'll be notified when your request has been approved."
      }
    ]
  }
}