Referensi penyedia klaim kustom

Artikel
07/27/2024

Dalam artikel referensi ini, Anda dapat mempelajari tentang skema REST API dan struktur kebijakan pemetaan klaim untuk peristiwa penyedia klaim kustom.

Peristiwa mulai penerbitan token

Peristiwa penerbitan token penyedia klaim kustom memungkinkan Anda memperkaya atau menyesuaikan token aplikasi dengan informasi dari sistem eksternal. Informasi ini tidak dapat disimpan sebagai bagian dari profil pengguna di direktori Microsoft Entra.

Gambaran umum komponen

Untuk menyiapkan dan, mengintegrasikan ekstensi kustom dengan aplikasi Anda mengharuskan beberapa komponen terhubung. Diagram berikut menunjukkan tampilan tingkat tinggi dari titik konfigurasi, dan hubungan yang dibuat untuk mengimplementasikan ekstensi kustom.

Anda harus memiliki titik akhir REST API yang tersedia untuk umum. Dalam diagram ini, ia diwakili oleh Azure Function. REST API menghasilkan dan mengembalikan klaim kustom ke ekstensi kustom. Ini dikaitkan dengan pendaftaran aplikasi Microsoft Entra.
Anda harus mengonfigurasi ekstensi kustom di MICROSOFT Entra ID, yang dikonfigurasi untuk terhubung ke API Anda.
Anda memerlukan aplikasi yang menerima token yang disesuaikan. Misalnya https://jwt.ms aplikasi web milik Microsoft yang menampilkan konten token yang didekodekan.
Aplikasi, seperti https://jwt.ms harus didaftarkan ke MICROSOFT Entra ID menggunakan pendaftaran aplikasi.
Anda harus membuat hubungan antara aplikasi dan ekstensi kustom Anda.
Anda dapat secara opsional mengamankan Azure Function dengan penyedia autentikasi, dalam artikel ini kami menggunakan ID Microsoft Entra Anda.

REST API

Titik akhir REST API Anda bertanggung jawab untuk berinteraksi dengan layanan hilir. Misalnya, database, REST API lainnya, direktori LDAP, atau penyimpanan lain yang berisi atribut yang ingin Anda tambahkan ke konfigurasi token.

REST API mengembalikan respons HTTP ke MICROSOFT Entra ID yang berisi atribut . Atribut yang dikembalikan oleh REST API Anda tidak secara otomatis ditambahkan ke dalam token. Sebagai gantinya, kebijakan pemetaan klaim aplikasi harus dikonfigurasi agar atribut apa pun disertakan dalam token. Di ID Microsoft Entra, kebijakan pemetaan klaim memodifikasi klaim yang dikeluarkan dalam token yang dikeluarkan untuk aplikasi tertentu.

Skema REST API

Untuk mengembangkan REST API Anda sendiri untuk peristiwa mulai penerbitan token, gunakan kontrak data REST API berikut. Skema menjelaskan kontrak untuk merancang penangan permintaan dan respons.

Ekstensi 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. Nilai id dalam JSON berikut adalah aplikasi Microsoft yang mewakili layanan peristiwa autentikasi Microsoft Entra. Atribut JSON dapat digunakan untuk melakukan logika tambahan oleh API Anda. Permintaan ke API Anda dalam format berikut:

POST https://your-api.com/endpoint

{
    "type": "microsoft.graph.authenticationEvent.tokenIssuanceStart",
    "source": "/tenants/<Your tenant GUID>/applications/<Your Test Application App Id>",
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartCalloutData",
        "tenantId": "<Your tenant GUID>",
        "authenticationEventListenerId": "<GUID>",
        "customAuthenticationExtensionId": "<Your custom extension ID>",
        "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"
            },
            "user": {
                "companyName": "Casey Jensen",
                "createdDateTime": "2016-03-01T15:23:40Z",
                "displayName": "Casey Jensen",
                "givenName": "Casey",
                "id": "90847c2a-e29d-4d2f-9f54-c5b4d3f26471", // Client ID representing the Microsoft Entra authentication events service
                "mail": "casey@contoso.com",
                "onPremisesSamAccountName": "caseyjensen",
                "onPremisesSecurityIdentifier": "<Enter Security Identifier>",
                "onPremisesUserPrincipalName": "Casey Jensen",
                "preferredLanguage": "en-us",
                "surname": "Jensen",
                "userPrincipalName": "casey@contoso.com",
                "userType": "Member"
            }
        }
    }
}

