Bagikan melalui

Mengaktifkan aplikasi Java Spring Boot untuk memasukkan pengguna dan mengakses Microsoft Graph

Artikel ini menunjukkan aplikasi web Java Spring Boot yang memasukkan pengguna dan mendapatkan token akses untuk memanggil Microsoft Graph. Ini menggunakan pustaka klien Microsoft Entra ID Spring Boot Starter untuk Java untuk autentikasi, otorisasi, dan akuisisi token. Ini menggunakan Microsoft Graph SDK untuk Java untuk mendapatkan data dari Graph.

Diagram berikut menunjukkan topologi aplikasi:

Diagram that shows the topology of the app.Diagram yang menunjukkan topologi aplikasi.

Aplikasi ini menggunakan pustaka klien Microsoft Entra ID Spring Boot Starter untuk Java untuk mendapatkan token akses untuk Microsoft Graph dari ID Microsoft Entra. Token akses membuktikan bahwa pengguna berwenang untuk mengakses titik akhir Microsoft Graph API seperti yang didefinisikan dalam cakupan.

Prasyarat

Rekomendasi

  • Beberapa keakraban dengan Spring Framework.
  • Beberapa keakraban dengan terminal Linux/OSX.
  • jwt.ms untuk memeriksa token Anda.
  • Fiddler untuk memantau aktivitas jaringan dan pemecahan masalah Anda.
  • Ikuti Blog Microsoft Entra untuk tetap up-to-date dengan perkembangan terbaru.

Menyiapkan sampel

Bagian berikut menunjukkan kepada Anda cara menyiapkan aplikasi sampel.

Mengkloning atau mengunduh repositori sampel

Untuk mengkloning sampel, buka jendela Bash dan gunakan perintah berikut:

git clone https://github.com/Azure-Samples/ms-identity-msal-java-samples.git
cd 4-spring-web-app/2-Authorization-I/call-graph

Atau, navigasikan ke repositori ms-identity-msal-java-samples , lalu unduh sebagai file .zip dan ekstrak ke hard drive Anda.

Penting

Untuk menghindari batasan panjang jalur file pada Windows, kloning atau ekstrak repositori ke direktori di dekat akar hard drive Anda.

Mendaftarkan aplikasi sampel dengan penyewa MICROSOFT Entra ID Anda

Ada satu proyek dalam sampel ini. Bagian berikut menunjukkan kepada Anda cara mendaftarkan aplikasi menggunakan portal Azure.

Pilih penyewa ID Microsoft Entra tempat Anda ingin membuat aplikasi

Untuk memilih penyewa Anda, gunakan langkah-langkah berikut:

  1. Masuk ke portal Azure.

  2. Jika akun Anda ada di lebih dari satu penyewa MICROSOFT Entra ID, pilih profil Anda di sudut portal Azure, lalu pilih Alihkan direktori untuk mengubah sesi Anda ke penyewa MICROSOFT Entra ID yang diinginkan.

Mendaftarkan aplikasi (java-spring-webapp-call-graph)

