Ekstensi Kustom untuk referensi peristiwa OnAttributeCollectionSubmit (pratinjau)

Berlaku untuk: Penyewa Tenaga Kerja Penyewa eksternal (pelajari lebih lanjut)

Untuk mengubah pengalaman pendaftaran untuk alur pengguna pendaftaran layanan mandiri pelanggan, Anda dapat membuat ekstensi autentikasi kustom dan memanggilnya di titik tertentu dalam alur pengguna. Peristiwa OnAttributeCollectionSubmit terjadi setelah pengguna memasukkan dan mengirimkan atribut dan dapat digunakan untuk memvalidasi informasi yang diberikan oleh pengguna. Misalnya, Anda dapat memvalidasi kode undangan atau nomor mitra, mengubah format alamat, memungkinkan pengguna untuk melanjutkan, atau menampilkan halaman validasi atau blokir. Tindakan berikut dapat dikonfigurasi:

• continueWithDefaultBehavior - Lanjutkan dengan alur pendaftaran.
• modifyAttributeValues - Timpa nilai yang dikirimkan pengguna dalam formulir pendaftaran.
• showValidationError - Mengembalikan kesalahan berdasarkan nilai yang dikirimkan.
• showBlockPage - Tampilkan pesan kesalahan dan blokir pengguna untuk mendaftar.

Artikel ini menjelaskan skema REST API untuk peristiwa OnAttributeCollectionSubmit. (Lihat juga artikel terkaitEkstensi Kustom untuk peristiwa OnAttributeCollectionStart.)

Tip

Untuk mencoba fitur ini, buka demo Woodgrove Groceries dan mulai kasus penggunaan "Validasi atribut pendaftaran", atau kasus penggunaan "Blokir pengguna agar tidak melanjutkan proses pendaftaran".

Skema REST API

Untuk mengembangkan REST API Anda sendiri untuk peristiwa pengiriman koleksi atribut, gunakan kontrak data REST API berikut. Skema menjelaskan kontrak untuk merancang penangan permintaan dan respons.

Ekstensi autentikasi kustom Anda di MICROSOFT Entra ID melakukan panggilan HTTP ke REST API Anda dengan payload JSON. Payload JSON berisi data profil pengguna, atribut konteks autentikasi, dan informasi tentang aplikasi yang ingin masuk pengguna. Atribut JSON dapat digunakan untuk melakukan logika tambahan oleh API Anda.

Permintaan ke REST API eksternal

Permintaan ke REST API Anda dalam format yang ditunjukkan di bawah ini. Dalam contoh ini, permintaan mencakup informasi identitas pengguna bersama dengan atribut bawaan (givenName dan companyName) dan atribut kustom (universityGroups, graduationYear, dan onMailingList).

Permintaan berisi atribut pengguna yang dipilih dalam alur pengguna untuk pengumpulan selama pendaftaran layanan mandiri, termasuk atribut bawaan (misalnya, givenName dan companyName) dan atribut kustom yang telah ditentukan (misalnya, universityGroups, graduationYear, dan onMailingList). REST API Anda tidak dapat menambahkan atribut baru.

Permintaan ini juga berisi identitas pengguna, termasuk email pengguna jika digunakan sebagai kredensial terverifikasi untuk mendaftar. Kata sandi tidak dikirim. Untuk atribut dengan beberapa nilai, nilai dikirim sebagai string yang dibatasi koma.

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

Respons dari REST API eksternal

MICROSOFT Entra ID mengharapkan respons REST API dalam format berikut. Jenis nilai respons cocok dengan jenis nilai permintaan, misalnya:

• Jika permintaan berisi atribut dengan , respons harus menyertakan graduationYear atribut dengan nilai bilangan bulat, seperti 2010.int64DirectoryAttributeValue@odata.typegraduationYear
• Jika permintaan berisi atribut dengan beberapa nilai yang ditentukan sebagai string yang dibatasi koma, respons harus berisi nilai dalam string yang dibatasi koma.

Tindakan continueWithDefaultBehavior menentukan bahwa REST API eksternal Anda mengembalikan respons kelanjutan.

HTTP/1.1 200 OK

{
  "data": {
    "@odata.type": "microsoft.graph.onAttributeCollectionSubmitResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionSubmit.continueWithDefaultBehavior"
      }
    ]
  }
}

Tindakan modifyAttributeValues menentukan bahwa REST API eksternal Anda mengembalikan respons untuk memodifikasi dan mengambil alih atribut dengan nilai default setelah atribut dikumpulkan. REST API Anda tidak dapat menambahkan atribut baru. Atribut tambahan apa pun yang dikembalikan tetapi itu bukan bagian dari koleksi atribut diabaikan.

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
        }
      }
    ]
  }
}

Tindakan showBlockPage menentukan bahwa REST API eksternal Anda mengembalikan respons pemblokiran.

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."
      }
    ]
  }
}

Tindakan showValidationError menentukan bahwa REST API Anda mengembalikan kesalahan validasi dan pesan dan kode status yang sesuai.

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