Share via

Menyiapkan ID Microsoft Entra untuk autentikasi klien

  • Artikel

Peringatan

Saat ini, autentikasi klien Microsoft Entra dan Layanan Token Identitas Terkelola saling tidak kompatibel di Linux.

Untuk kluster yang berjalan di Azure, ID Microsoft Entra disarankan untuk mengamankan akses ke titik akhir manajemen. Artikel ini menjelaskan cara menyiapkan ID Microsoft Entra untuk mengautentikasi klien untuk kluster Service Fabric.

Di Linux, Anda harus menyelesaikan langkah-langkah berikut sebelum Anda membuat klaster. Di Windows, Anda juga memiliki opsi untuk mengonfigurasi autentikasi Microsoft Entra untuk kluster yang ada.

Dalam artikel ini, istilah "aplikasi" mengacu pada aplikasi Microsoft Entra, bukan aplikasi Service Fabric; perbedaan dibuat jika perlu. MICROSOFT Entra ID memungkinkan organisasi (dikenal sebagai penyewa) untuk mengelola akses pengguna ke aplikasi.

Kluster Service Fabric menawarkan beberapa titik masuk ke fungsionalitas manajemennya, termasuk Service Fabric Explorer dan Visual Studio berbasis web. Akibatnya, Anda akan membuat dua aplikasi Microsoft Entra untuk mengontrol akses ke kluster: satu aplikasi web dan satu aplikasi asli. Setelah aplikasi dibuat, Anda akan menetapkan pengguna ke peran baca-saja dan admin.

Catatan

Saat ini, Service Fabric tidak mendukung autentikasi Microsoft Entra untuk penyimpanan.

Catatan

Ini adalah masalah yang diketahui bahwa aplikasi dan simpul pada kluster berkemampuan ID Microsoft Entra Linux tidak dapat dilihat di Portal Microsoft Azure.

Catatan

MICROSOFT Entra ID sekarang mengharuskan domain penerbit aplikasi (pendaftaran aplikasi) diverifikasi atau penggunaan skema default. Lihat Mengonfigurasi domain penerbit aplikasi dan AppId Uri dalam aplikasi penyewa tunggal memerlukan penggunaan skema default atau domain terverifikasi untuk informasi tambahan.

Catatan

Mulai dari Service Fabric 11.0, Service Fabric Explorer memerlukan URI Pengalihan aplikasi satu halaman alih-alih URI Pengalihan Web.

Prasyarat

Di artikel ini, kami anggap Anda telah membuat penyewa. Jika belum, mulailah dengan membaca Cara mendapatkan penyewa Microsoft Entra. Untuk menyederhanakan beberapa langkah yang terlibat dalam mengonfigurasi ID Microsoft Entra dengan kluster Service Fabric, kami telah membuat sekumpulan skrip Windows PowerShell. Beberapa tindakan memerlukan akses tingkat administratif ke ID Microsoft Entra. Jika skrip mengalami kesalahan 401 atau 403 'Authorization_RequestDenied', administrator perlu menjalankan skrip.

  1. Autentikasi dengan izin administratif Azure.
  2. Kloning repositori ke komputer Anda.
  3. Pastikan Anda memiliki semua persyaratan untuk skrip yang terpasang.

Membuat aplikasi Microsoft Entra dan menetapkan pengguna ke peran

Kita akan menggunakan skrip untuk membuat dua aplikasi Microsoft Entra untuk mengontrol akses ke kluster: satu aplikasi web dan satu aplikasi asli. Setelah Anda membuat aplikasi untuk mewakili klaster Anda, Anda akan membuat pengguna untuk peran yang didukung oleh Service Fabric: baca-saja dan admin.

SetupApplications.ps1

