Memecahkan masalah API penyedia klaim kustom Anda

Peristiwa autentikasi dan penyedia klaim kustom memungkinkan Anda menyesuaikan pengalaman autentikasi Microsoft Entra dengan mengintegrasikan dengan sistem eksternal. Misalnya, Anda dapat membuat API penyedia klaim kustom dan mengonfigurasi aplikasi OpenID Connect atau aplikasi SAML untuk menerima token dengan klaim dari penyimpanan eksternal.

Perilaku kesalahan

Saat panggilan API gagal, perilaku kesalahannya adalah sebagai berikut:

• Untuk aplikasi OpenId Connect - ID Microsoft Entra mengalihkan pengguna kembali ke aplikasi klien dengan kesalahan. Token tidak ditambang.
• Untuk aplikasi SAML - ID Microsoft Entra menunjukkan layar kesalahan kepada pengguna dalam pengalaman autentikasi. Pengguna tidak dialihkan kembali ke aplikasi klien.

Kode kesalahan yang dikirim kembali ke aplikasi atau pengguna bersifat generik. Untuk memecahkan masalah, periksa log masuk untuk kode kesalahan.

Pencatatan

Untuk memecahkan masalah dengan titik akhir REST API penyedia klaim kustom Anda, REST API harus menangani pengelogan. Azure Functions dan platform pengembangan API lainnya menyediakan solusi pengelogan mendalam. Gunakan solusi tersebut untuk mendapatkan informasi terperinci tentang perilaku API Anda dan memecahkan masalah logika API Anda.

Log masuk Microsoft Entra

Tip

Langkah-langkah dalam artikel ini mungkin sedikit berbeda berdasarkan portal tempat Anda memulai.

Anda juga dapat menggunakan log masuk Microsoft Entra selain log REST API Anda, dan solusi diagnostik lingkungan hosting. Dengan menggunakan log masuk Microsoft Entra, Anda dapat menemukan kesalahan, yang dapat memengaruhi rincian masuk pengguna. Log masuk Microsoft Entra menyediakan informasi tentang status HTTP, kode kesalahan, durasi eksekusi, dan jumlah percobaan ulang yang terjadi API dipanggil oleh ID Microsoft Entra.

Log masuk Microsoft Entra juga terintegrasi dengan Azure Monitor. Anda dapat menyiapkan pemberitahuan dan pemantauan, memvisualisasikan data, dan berintegrasi dengan alat informasi keamanan dan manajemen peristiwa (SIEM). Misalnya, Anda dapat menyiapkan pemberitahuan jika jumlah kesalahan melebihi ambang tertentu yang Anda pilih.

Untuk mengakses log masuk Microsoft Entra:

1. Masuk ke pusat admin Microsoft Entra sebagai setidaknya Administrator Aplikasi Cloud.

2. Telusuri aplikasi Identity>Applications>Enterprise.

3. Pilih Log masuk, lalu pilih log masuk terbaru.

4. Untuk detail selengkapnya, pilih tab Peristiwa Autentikasi. Informasi yang terkait dengan panggilan REST API ekstensi autentikasi kustom ditampilkan, termasuk kode kesalahan apa pun.

   

Referensi kode kesalahan

Gunakan tabel berikut untuk mendiagnosis kode kesalahan.

