Ekstensi Kustom untuk referensi peristiwa OnAttributeCollectionStart (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 OnAttributeCollectionStart terjadi di awal langkah pengumpulan atribut, sebelum halaman pengumpulan atribut dirender. Kejadian ini memungkinkan Anda menentukan tindakan sebelum atribut dikumpulkan dari pengguna. Misalnya, Anda dapat memblokir pengguna untuk melanjutkan alur pendaftaran berdasarkan identitas atau email federasi mereka, atau atribut awalan dengan nilai yang ditentukan. Tindakan berikut dapat dikonfigurasi:

• continueWithDefaultBehavior - Render halaman pengumpulan atribut seperti biasa.
• setPreFillValues - Atribut awalan dalam formulir pendaftaran.
• showBlockPage - Tampilkan pesan kesalahan dan blokir pengguna untuk mendaftar.

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

Tip

Untuk mencoba fitur ini, buka demo Woodgrove Groceries dan mulai kasus penggunaan "Atribut pendaftaran prepopulasi".

Skema REST API

Untuk mengembangkan REST API Anda sendiri untuk peristiwa mulai pengumpulan 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.

Atribut dalam permintaan mulai berisi nilai defaultnya. Untuk atribut dengan beberapa nilai, nilai dikirim sebagai string yang dibatasi koma. Karena atribut belum dikumpulkan dari pengguna, sebagian besar atribut tidak akan memiliki nilai yang ditetapkan.

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

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.onAttributeCollectionStartResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionStart.continueWithDefaultBehavior"
      }
    ]
  }
}

Tindakan setPrefillValues menentukan bahwa REST API eksternal mengembalikan respons ke atribut pra-isi dengan nilai default. 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.onAttributeCollectionStartResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionStart.setPrefillValues",
        "inputs": {
          "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.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."
      }
    ]
  }
}