Format respons REST API yang diharapkan Azure dalam format berikut, di mana klaim DateOfBirth dan CustomRoles dikembalikan ke Azure:

{
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData",
        "actions": [
            {
                "@odata.type": "microsoft.graph.tokenIssuanceStart.provideClaimsForToken",
                "claims": {
                    "DateOfBirth": "01/01/2000",
                    "CustomRoles": [
                        "Writer",
                        "Editor"
                    ]
                }
            }
        ]
    }
}

Ketika pengguna B2B dari organisasi Fabrikam mengautentikasi ke organisasi Contoso, payload permintaan yang dikirim ke REST API memiliki user elemen dalam format berikut:

"user": {
    "companyName": "Fabrikam",
    "createdDateTime": "2022-07-15T00:00:00Z",
    "displayName": "John Wright",
    "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "mail": "johnwright@fabrikam.com",
    "preferredDataLocation": "EUR",
    "userPrincipalName": "johnwright_fabrikam.com#EXT#@contoso.onmicrosoft.com",
    "userType": "Guest"
}

Tipe data yang didukung

Tabel berikut ini memperlihatkan jenis data yang didukung oleh penyedia klaim kustom untuk peristiwa mulai penerbitan token:

Jenis Data	Didukung
String	Benar
Array string	Benar
Boolean	Salah
JSON	Salah

Batasan ukuran klaim

Ukuran klaim maksimum yang dapat dikembalikan penyedia klaim dibatasi hingga 3KB. Ini adalah jumlah semua pasangan kunci dan nilai yang dikembalikan oleh REST API.

Kebijakan pemetaan klaim

Di ID Microsoft Entra, kebijakan pemetaan klaim memodifikasi klaim yang dikeluarkan dalam token yang dikeluarkan untuk aplikasi tertentu. Ini termasuk klaim dari penyedia klaim kustom Anda, dan mengeluarkannya ke dalam token.

{
    "ClaimsMappingPolicy": {
        "Version": 1,
        "IncludeBasicClaimSet": "true",
        "ClaimsSchema": [{
            "Source": "CustomClaimsProvider",
            "ID": "dateOfBirth",
            "JwtClaimType": "birthdate"
        },
        {
            "Source": "CustomClaimsProvider",
            "ID": "customRoles",
            "JwtClaimType": "my_roles"
        },
        {
            "Source": "CustomClaimsProvider",
            "ID": "correlationId",
            "JwtClaimType": "correlation_Id"
        },
        {
            "Source": "CustomClaimsProvider",
            "ID": "apiVersion",
            "JwtClaimType": "apiVersion"
        },
        {
            "Value": "tokenaug_V2",
            "JwtClaimType": "policy_version"
        }]
    }
}

Elemen ClaimsSchema berisi daftar klaim yang akan dipetakan dengan atribut berikut:

Sumber menjelaskan sumber atribut , CustomClaimsProvider. Perhatikan, elemen terakhir berisi nilai tetap dengan versi kebijakan, untuk tujuan pengujian. Dengan demikian, atribut dihilangkan source .
ID adalah nama klaim yang dikembalikan dari Fungsi Azure yang Anda buat.

Penting

Nilai atribut ID peka huruf besar/kecil. Pastikan Anda mengetikkan nama klaim persis seperti yang dikembalikan oleh Azure Function.
JwtClaimType adalah nama klaim opsional dalam token yang dipancarkan untuk aplikasi OpenID Connect. Ini memungkinkan Anda untuk memberikan nama berbeda yang dikembalikan dalam token JWT. Misalnya, jika respons API memiliki ID nilai dateOfBirth, respons api dapat dipancarkan seperti birthdate dalam token.

Setelah Anda membuat kebijakan pemetaan klaim, langkah selanjutnya adalah mengunggahnya ke penyewa Microsoft Entra Anda. Gunakan claimsMappingPolicy Graph API berikut di penyewa Anda.

Penting

Elemen definisi harus berupa array dengan nilai string tunggal. String harus berupa versi string dan lolos dari kebijakan pemetaan klaim Anda. Anda dapat menggunakan alat seperti https://jsontostring.com/ untuk merangkai kebijakan pemetaan klaim Anda.

Bagikan melalui