Kode kesalahan	Nama kesalahan	Deskripsi
1003000	EventHandlerUnexpectedError	Terjadi kesalahan tak terduga saat memproses penanganan aktivitas.
1003001	CustomExtenstionUnexpectedError	Terjadi kesalahan tak terduga saat memanggil API ekstensi kustom.
1003002	CustomExtensionInvalidHTTPStatus	API ekstensi kustom mengembalikan kode status HTTP yang tidak valid. Periksa apakah API mengembalikan kode status yang diterima yang ditentukan untuk jenis ekstensi kustom tersebut.
1003003	CustomExtensionInvalidResponseBody	Ada masalah saat mengurai isi respons ekstensi kustom. Periksa apakah isi respons API berada dalam skema yang dapat diterima untuk jenis ekstensi kustom tersebut.
1003004	CustomExtensionThrottlingError	Ada terlalu banyak permintaan ekstensi kustom. Pengecualian ini dilemparkan untuk panggilan API ekstensi kustom saat batas pembatasan tercapai.
1003005	CustomExtensionTimedOut	Ekstensi kustom tidak merespons dalam batas waktu yang diizinkan. Periksa apakah API Anda merespons dalam batas waktu yang dikonfigurasi untuk ekstensi kustom. Ini juga dapat menunjukkan bahwa token akses tidak valid. Ikuti langkah-langkah untuk memanggil REST API Anda secara langsung.
1003006	CustomExtensionInvalidResponseContentType	Jenis konten respons ekstensi kustom bukan 'application/json'.
1003007	CustomExtensionNullClaimsResponse	API ekstensi kustom merespons dengan kantong klaim null.
1003008	CustomExtensionInvalidResponseApiSchemaVersion	API ekstensi kustom tidak merespons dengan apiSchemaVersion yang sama dengan yang dipanggil.
1003009	CustomExtensionEmptyResponse	Isi respons API ekstensi kustom null ketika itu tidak diharapkan.
1003010	CustomExtensionInvalidNumberOfActions	Respons API ekstensi kustom menyertakan jumlah tindakan yang berbeda dari yang didukung untuk jenis ekstensi kustom tersebut.
1003011	CustomExtensionNotFound	Ekstensi kustom yang terkait dengan pendengar peristiwa tidak dapat ditemukan.
1003012	CustomExtensionInvalidActionType	Ekstensi kustom mengembalikan jenis tindakan yang tidak valid yang ditentukan untuk jenis ekstensi kustom tersebut.
1003014	CustomExtensionIncorrectResourceIdFormat	Properti identifierUris dalam manifes untuk pendaftaran aplikasi untuk ekstensi kustom, harus dalam format "api://{nama domain yang sepenuhnya memenuhi syarat}/{appid}.
1003015	CustomExtensionDomainNameDoesNotMatch	targetUrl dan resourceId dari ekstensi kustom harus memiliki nama domain yang sepenuhnya memenuhi syarat yang sama.
1003016	CustomExtensionResourceServicePrincipalNotFound	AppId dari resourceId ekstensi kustom harus sesuai dengan perwakilan layanan nyata di penyewa.
1003017	CustomExtensionClientServicePrincipalNotFound	Perwakilan layanan sumber daya ekstensi kustom tidak ditemukan di penyewa.
1003018	CustomExtensionClientServiceDisabled	Perwakilan layanan sumber daya ekstensi kustom dinonaktifkan di penyewa ini.
1003019	CustomExtensionResourceServicePrincipalDisabled	Perwakilan layanan sumber daya ekstensi kustom dinonaktifkan di penyewa ini.
1003020	CustomExtensionIncorrectTargetUrlFormat	URL target dalam format yang tidak tepat. Ini harus berupa URL valid yang dimulai dengan https.
1003021	CustomExtensionPermissionNotGrantedToServicePrincipal	Perwakilan layanan tidak memiliki persetujuan admin untuk peran aplikasi Microsoft Graph CustomAuthenticationExtensions.Receive.Payload (juga dikenal sebagai izin aplikasi) yang diperlukan agar aplikasi menerima permintaan HTTP ekstensi autentikasi kustom.
1003022	CustomExtensionMsGraphServicePrincipalDisabledOrNotFound	Perwakilan layanan MS Graph dinonaktifkan atau tidak ditemukan di penyewa ini.
1003023	CustomExtensionBlocked	Titik akhir yang digunakan untuk ekstensi kustom diblokir oleh layanan.
1003024	CustomExtensionResponseSizeExceeded	Ukuran respons ekstensi kustom melebihi batas maksimum.
1003025	CustomExtensionResponseClaimsSizeExceededed	Ukuran total klaim dalam respons ekstensi kustom melebihi batas maksimum.
1003026	CustomExtensionNullOrEmptyClaimKeyNotSupported	API ekstensi kustom merespons dengan klaim yang berisi kunci null atau kosong'
1003027	CustomExtensionConnectionError	Kesalahan saat menyambungkan ke API ekstensi kustom.