Jalankan SetupApplications.ps1 dan sediakan ID penyewa, nama kluster, URI aplikasi web, dan URL balasan aplikasi web sebagai parameter. Gunakan -remove untuk menghapus pendaftaran aplikasi. Menggunakan -logFile <log file path> menghasilkan log transkrip. Lihat bantuan skrip (help .\setupApplications.ps1 -full) untuk informasi tambahan. Skrip membuat aplikasi web dan asli untuk mewakili kluster Service Fabric Anda. Dua entri pendaftaran aplikasi baru dalam format berikut:

  • ClusterName_Cluster
  • ClusterName_Client

Catatan

Untuk cloud nasional (misalnya Azure Government, Microsoft Azure yang dioperasikan oleh 21Vianet), Anda juga harus menentukan -Location parameter .

Parameter

  • tenantId: Anda dapat mencari TenantId Anda dengan menjalankan perintah PowerShell Get-AzureSubscription. Menjalankan perintah ini akan menampilkan TenantId untuk setiap langganan.

  • clusterName:ClusterName digunakan untuk mengawali aplikasi Microsoft Entra yang dibuat oleh skrip. Tidak perlu mencocokkan nama kluster yang sebenarnya dengan tepat. Ini dimaksudkan hanya untuk mempermudah pemetaan artefak Microsoft Entra ke kluster Service Fabric yang digunakan.

  • SpaApplicationReplyUrl:SpaApplicationReplyUrl adalah titik akhir default yang dikembalikan ID Microsoft Entra kepada pengguna Anda setelah mereka selesai masuk. Atur titik akhir ini sebaga titik akhir Service Fabric Explorer untuk klaster Anda. Jika Anda membuat aplikasi Microsoft Entra untuk mewakili kluster yang ada, pastikan URL ini cocok dengan titik akhir kluster yang ada. Jika Anda membuat aplikasi untuk kluster baru, rencanakan titik akhir untuk kluster Anda dan pastikan untuk tidak menggunakan titik akhir kluster yang ada. Secara default, titik akhir Service Fabric Explorer adalah: https://<cluster_domain>:19080/Explorer/index.html

  • webApplicationUri:WebApplicationUri adalah URI dari 'domain terverifikasi' atau URI menggunakan format skema API API://{{tenant Id}}/{{nama kluster}}. Lihat AppId Uri dalam aplikasi penyewa tunggal memerlukan penggunaan skema default atau domain terverifikasi untuk informasi tambahan.

    Contoh skema API: API://0e3d2646-78b3-4711-b8be-74a381d9890c/mysftestcluster

Contoh SetupApplications.ps1

# if using cloud shell
# cd clouddrive 
# git clone https://github.com/Azure-Samples/service-fabric-aad-helpers
# cd service-fabric-aad-helpers
# code .

$tenantId = '0e3d2646-78b3-4711-b8be-74a381d9890c'
$clusterName = 'mysftestcluster'
$spaApplicationReplyUrl = 'https://mysftestcluster.eastus.cloudapp.azure.com:19080/Explorer/index.html' # <--- client browser redirect url
#$webApplicationUri = 'https://mysftestcluster.contoso.com' # <--- must be verified domain due to AAD changes
$webApplicationUri = "API://$tenantId/$clusterName" # <--- doesn't have to be verified domain

