Bagikan melalui

Mengamankan aplikasi Java Spring Boot menggunakan ID Microsoft Entra

Artikel ini menunjukkan aplikasi web Java Spring Boot yang memasukkan pengguna di penyewa ID Microsoft Entra Anda menggunakan pustaka klien Microsoft Entra ID Spring Boot Starter untuk Java. Ini menggunakan protokol OpenID Connect.

Diagram berikut menunjukkan topologi aplikasi:

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

Aplikasi klien menggunakan pustaka klien Microsoft Entra ID Spring Boot Starter untuk Java untuk memasukkan pengguna dan mendapatkan token ID dari ID Microsoft Entra. Token ID membuktikan bahwa pengguna diautentikasi dengan ID Microsoft Entra dan memungkinkan pengguna mengakses rute yang dilindungi.

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/1-Authentication/sign-in

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 pada Windows, sebaiknya kloning ke direktori di dekat akar 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.

Daftarkan aplikasi (java-spring-webapp-auth)

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-auth.
    • 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.

Mengonfigurasi aplikasi (java-spring-webapp-auth) 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-auth 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-auth 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. 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 diarahkan ke halaman beranda - yang menunjukkan status masuk - atau halaman detail token, 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. 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 guna memasukkan pengguna ke penyewa ID Microsoft Entra Anda. Sampel ini juga menggunakan starter boot Spring Oauth2 Client dan Spring Web. Sampel menggunakan klaim dari token ID yang diperoleh dari ID Microsoft Entra untuk menampilkan detail pengguna yang masuk.

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 sehingga hanya pengguna yang masuk yang dapat mengaksesnya. Aplikasi mengonfigurasi rute ini dengan menggunakan app.protect.authenticated properti dari file application.yml . Untuk mengonfigurasi persyaratan spesifik aplikasi Anda, terapkan AadWebApplicationHttpSecurityConfigurer#aadWebApplication metode ke HttpSecurity instans. Misalnya, lihat kelas SecurityConfig aplikasi ini, yang ditunjukkan dalam kode berikut:

@Configuration
@EnableWebSecurity
@EnableMethodSecurity
public class SecurityConfig  {
    
    @Value("${app.protect.authenticated}")
    private String[] allowedOrigins;
    
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        // @formatter:off
        http.apply(AadWebApplicationHttpSecurityConfigurer.aadWebApplication())
            .and()
            .authorizeHttpRequests(auth -> auth
                .requestMatchers(allowedOrigins).authenticated()
                .anyRequest().permitAll()
                );
        // @formatter:on
        return http.build();
    }

    @Bean
    @RequestScope
    public ServletUriComponentsBuilder urlBuilder() {
        return ServletUriComponentsBuilder.fromCurrentRequest();
    }    
}

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