Untuk mendaftarkan aplikasi, gunakan langkah-langkah berikut:

  1. Navigasi ke portal Azure dan pilih MICROSOFT Entra ID.

  2. Pilih Pendaftaran Aplikasi di panel navigasi, lalu pilih Pendaftaran baru.

  3. Di halaman Daftarkan aplikasi yang muncul, masukkan informasi pendaftaran aplikasi berikut ini:

    • Di bagian Nama , masukkan nama aplikasi yang bermakna untuk ditampilkan kepada pengguna aplikasi - misalnya, java-spring-webapp-call-graph.
    • Di bawah Jenis akun yang didukung, pilih Hanya akun dalam direktori organisasi ini.
    • Di bagian Alihkan URI (opsional) , pilih Web di kotak kombo dan masukkan URI pengalihan berikut: http://localhost:8080/login/oauth2/code/.

  4. Pilih Daftar untuk membuat aplikasi.

  5. Pada halaman pendaftaran aplikasi, temukan dan salin nilai ID Aplikasi (klien) untuk digunakan nanti. Anda menggunakan nilai ini dalam file atau file konfigurasi aplikasi Anda.

  6. Pada halaman pendaftaran aplikasi, pilih Sertifikat & rahasia di panel navigasi untuk membuka halaman tempat Anda dapat membuat rahasia dan mengunggah sertifikat.

  7. Di bagian Rahasia klien, pilih Rahasia klien baru.

  8. Ketik deskripsi - misalnya, rahasia aplikasi.

  9. Pilih salah satu durasi yang tersedia: Dalam 1 tahun, Dalam 2 tahun, atau Tidak Pernah Kedaluwarsa.

  10. Pilih Tambahkan. Nilai yang dihasilkan ditampilkan.

  11. Salin dan simpan nilai yang dihasilkan untuk digunakan di langkah selanjutnya. Anda memerlukan nilai ini untuk file konfigurasi kode Anda. Nilai ini tidak ditampilkan lagi, dan Anda tidak dapat mengambilnya dengan cara lain. Jadi, pastikan untuk menyimpannya dari portal Azure sebelum Anda menavigasi ke layar atau panel lain.

  12. Pada halaman pendaftaran aplikasi, pilih panel izin API di panel navigasi untuk membuka halaman untuk akses ke API yang dibutuhkan aplikasi Anda.

  13. Pilih Tambahkan izin, lalu pastikan bahwa tab API Microsoft dipilih.

  14. Di bagian Microsoft API yang umum digunakan, pilih Microsoft Graph.

  15. Di bagian Izin yang didelegasikan, pilih User.Read dari daftar. Gunakan kotak pencarian jika perlu.

  16. Pilih Tambahkan izin.

Mengonfigurasi aplikasi (java-spring-webapp-call-graph) untuk menggunakan pendaftaran aplikasi Anda

Gunakan langkah-langkah berikut untuk mengonfigurasi aplikasi:

Catatan

Dalam langkah-langkah berikut, ClientID sama dengan Application ID atau AppId.

  1. Buka proyek di IDE Anda.

  2. Buka file src\main\resources\application.yml.

  3. Temukan tempat penampung Enter_Your_Tenant_ID_Here dan ganti nilai yang ada dengan ID penyewa Microsoft Entra Anda.

  4. Temukan tempat penampung Enter_Your_Client_ID_Here dan ganti nilai yang ada dengan ID aplikasi atau clientId aplikasi yang java-spring-webapp-call-graph disalin dari portal Azure.

  5. Temukan tempat penampung Enter_Your_Client_Secret_Here dan ganti nilai yang ada dengan nilai yang Anda simpan selama pembuatan java-spring-webapp-call-graph yang disalin dari portal Azure.

Jalankan sampel

Bagian berikut menunjukkan kepada Anda cara menyebarkan sampel ke Azure Container Apps.

Prasyarat

  • Akun Azure. Jika Anda tidak memilikinya, buat akun gratis. Anda memerlukan izin Contributor atau Owner pada langganan Azure untuk melanjutkan. Untuk informasi selengkapnya, lihat Menetapkan peran Azure menggunakan portal Azure.
  • Azure CLI.
  • Ekstensi CLI Azure Container Apps, versi 0.3.47 atau yang lebih tinggi. Untuk menginstal versi terbaru, gunakan az extension add --name containerapp --upgrade --allow-preview perintah .
  • Java Development Kit, versi 17 atau yang lebih tinggi.
  • Maven.

Menyiapkan proyek Spring

Gunakan langkah-langkah berikut untuk menyiapkan proyek:

  1. Gunakan perintah Maven berikut untuk membangun proyek:

    mvn clean verify

  2. Jalankan proyek sampel secara lokal dengan menggunakan perintah berikut:

    mvn spring-boot:run

Siapkan

Untuk masuk ke Azure dari CLI, jalankan perintah berikut dan ikuti perintah untuk menyelesaikan proses autentikasi.

az login

Untuk memastikan Anda menjalankan CLI versi terbaru, jalankan perintah peningkatan.