Hubungi REST API Anda secara langsung

REST API Anda dilindungi oleh token akses Microsoft Entra. Anda dapat menguji API dengan;

• Mendapatkan token akses dengan pendaftaran aplikasi yang terkait dengan ekstensi autentikasi kustom
• Uji API Anda secara lokal menggunakan alat pengujian API.

Alat pengujian API

1. Untuk tujuan pengembangan dan pengujian lokal, buka local.settings.json dan ganti kode dengan JSON berikut:

   {
     "IsEncrypted": false,
     "Values": {
       "AzureWebJobsStorage": "",
       "AzureWebJobsSecretStorageType": "files",
       "FUNCTIONS_WORKER_RUNTIME": "dotnet",
       "AuthenticationEvents__BypassTokenValidation" : false
     }
   }
   

   Catatan

   Jika Anda menggunakan paket NuGet Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents , pastikan untuk mengatur "AuthenticationEvents__BypassTokenValidation" : true untuk tujuan pengujian lokal.

2. Menggunakan alat pengujian API pilihan Anda, buat permintaan HTTP baru dan atur metode HTTP ke POST.

3. Gunakan isi JSON berikut yang meniru permintaan yang dikirim microsoft Entra ID ke REST API Anda.

   {
       "type": "microsoft.graph.authenticationEvent.tokenIssuanceStart",
       "source": "/tenants/aaaabbbb-0000-cccc-1111-dddd2222eeee/applications/00001111-aaaa-2222-bbbb-3333cccc4444",
       "data": {
           "@odata.type": "microsoft.graph.onTokenIssuanceStartCalloutData",
           "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
           "authenticationEventListenerId": "11112222-bbbb-3333-cccc-4444dddd5555",
           "customAuthenticationExtensionId": "22223333-cccc-4444-dddd-5555eeee6666",
           "authenticationContext": {
               "correlationId": "aaaa0000-bb11-2222-33cc-444444dddddd",
               "client": {
                   "ip": "127.0.0.1",
                   "locale": "en-us",
                   "market": "en-us"
               },
               "protocol": "OAUTH2.0",
               "clientServicePrincipal": {
                   "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
                   "appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
                   "appDisplayName": "My Test application",
                   "displayName": "My Test application"
               },
               "resourceServicePrincipal": {
                   "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
                   "appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
                   "appDisplayName": "My Test application",
                   "displayName": "My Test application"
               },
               "user": {
                   "companyName": "Casey Jensen",
                   "createdDateTime": "2023-08-16T00:00:00Z",
                   "displayName": "Casey Jensen",
                   "givenName": "Casey",
                   "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
                   "mail": "casey@contoso.com",
                   "onPremisesSamAccountName": "Casey Jensen",
                   "onPremisesSecurityIdentifier": "<Enter Security Identifier>",
                   "onPremisesUserPrincipalName": "Casey Jensen",
                   "preferredLanguage": "en-us",
                   "surname": "Jensen",
                   "userPrincipalName": "casey@contoso.com",
                   "userType": "Member"
               }
           }
       }
   }
   

   Tip

   Jika Anda menggunakan token akses yang diperoleh dari ID Microsoft Entra, pilih Otorisasi lalu pilih Token pembawa, lalu tempelkan token akses yang Anda terima dari ID Microsoft Entra.

4. Pilih Kirim, dan Anda akan menerima respons JSON yang mirip dengan yang berikut ini:

   {
       "data": {
           "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData",
           "actions": [
               {
                   "@odata.type": "microsoft.graph.tokenIssuanceStart.provideClaimsForToken",
                   "claims": {
                       "customClaim1": "customClaimValue1",
                       "customClaim2": [
                           "customClaimString1",
                           "customClaimString2" 
                       ]
                   }
               }
   
           ]
       }
   }
   

