Mengamankan aplikasi Java Spring Boot menggunakan ID Microsoft Entra

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

Diagram berikut menunjukkan topologi aplikasi:

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

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

Siapkan 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, buka repositori ms-identity-msal-java-samples, lalu unduh repositori tersebut sebagai file .zip dan ekstrak ke hard disk Anda.

Penting

Untuk menghindari batasan panjang jalur pada Windows, sebaiknya kloning ke direktori di dekat akar drive Anda.

Daftarkan aplikasi sampel dengan tenant 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 Microsoft Azure.

  2. Jika akun Anda berada di lebih dari satu tenant Microsoft Entra ID, pilih profil Anda di sudut Azure portal, lalu pilih Alihkan direktori untuk mengalihkan sesi Anda ke tenant Microsoft Entra ID yang diinginkan.

Daftarkan aplikasi (java-spring-webapp-auth)

Untuk mendaftarkan aplikasi, gunakan langkah-langkah berikut:

  1. Buka Azure portal dan pilih Microsoft Entra ID.

  2. Pilih Pendaftaran aplikasi pada 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 deskriptif untuk ditampilkan kepada pengguna aplikasi - misalnya, java-spring-webapp-auth.
    • Di bawah Jenis akun yang didukung, pilih Penyewa tunggal saja - TENANT_NAME (TENANT_NAME bervariasi per penyewa).
    • Di bagian URI pengalihan (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: Direkomendasikan: 180 hari (6 bulan), 90 hari (3 bulan), 365 hari (12 bulan), 545 hari (18 bulan) atau 730 hari (24 bulan).

  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

Pada 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 placeholder Enter_Your_Tenant_ID_Here dan ganti nilai yang ada dengan ID tenant Microsoft Entra Anda.

  4. Temukan placeholder Enter_Your_Client_ID_Here dan ganti nilai yang ada dengan ID aplikasi dari aplikasi java-spring-webapp-auth atau clientId yang Anda salin dari portal Azure.

  5. Temukan placeholder Enter_Your_Client_Secret_Here dan ganti nilai yang ada dengan nilai yang Anda simpan saat membuat 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 belum memilikinya, buat akun gratis. Anda memerlukan izin Contributor atau Owner pada langganan Azure untuk melanjutkan. Untuk informasi lebih lanjut, lihat Menetapkan peran Azure menggunakan portal Azure.
  • Azure CLI tersebut.
  • Ekstensi Azure Container Apps CLI, versi 0.3.47 atau yang lebih tinggi. Untuk menginstal versi terbaru, gunakan perintah az extension add --name containerapp --upgrade --allow-preview.
  • Java Development Kit, versi 17 atau yang lebih baru.
  • 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

Penyiapan

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 terkait parameter yang hilang saat menjalankan perintah az containerapp di Azure CLI, pastikan Anda telah memasang ekstensi Azure Container Apps versi terbaru.

az extension add --name containerapp --upgrade

Catatan

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

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

Setelah ekstensi atau modul saat ini terpasang, daftarkan namespace Microsoft.App dan Microsoft.OperationalInsights.

Catatan

Sumber daya Azure Container Apps telah dimigrasikan dari namespace Microsoft.Web ke namespace Microsoft.App. Lihat Migrasi namespace dari Microsoft.Web ke Microsoft.App pada Maret 2022 untuk informasi 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. Buka file src\main\resources\application.yml aplikasi Anda dan ubah nilai post-logout-redirect-uri menjadi nama domain aplikasi Anda yang telah di-deploy, seperti yang ditunjukkan dalam contoh berikut. Pastikan untuk mengganti <API_NAME> dan <default-domain-of-container-app-environment> dengan nilai sebenarnya. Misalnya, dengan domain default untuk lingkungan Azure Container App Anda dari langkah sebelumnya dan ms-identity-api sebagai nama aplikasi Anda, Anda akan menggunakan https://ms-identity-api.<default-domain> untuk nilai 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 dari aplikasi saat ini berisi nilai rahasia klien Anda dalam parameter client-secret. 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. Buka 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 Web - URI Pengalihan, pilih Tambahkan URI.

  6. Isi URI aplikasi Anda dengan menambahkan /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 Variabel lingkungan build untuk Java di Azure Container Apps.

Sekarang Anda dapat men-deploy file WAR Anda dengan perintah CLI az containerapp up.

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 agar kompatibel dengan aplikasi Anda, Anda dapat menggunakan argumen --build-env-vars BP_JVM_VERSION=<YOUR_JDK_VERSION> untuk menyesuaikan nomor versi.

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

Memvalidasi aplikasi

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

  1. Akses URL keluaran aplikasi dari halaman Outputs di bagian Deployment.

  2. Dari panel navigasi pada halaman Overview instans Azure Container Apps, pilih Logs untuk memeriksa log aplikasi.

Jelajahi contoh

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 bertuliskan 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 menggunakan akun di tenant Microsoft Entra ID.
  4. Pada layar persetujuan, perhatikan cakupan yang diminta.
  5. Setelah berhasil menyelesaikan proses masuk, Anda akan diarahkan ke halaman beranda—yang menampilkan status masuk—atau ke halaman detail token, bergantung pada tombol yang memicu proses masuk tersebut.
  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

Contoh ini menunjukkan cara menggunakan pustaka klien Microsoft Entra ID Spring Boot Starter untuk Java guna memungkinkan pengguna masuk ke penyewa Microsoft Entra ID 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.

Isi

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 Aplikasi dan Pustaka Boot Starter Microsoft Entra ID
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 ID token

Untuk mengekstrak detail token, aplikasi memanfaatkan objek AuthenticationPrincipal dan OidcUser milik Spring Security dalam request mapping, seperti yang ditunjukkan pada contoh berikut. Lihat Sample Controller untuk detail selengkapnya tentang cara 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 mengirimkan permintaan POST ke endpoint logout, seperti yang ditunjukkan pada 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>

Lindungi 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 properti app.protect.authenticated dari file application.yml. Untuk mengonfigurasi persyaratan khusus aplikasi Anda, terapkan metode AadWebApplicationHttpSecurityConfigurer#aadWebApplication pada instance HttpSecurity. Sebagai contoh, lihat kelas SecurityConfig pada aplikasi ini, seperti 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 Microsoft Entra ID.

  • Last updated on