az upgrade

Selanjutnya, instal atau perbarui ekstensi Azure Container Apps untuk CLI.

Jika Anda menerima kesalahan tentang parameter yang hilang saat menjalankan az containerapp perintah di Azure CLI, pastikan Anda memiliki versi terbaru ekstensi Azure Container Apps yang terinstal.

az extension add --name containerapp --upgrade

Catatan

Mulai Mei 2024, ekstensi Azure CLI tidak lagi mengaktifkan fitur pratinjau secara default. Untuk mengakses fitur pratinjau Container Apps, instal ekstensi Container Apps dengan --allow-preview true.

az extension add --name containerapp --upgrade --allow-preview true

Sekarang setelah ekstensi atau modul saat ini diinstal, daftarkan Microsoft.App namespace layanan dan Microsoft.OperationalInsights .

Catatan

Sumber daya Azure Container Apps telah bermigrasi dari namespace layanan Microsoft.Web ke namespace layanan Microsoft.App. Lihat Migrasi Namespace layanan dari Microsoft.Web ke Microsoft.App pada bulan Maret 2022 untuk detail selengkapnya.

az provider register --namespace Microsoft.App
az provider register --namespace Microsoft.OperationalInsights

Membuat lingkungan Azure Container Apps

Setelah penyiapan Azure CLI selesai, Anda dapat menentukan variabel lingkungan yang digunakan di seluruh artikel ini.

Tentukan variabel berikut dalam shell bash Anda.

export RESOURCE_GROUP="ms-identity-containerapps"
export LOCATION="canadacentral"
export ENVIRONMENT="env-ms-identity-containerapps"
export API_NAME="ms-identity-api"
export JAR_FILE_PATH_AND_NAME="./target/ms-identity-spring-boot-webapp-0.0.1-SNAPSHOT.jar"

Buat grup sumber daya.

az group create  \
    --name $RESOURCE_GROUP \
    --location $LOCATION \

Buat lingkungan dengan ruang kerja Analitik Log yang dibuat secara otomatis.

az containerapp env create \
    --name $ENVIRONMENT \
    --resource-group $RESOURCE_GROUP \
    --location $LOCATION

Tampilkan domain default lingkungan aplikasi kontainer. Catat domain ini untuk digunakan di bagian selanjutnya.

az containerapp env show \
    --name $ENVIRONMENT \
    --resource-group $RESOURCE_GROUP \
    --query properties.defaultDomain

Menyiapkan aplikasi untuk penyebaran

Saat Anda menyebarkan aplikasi ke Azure Container Apps, URL pengalihan Anda berubah ke URL pengalihan instans aplikasi yang anda sebarkan di Azure Container Apps. Gunakan langkah-langkah berikut untuk mengubah pengaturan ini di file application.yml Anda:

  1. Navigasi ke file src\main\resources\application.yml aplikasi Anda dan ubah nilai post-logout-redirect-uri ke nama domain aplikasi yang Disebarkan, seperti yang ditunjukkan dalam contoh berikut. Pastikan untuk mengganti <API_NAME> dan <default-domain-of-container-app-environment> dengan nilai aktual Anda. Misalnya, dengan domain default untuk lingkungan Azure Container App Anda dari langkah sebelumnya dan ms-identity-api untuk nama aplikasi Anda, Anda akan menggunakan https://ms-identity-api.<default-domain> untuk nilai tersebut post-logout-redirect-uri .

    post-logout-redirect-uri: https://<API_NAME>.<default-domain-of-container-app-environment>

  2. Setelah menyimpan file ini, gunakan perintah berikut untuk membangun kembali aplikasi Anda:

    mvn clean package

Penting

File application.yml aplikasi saat ini menyimpan nilai rahasia klien Anda dalam client-secret parameter . Tidak baik untuk menyimpan nilai ini dalam file ini. Anda mungkin juga mengambil risiko jika Anda menerapkan file ke repositori Git. Untuk pendekatan yang direkomendasikan, lihat Mengelola rahasia di Azure Container Apps.