$configObj = .\SetupApplications.ps1 -TenantId $tenantId `
  -ClusterName $clusterName `
  -SpaApplicationReplyUrl $spaApplicationReplyUrl `
  -AddResourceAccess `
  -WebApplicationUri $webApplicationUri `
  -Verbose

Skrip menghasilkan variabel $configObj untuk perintah berikutnya dan mencetak JSON yang diperlukan oleh templat ARM. Salin output JSON dan gunakan saat membuat atau memodifikasi kluster yang ada membuat kluster yang diaktifkan ID Microsoft Entra Anda.

Contoh output SetupApplications.ps1

Name                           Value
----                           -----
WebAppId                       f263fd84-ec9e-44c0-a419-673b1b9fd345
TenantId                       0e3d2646-78b3-4711-b8be-74a381d9890c
ServicePrincipalId             3d10f55b-1876-4a62-87db-189bfc54a9f2
NativeClientAppId              b22cc0e2-7c4e-480c-89f5-25f768ecb439

-----ARM template-----
"azureActiveDirectory": {
  "tenantId":"0e3d2646-78b3-4711-b8be-74a381d9890c",
  "clusterApplication":"f263fd84-ec9e-44c0-a419-673b1b9fd345",
  "clientApplication":"b22cc0e2-7c4e-480c-89f5-25f768ecb439"
},

objek parameter azureActiveDirectory JSON

"azureActiveDirectory": {
  "tenantId":"<guid>",
  "clusterApplication":"<guid>",
  "clientApplication":"<guid>"
},

SetupUser.ps1

SetupUser.ps1 digunakan untuk menambahkan akun pengguna ke pendaftaran aplikasi yang baru dibuat menggunakan variabel output $configObj dari atas. Tentukan nama pengguna untuk akun pengguna yang akan dikonfigurasi dengan pendaftaran aplikasi dan tentukan 'isAdmin' untuk izin administratif. Jika akun pengguna tersebut baru, berikan juga kata sandi sementara untuk pengguna baru. Kata sandi perlu diubah pada log masuk pertama. Jika Anda menggunakan '-remove', Anda akan menghapus akun pengguna, bukan hanya pendaftaran aplikasi.

contoh pengguna SetupUser.ps1 (baca)

.\SetupUser.ps1 -ConfigObj $configobj `
  -UserName 'TestUser' `
  -Password 'P@ssword!123' `
  -Verbose

contoh admin SetupUser.ps1 (baca/tulis)

.\SetupUser.ps1 -ConfigObj $configobj `
  -UserName 'TestAdmin' `
  -Password 'P@ssword!123' `
  -IsAdmin `
  -Verbose

SetupClusterResource.ps1

SetupClusterResource.ps1 secara opsional dapat digunakan untuk mengekspor templat ARM sumber daya kluster yang ada, menambahkan/memodifikasi konfigurasi 'azureActiveDirectory', dan menyebarkan ulang templat. Gunakan '-Whatif' untuk hanya mengekspor dan memodifikasi templat tanpa menyebarkan ulang perubahan konfigurasi. Skrip ini memang memerlukan modul Azure 'Az' dan nama grup sumber daya untuk kluster.

Contoh SetupClusterResource.ps1 -whatIf

# requires azure module 'az'
# install-module az
$resourceGroupName = 'mysftestcluster'
.\SetupClusterResource.ps1 -configObj $configObj `
  -resourceGroupName $resourceGroupName `
  -WhatIf

Setelah templat diverifikasi dan siap diproses, jalankan ulang skrip tanpa '-WhatIf' atau gunakan cmdlet powershell 'New-AzResourceGroupDeployment' untuk menyebarkan templat.

contoh SetupClusterResource.ps1