Mendapatkan token akses

Setelah Anda memperoleh token akses, berikan header HTTP Authorization . Untuk mendapatkan token akses, ikuti langkah-langkah berikut:

1. Masuk ke pusat admin Microsoft Entra sebagai setidaknya Administrator Aplikasi Cloud.

2. Telusuri pendaftaran Aplikasi Aplikasi>Identitas>.

3. Pilih pendaftaran aplikasi API peristiwa autentikasi Azure Functions, yang sebelumnya dikonfigurasi dalam mengonfigurasi penyedia klaim kustom untuk peristiwa penerbitan token.

4. Salin ID aplikasi.

5. Jika Anda belum membuat rahasia aplikasi, ikuti langkah-langkah berikut:

   1. Pilih Sertifikat & rahasia>Rahasia>klien Rahasia klien baru.
   2. Tambahkan deskripsi untuk rahasia klien Anda.
   3. Pilih kedaluwarsa untuk rahasia atau tentukan masa pakai kustom.
   4. Pilih Tambahkan.
   5. Catat nilai rahasia untuk digunakan dalam kode aplikasi klien Anda. Nilai rahasia ini tidak pernah ditampilkan lagi setelah Anda meninggalkan halaman ini.

6. Dari menu, pilih Ekspos API dan salin nilai URI ID Aplikasi. Contohnya,api://contoso.azurewebsites.net/00001111-aaaa-2222-bbbb-3333cccc4444.

7. Buka alat pengujian API pilihan Anda dan buat kueri HTTP baru.

8. Ubah metode HTTP menjadi POST.

9. Masukkan URL berikut. {tenantID} Ganti dengan ID penyewa Anda.

   https://login.microsoftonline.com/{tenantID}/oauth2/v2.0/token
   

10. Di bawah Isi, pilih data formulir dan tambahkan kunci berikut:

    Tombol	Nilai
    grant_type	client_credentials
    client_id	ID Klien aplikasi Anda.
    client_secret	Rahasia Klien aplikasi Anda.
    scope	URI ID Aplikasi aplikasi Anda, lalu tambahkan .default. Misalnya: api://contoso.azurewebsites.net/00001111-aaaa-2222-bbbb-3333cccc4444/.default

11. Jalankan kueri HTTP dan salin access_token ke https://jwt.ms dalam aplikasi web.

12. Bandingkan iss dengan nama pengeluar sertifikat yang Anda konfigurasikan di API Anda.

13. Bandingkan aud dengan ID klien yang Anda konfigurasikan di API Anda.

Peningkatan performa umum

Salah satu masalah paling umum adalah BAHWA API penyedia klaim kustom Anda tidak merespons dalam batas waktu dua detik. Jika REST API Anda tidak merespons dalam percobaan ulang berikutnya, maka autentikasi gagal. Untuk meningkatkan performa REST API Anda, ikuti saran di bawah ini:

1. Jika API Anda mengakses API hilir apa pun, cache token akses yang digunakan untuk memanggil API ini, sehingga token baru tidak perlu diperoleh pada setiap eksekusi.
2. Masalah performa sering kali terkait dengan layanan hilir. Tambahkan pengelogan, yang merekam waktu proses untuk memanggil ke layanan hilir apa pun.
3. Jika Anda menggunakan penyedia cloud untuk menghosting API Anda, gunakan paket hosting yang menjaga API selalu "hangat". Untuk Azure Functions, ini dapat berupa paket Premium atau Paket khusus.
4. Jalankan pengujian integrasi otomatis untuk autentikasi Anda. Anda juga dapat menggunakan alat pengujian API untuk menguji performa API Anda saja.

Lihat juga

• Membuat REST API dengan peristiwa mulai penerbitan token
• Mengonfigurasi aplikasi SAML untuk menerima token dengan klaim dari penyimpanan eksternal
• Artikel referensi penyedia klaim kustom.