Memperbarui pendaftaran aplikasi ID Microsoft Entra Anda

Karena URI pengalihan berubah ke aplikasi yang disebarkan di Azure Container Apps, Anda juga perlu mengubah URI pengalihan di pendaftaran aplikasi ID Microsoft Entra Anda. Gunakan langkah-langkah berikut untuk membuat perubahan ini:

  1. Navigasikan ke halaman platform identitas Microsoft untuk pengembang Pendaftaran aplikasi.

  2. Gunakan kotak pencarian untuk mencari pendaftaran aplikasi Anda - misalnya, java-servlet-webapp-authentication.

  3. Buka pendaftaran aplikasi Anda dengan memilih namanya.

  4. Pilih Autentikasi dari menu.

  5. Di bagian URI Pengalihan Web - , pilih Tambahkan URI.

  6. Isi URI aplikasi Anda, tambahkan /login/oauth2/code/ - misalnya, https://<containerapp-name>.<default domain of container app environment>/login/oauth2/code/.

  7. Pilih Simpan.

Menyebarkan aplikasi

Sebarkan paket JAR ke Azure Container Apps.

Catatan

Jika perlu, Anda dapat menentukan versi JDK di variabel lingkungan build Java. Untuk informasi selengkapnya, lihat Membangun variabel lingkungan untuk Java di Azure Container Apps.

Sekarang Anda dapat menyebarkan file WAR Anda dengan az containerapp up perintah CLI.

az containerapp up \
    --name $API_NAME \
    --resource-group $RESOURCE_GROUP \
    --location $LOCATION \
    --environment $ENVIRONMENT \
    --artifact <JAR_FILE_PATH_AND_NAME> \
    --ingress external \
    --target-port 8080 \
    --query properties.configuration.ingress.fqdn

Catatan

Versi JDK default adalah 17. Jika Anda perlu mengubah versi JDK untuk kompatibilitas dengan aplikasi, Anda dapat menggunakan --build-env-vars BP_JVM_VERSION=<YOUR_JDK_VERSION> argumen untuk menyesuaikan nomor versi.

Untuk variabel lingkungan build lainnya, lihat Membangun variabel lingkungan untuk Java di Azure Container Apps.

Memvalidasi aplikasi

Dalam contoh ini, containerapp up perintah menyertakan --query properties.configuration.ingress.fqdn argumen, yang mengembalikan nama domain yang sepenuhnya memenuhi syarat (FQDN), juga dikenal sebagai URL aplikasi. Gunakan langkah-langkah berikut untuk memeriksa log aplikasi untuk menyelidiki masalah penyebaran apa pun:

  1. Akses URL aplikasi output dari halaman Output di bagian Penyebaran .

  2. Dari panel navigasi halaman Gambaran Umum instans Azure Container Apps, pilih Log untuk memeriksa log aplikasi.

Menjelajahi sampel

Gunakan langkah-langkah berikut untuk menjelajahi sampel:

  1. Perhatikan status masuk atau keluar yang ditampilkan di tengah layar.
  2. Pilih tombol peka konteks di sudut. Tombol ini membaca Masuk saat Anda pertama kali menjalankan aplikasi. Atau, pilih detail token atau grafik panggilan. Karena halaman ini dilindungi dan memerlukan autentikasi, Anda secara otomatis diarahkan ke halaman masuk.
  3. Pada halaman berikutnya, ikuti instruksi dan masuk dengan akun di penyewa ID Microsoft Entra.
  4. Pada layar persetujuan, perhatikan cakupan yang diminta.
  5. Setelah berhasil menyelesaikan alur masuk, Anda harus dialihkan ke halaman beranda - yang menunjukkan status masuk - atau salah satu halaman lainnya, tergantung tombol mana yang memicu alur masuk Anda.
  6. Perhatikan bahwa tombol peka konteks sekarang mengatakan Keluar dan menampilkan nama pengguna Anda.
  7. Jika Anda berada di beranda, pilih Detail Token ID untuk melihat beberapa klaim token ID yang didekodekan.
  8. Pilih Call Graph untuk melakukan panggilan ke titik akhir /me Microsoft Graph dan lihat pilihan detail pengguna yang diperoleh.
  9. Gunakan tombol di sudut untuk keluar. Halaman status mencerminkan status baru.