$resourceGroupName = 'mysftestcluster'
.\SetupClusterResource.ps1 -configObj $configObj `
  -resourceGroupName $resourceGroupName

Catatan

Perbarui templat atau skrip ARM provisi kluster dengan perubahan konfigurasi Microsoft Entra sumber daya kluster baru.

Anda mungkin perlu 'Memberikan persetujuan admin' untuk 'Izin API' yang sedang dikonfigurasi. Buka bilah Pendaftaran aplikasi Azure dan tambahkan nama kluster ke filter. Untuk kedua pendaftaran, buka 'Izin API', dan pilih 'Berikan persetujuan admin untuk' jika tersedia.

Screenshot that shows Grant admin consent selected on the Azure App registrations blade.

Screenshot that shows the Grant admin consent confirmation with Yes highlighted.

Memverifikasi Konfigurasi Microsoft Entra

Buka URL Service Fabric Explorer (SFX). Ini harus sama dengan parameter spaApplicationReplyUrl. Dialog autentikasi Azure akan ditampilkan. Masuk dengan akun yang dikonfigurasi dengan konfigurasi Microsoft Entra baru. Verifikasi bahwa akun administrator memiliki akses baca/tulis dan bahwa pengguna telah memiliki akses baca. Setiap modifikasi pada kluster, misalnya melakukan tindakan, adalah tindakan administratif.

Bantuan pemecahan masalah dalam menyiapkan ID Microsoft Entra

Menyiapkan ID Microsoft Entra dan menggunakannya bisa menjadi tantangan, jadi berikut adalah beberapa petunjuk tentang apa yang dapat Anda lakukan untuk men-debug masalah. Pengelogan transkrip PowerShell dapat diaktifkan dengan menggunakan argumen '-logFile' pada skrip 'SetupApplications.ps1' dan 'SetupUser.ps1' untuk meninjau output.

Catatan

Dengan migrasi platform Identitas (ADAL ke MSAL), penghentian AzureRM demi Azure AZ, dan mendukung beberapa versi PowerShell, dependensi mungkin tidak selalu benar atau terbaru yang menyebabkan kesalahan dalam eksekusi skrip. Menjalankan skrip dan perintah PowerShell dari Azure Cloud Shell akan mengurangi potensi kesalahan pada autentikasi otomatis sesi dan identitas terkelola.

Button to launch the Azure Cloud Shell.

Request_BadRequest

Masalah

Bukan pembaruan referensi yang valid. Kode status HTTP: 400.

VERBOSE: POST with 157-byte payload
VERBOSE: received -byte response of content type application/json
>> TerminatingError(Invoke-WebRequest): "{"error":{"code":"Request_BadRequest","message":"Not a valid reference update.","innerError":{"date":"2022-09-11T22:17:16","request-id":"61fadb2a-478b-4483-8f23-d17e13732104","client-request-id":"61fadb2a-478b-4483-8f23-d17e13732104"}}}"
confirm-graphApiRetry returning:True
VERBOSE: invoke-graphApiCall status: 400
exception:
Response status code doesn't indicate success: 400 (Bad Request).

Invoke-WebRequest: /home/<user>/clouddrive/service-fabric-aad-helpers/Common.ps1:239
Line |
 239 |  …   $result = Invoke-WebRequest $uri -Method $method -Headers $headers  …
     |                ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     | {"error":{"code":"Request_BadRequest","message":"Not a valid reference update.","innerError":{"date":"2022-09-11T22:17:16","request-id":"61fadb2a-478b-4483-8f23-d17e13732104","client-request-id":"61fadb2a-478b-4483-8f23-d17e13732104"}}}

at invoke-graphApiCall, /home/<user>/clouddrive/service-fabric-aad-helpers/Common.ps1: line 239
at invoke-graphApi, /home/<user>/clouddrive/service-fabric-aad-helpers/Common.ps1: line 275
at add-roleAssignment, /home/<user>/clouddrive/service-fabric-aad-helpers/SetupUser.ps1: line 193
at add-user, /home/<user>/clouddrive/service-fabric-aad-helpers/SetupUser.ps1: line 244
at enable-AADUser, /home/<user>/clouddrive/service-fabric-aad-helpers/SetupUser.ps1: line 178
at main, /home/<user>/clouddrive/service-fabric-aad-helpers/SetupUser.ps1: line 136
at <ScriptBlock>, /home/<user>/clouddrive/service-fabric-aad-helpers/SetupUser.ps1: line 378
at <ScriptBlock>, /home/<user>/clouddrive/aad-test.ps1: line 43
at <ScriptBlock>, <No file>: line 1
WARNING: invoke-graphApiCall response status: 400
invoke-graphApi count:0 statuscode:400 -uri https://graph.microsoft.com/v1.0/0e3d2646-78b3-4711-b8be-74a381d9890c/servicePrincipals/3d10f55b-1876-4a62-87db-189bfc54a9f2/appRoleAssignedTo -headers System.Collections.Hashtable -body System.Collections.Hashtable -method post
confirm-graphApiRetry returning:True

Alasan

Perubahan konfigurasi belum disebarluaskan. Skrip mencoba kembali pada permintaan tertentu dengan kode status HTTP 400 dan 404.

Solusi

Skrip mencoba kembali permintaan tertentu dengan kode status HTTP 400 dan 404 upto menyediakan '-timeoutMin' yang secara default 5 menit. Skrip dapat dijalankan ulang sesuai kebutuhan.

Service Fabric Explorer meminta Anda untuk memilih sertifikat

Masalah

Setelah Anda berhasil masuk ke ID Microsoft Entra di Service Fabric Explorer, browser kembali ke halaman beranda tetapi pesan meminta Anda untuk memilih sertifikat.

SFX certificate dialog

Alasan

Pengguna tidak diberi peran dalam aplikasi kluster ID Microsoft Entra. Dengan demikian, autentikasi Microsoft Entra gagal pada kluster Service Fabric. Service Fabric Explorer kembali ke autentikasi sertifikat.

Solusi

Ikuti instruksi untuk menyiapkan ID Microsoft Entra, dan tetapkan peran pengguna. Selain itu, sebaiknya aktifkan "Penetapan pengguna diperlukan untuk mengakses aplikasi," seperti yang dilakukan SetupApplications.ps1.

Koneksi dengan PowerShell gagal dengan kesalahan: "Kredensial yang ditentukan tidak valid"

Masalah

Saat Anda menggunakan PowerShell untuk menyambungkan ke kluster dengan menggunakan mode keamanan "AzureActiveDirectory", setelah Anda berhasil masuk ke ID Microsoft Entra, koneksi gagal dengan kesalahan: "Kredensial yang ditentukan tidak valid."

Solusi

Solusi ini sama dengan yang sebelumnya.

Service Fabric Explorer mengembalikan kegagalan saat Anda masuk: "AADSTS50011"

Masalah

Ketika Anda mencoba masuk ke ID Microsoft Entra di Service Fabric Explorer, halaman mengembalikan kegagalan: "AADSTS50011: Url> alamat <balasan tidak cocok dengan alamat balasan yang dikonfigurasi untuk aplikasi: <guid>."

SFX reply address doesn't match

Alasan

Aplikasi kluster (web) yang mewakili Service Fabric Explorer mencoba mengautentikasi terhadap ID Microsoft Entra, dan sebagai bagian dari permintaan, aplikasi tersebut menyediakan URL pengembalian pengalihan. Tetapi URL tidak tercantum dalam daftar URL BALASAN aplikasi Microsoft Entra.

Solusi

Pada halaman pendaftaran aplikasi Microsoft Entra untuk kluster Anda, pilih Autentikasi, dan di bawah bagian URI Pengalihan, tambahkan URL Service Fabric Explorer ke daftar. Simpan perubahan Anda.

Web application reply URL

Koneksi ke kluster menggunakan autentikasi Microsoft Entra melalui PowerShell memberikan kesalahan saat Anda masuk: "AADSTS50011"

Masalah

Ketika Anda mencoba menyambungkan ke kluster Service Fabric menggunakan MICROSOFT Entra ID melalui PowerShell, halaman masuk mengembalikan kegagalan: "AADSTS50011: Url balasan yang ditentukan dalam permintaan tidak cocok dengan url balasan yang dikonfigurasi untuk aplikasi: <guid>."

Alasan

Mirip dengan masalah sebelumnya, PowerShell mencoba mengautentikasi terhadap ID Microsoft Entra, yang menyediakan URL pengalihan yang tidak tercantum dalam daftar URL Balasan aplikasi Microsoft Entra.

Solusi

Gunakan proses yang sama seperti dalam masalah sebelumnya, tetapi URL harus diatur menjadi urn:ietf:wg:oauth:2.0:oob, pengalihan khusus untuk autentikasi baris perintah.

Eksekusi skrip mengakibatkan kesalahan dalam kesalahan Otorisasi

Masalah

Skrip PowerShell mungkin gagal melakukan semua perintah REST yang diperlukan untuk menyelesaikan konfigurasi Microsoft Entra dengan kesalahan "Authorization_RequestDenied","Hak istimewa yang tidak mencukupi untuk menyelesaikan operasi". Contoh kesalahan:

Invoke-WebRequest: /home/<user>/clouddrive/service-fabric-aad-helpers/Common.ps1:239
Line |
 239 |  …   $result = Invoke-WebRequest $uri -Method $method -Headers $headers  …
     |                ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     | {"error":{"code":"Authorization_RequestDenied","message":"Insufficient privileges to complete the
     | operation.","innerError":{"date":"2022-08-29T14:46:37","request-id":"c4fd3acc-1558-4950-8028-68bb058f7bf0","client-request-id":"c4fd3acc-1558-4950-8028-68bb058f7bf0"}}}
...
invoke-graphApi count:0 statuscode:403 -uri https://graph.microsoft.com/v1.0/72f988bf-86f1-41af-91ab-2d7cd011db47/oauth2PermissionGrants -headers System.Collections.Hashtable -body System.Collections.Hashtable -method post
Write-Error: /home/<user>/clouddrive/service-fabric-aad-helpers/SetupApplications.ps1:364
Line |
 364 |      assert-notNull $result "aad app service principal oauth permissio …
     |      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     | aad app service principal oauth permissions User.Read configuration failed

Write-Error: /home/<user>/clouddrive/service-fabric-aad-helpers/SetupApplications.ps1:656
Line |
 656 |  main
     |  ~~~~
     | exception:  exception: assertion failure: object: message:aad app service principal oauth permissions User.Read configuration failed  Exception:
     | /home/<user>/clouddrive/service-fabric-aad-helpers/Common.ps1:22 Line |   22 |          throw "assertion failure: object:$obj message:$msg"      |         
     | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~      | assertion failure: object: message:aad app service principal oauth permissions User.Read configuration failed  
...

Alasan

Kesalahan ini dikembalikan ketika akun pengguna yang menjalankan skrip tidak memiliki izin untuk melakukan panggilan REST. Hal ini dapat terjadi jika pengguna tidak memiliki izin Administrator/Kelola/Tulis pada objek yang sedang dibuat atau dimodifikasi.

Solusi

Bekerja sama dengan Administrator penyewa Azure atau ID Microsoft Entra untuk menyelesaikan semua tindakan yang tersisa. Skrip yang disediakan idempogen, sehingga dapat dijalankan kembali untuk menyelesaikan proses.

Koneksi kluster dengan menggunakan autentikasi Microsoft Entra melalui PowerShell

Untuk menyambungkan klaster Service Fabric, gunakan contoh perintah PowerShell berikut ini:

Connect-ServiceFabricCluster -ConnectionEndpoint <endpoint> -KeepAliveIntervalInSec 10 -AzureActiveDirectory -ServerCertThumbprint <thumbprint>

Untuk mempelajari selengkapnya, lihat cmdlet Connect-ServiceFabricCluster.

Dapatkah saya menggunakan kembali penyewa Microsoft Entra yang sama di beberapa kluster?

Ya. Tapi ingatlah untuk menambahkan URL Service Fabric Explorer ke aplikasi klaster (web) Anda. Jika tidak, Service Fabric Explorer tidak akan berfungsi.

Mengapa saya masih memerlukan sertifikat server saat ID Microsoft Entra diaktifkan?

FabricClient dan FabricGateway melakukan otentikasi bersama. Selama autentikasi Microsoft Entra, integrasi Microsoft Entra menyediakan identitas klien ke server, dan sertifikat server digunakan oleh klien untuk memverifikasi identitas server. Untuk informasi selengkapnya tentang sertifikat Service Fabric, lihat sertifikat X.509 dan Service Fabric.

Langkah berikutnya

Setelah menyiapkan aplikasi Microsoft Entra dan mengatur peran untuk pengguna, konfigurasikan dan sebarkan kluster.