Tentang kode

Sampel ini menunjukkan cara menggunakan pustaka klien Microsoft Entra ID Spring Boot Starter untuk Java untuk memasukkan pengguna ke penyewa ID Microsoft Entra Anda dan mendapatkan token akses untuk memanggil Microsoft Graph. Sampel ini juga menggunakan starter boot Spring Oauth2 Client dan Spring Web.

Konten

Tabel berikut ini memperlihatkan konten folder proyek sampel:

Berkas/Folder Deskripsi
pom.xml Dependensi aplikasi.
src/main/resources/templates/ Templat Thymeleaf untuk UI.
src/main/resources/application.yml Konfigurasi Pustaka Pemula Boot Id Microsoft Entra dan Aplikasi.
src/main/java/com/microsoft/azuresamples/msal4j/msidentityspringbootwebapp/ Direktori ini berisi titik masuk aplikasi utama, pengontrol, dan kelas konfigurasi.
.../MsIdentitySpringBootWebappApplication.java Kelas utama.
.../SampleController.java Pengontrol dengan pemetaan titik akhir.
.../SecurityConfig.java Konfigurasi keamanan - misalnya, rute mana yang memerlukan autentikasi.
.../Utilities.java Kelas utilitas - misalnya, memfilter klaim token ID.
CHANGELOG.md Daftar perubahan pada sampel.
CONTRIBUTING.md Panduan untuk berkontribusi pada sampel.
LISENSI Lisensi untuk sampel.

Klaim token ID

Untuk mengekstrak detail token, aplikasi menggunakan spring security AuthenticationPrincipal dan OidcUser objek dalam pemetaan permintaan, seperti yang ditunjukkan dalam contoh berikut. Lihat Pengontrol Sampel untuk detail lengkap tentang bagaimana aplikasi ini menggunakan klaim token ID.

import org.springframework.security.oauth2.core.oidc.user.OidcUser;
import org.springframework.security.core.annotation.AuthenticationPrincipal;
//...
@GetMapping(path = "/some_path")
public String tokenDetails(@AuthenticationPrincipal OidcUser principal) {
    Map<String, Object> claims = principal.getIdToken().getClaims();
}

Untuk masuk, aplikasi membuat permintaan ke titik akhir masuk ID Microsoft Entra yang secara otomatis dikonfigurasi oleh pustaka klien Microsoft Entra ID Spring Boot Starter untuk Java, seperti yang ditunjukkan dalam contoh berikut:

<a class="btn btn-success" href="/oauth2/authorization/azure">Sign In</a>

Untuk keluar, aplikasi membuat permintaan POST ke logout titik akhir, seperti yang ditunjukkan dalam contoh berikut:

<form action="#" th:action="@{/logout}" method="post">
  <input class="btn btn-warning" type="submit" value="Sign Out" />
</form>

Elemen UI yang bergantung pada autentikasi

Aplikasi ini memiliki beberapa logika sederhana di halaman templat UI untuk menentukan konten yang akan ditampilkan berdasarkan apakah pengguna diautentikasi, seperti yang ditunjukkan dalam contoh berikut menggunakan tag Spring Security Thymeleaf:

<div sec:authorize="isAuthenticated()">
  this content only shows to authenticated users
</div>
<div sec:authorize="isAnonymous()">
  this content only shows to not-authenticated users
</div>

Melindungi rute dengan AADWebSecurityConfigurerAdapter

Secara default, aplikasi melindungi halaman Detail Token ID dan Grafik Panggilan sehingga hanya pengguna yang masuk yang dapat mengaksesnya. Aplikasi ini mengonfigurasi rute ini dari app.protect.authenticated properti dari file application.yml . Untuk mengonfigurasi persyaratan spesifik aplikasi, Anda dapat memperluas AADWebSecurityConfigurationAdapter di salah satu kelas. Misalnya, lihat kelas SecurityConfig aplikasi ini, yang ditunjukkan dalam kode berikut:

@EnableWebSecurity
@EnableGlobalMethodSecurity(prePostEnabled = true)
public class SecurityConfig extends AADWebSecurityConfigurerAdapter{
  @Value( "${app.protect.authenticated}" )
  private String[] protectedRoutes;

    @Override
    public void configure(HttpSecurity http) throws Exception {
    // use required configuration form AADWebSecurityAdapter.configure:
    super.configure(http);
    // add custom configuration:
    http.authorizeRequests()
      .antMatchers(protectedRoutes).authenticated()     // limit these pages to authenticated users (default: /token_details, /call_graph)
      .antMatchers("/**").permitAll();                  // allow all other routes.
    }
}

Grafik panggilan

Saat pengguna menavigasi ke /call_graph, aplikasi membuat instans menggunakan GraphServiceClientOauth2AuthorizedClient atau graphAuthorizedClient yang disiapkan oleh pemula boot ID Microsoft Entra. Aplikasi meminta GraphServiceClient untuk memanggil /me titik akhir dan menampilkan detail untuk pengguna yang masuk saat ini. GraphServiceClient berasal dari Microsoft Graph SDK untuk Java, v3.

Oauth2AuthorizedClient harus disiapkan dengan cakupan yang benar. Lihat file application.yml dan bagian Cakupan berikut. Oauth2AuthorizedClient digunakan untuk menampilkan token akses dan menempatkannya di Authorization header GraphServiceClient permintaan, seperti yang ditunjukkan dalam contoh berikut:

//see SampleController.java
@GetMapping(path = "/call_graph")
public String callGraph(@RegisteredOAuth2AuthorizedClient("graph") OAuth2AuthorizedClient graphAuthorizedClient) {
  // See the Utilities.graphUserProperties() method for the full example of the following operation:
  GraphServiceClient graphServiceClient = Utilities.getGraphServiceClient(graphAuthorizedClient);
  User user = graphServiceClient.me().buildRequest().get();
  return user.displayName;
}

Contoh berikut dari file application.yml menunjukkan cakupan yang diminta:

# see application.yml file
authorization-clients:
  graph:
    # Specifies the Microsoft Graph scopes that your app needs access to:
    scopes: https://graph.microsoft.com/User.Read

Cakupan

Cakupan memberi tahu Microsoft Entra ID tingkat akses yang diminta aplikasi. Untuk cakupan Microsoft Graph yang diminta oleh aplikasi ini, lihat application.yml.

Secara default, aplikasi mengatur nilai cakupan ke https://graph.microsoft.com/User.Read. Cakupannya User.Read adalah untuk mengakses informasi pengguna yang masuk saat ini dari titik akhir /me. Permintaan yang valid ke titik akhir /me harus berisi User.Read cakupan.

Saat pengguna masuk, ID Microsoft Entra menyajikan dialog persetujuan kepada pengguna berdasarkan cakupan yang diminta oleh aplikasi. Jika pengguna menyetujui satu atau beberapa cakupan dan mendapatkan token, cakupan yang disetujui akan dikodekan ke dalam token akses yang dihasilkan.

Dalam aplikasi ini, muncul graphAuthorizedClient token akses yang membuktikan cakupan yang disetujui pengguna. Aplikasi ini menggunakan token ini untuk membuat instans GraphServiceClient yang menangani permintaan Graph.

Menggunakan GraphServiceClient.me().buildRequest().get(), permintaan dibuat dan dibuat ke https://graph.microsoft.com/v1.0/me. Token akses ditempatkan di Authorization header permintaan.

Informasi selengkapnya

Untuk informasi selengkapnya tentang cara kerja protokol OAuth 2.0 dalam skenario ini dan skenario lainnya, lihat Skenario Autentikasi untuk ID Microsoft Entra.

  • Last updated on