Amankan aplikasi Java WebSphere menggunakan peran aplikasi dan klaim peran

Artikel ini menunjukkan aplikasi Java WebSphere yang menggunakan OpenID Connect untuk memungkinkan pengguna masuk dan Peran Aplikasi Microsoft Entra ID (peran aplikasi) untuk otorisasi.

Aplikasi ini menerapkan kontrol akses berbasis peran (RBAC) menggunakan peran aplikasi dan fitur klaim peran milik Microsoft Entra ID. Pendekatan lain adalah menggunakan grup ID Microsoft Entra dan klaim grup. Grup ID Microsoft Entra dan peran aplikasi tidak saling eksklusif. Anda dapat menggunakan keduanya untuk menerapkan kontrol akses yang terperinci.

Anda juga dapat menggunakan RBAC dengan peran aplikasi dan klaim peran untuk menerapkan kebijakan otorisasi dengan aman.

Untuk video yang membahas skenario dan contoh ini, lihat Menerapkan otorisasi dalam aplikasi Anda menggunakan peran aplikasi, grup keamanan, cakupan, dan peran direktori.

Untuk informasi selengkapnya tentang cara kerja protokol dalam skenario ini maupun skenario lainnya, lihat Autentikasi vs. Otorisasi.

Aplikasi ini menggunakan MSAL for Java (MSAL4J) untuk mengautentikasi pengguna dan memperoleh ID token dari Microsoft Entra ID.

Sampel ini terlebih dahulu menggunakan MSAL untuk Java (MSAL4J) untuk memasukkan pengguna. Pada beranda, ia menampilkan opsi bagi pengguna untuk melihat klaim dalam token ID mereka. Aplikasi ini juga memungkinkan pengguna untuk melihat halaman admin istimewa atau halaman pengguna biasa, tergantung pada peran aplikasi tempat mereka ditetapkan. Idenya adalah untuk memberikan contoh bagaimana, dalam aplikasi, akses ke fungsionalitas atau halaman tertentu dibatasi untuk subset pengguna tergantung pada peran mana mereka berada.

Otorisasi semacam ini diimplementasikan menggunakan RBAC. Dengan RBAC, administrator memberikan izin untuk peran, bukan untuk pengguna atau grup individual. Administrator kemudian dapat menetapkan peran kepada pengguna dan grup yang berbeda untuk mengontrol siapa yang memiliki akses ke konten dan fungsionalitas tertentu.

Aplikasi sampel ini mendefinisikan dua Peran Aplikasi berikut:

  • : Berwenang untuk mengakses halaman Khusus Admin dan Pengguna Reguler.
  • : Diizinkan mengakses halaman Pengguna Reguler.

Peran aplikasi ini didefinisikan dalam portal Azure dalam manifes pendaftaran aplikasi. Saat pengguna masuk ke aplikasi, Microsoft Entra ID menghasilkan klaim peran untuk setiap peran yang diberikan secara individual kepada pengguna dalam bentuk keanggotaan dalam peran.

Anda dapat menetapkan pengguna dan grup ke peran melalui portal Azure.

Catatan

Klaim peran tidak tersedia untuk pengguna tamu dalam tenant jika titik akhir digunakan sebagai otoritas untuk memproses masuk pengguna. Anda perlu mengarahkan pengguna untuk masuk ke titik akhir tenant seperti .

Prasyarat

  • JDK versi 8 atau lebih tinggi
  • Maven 3
  • Penyewa Microsoft Entra ID. Untuk informasi selengkapnya, lihat Cara mendapatkan tenant Microsoft Entra ID.
  • Akun pengguna di tenant Microsoft Entra ID Anda sendiri jika Anda ingin bekerja hanya dengan akun di direktori organisasi Anda — yaitu, mode single-tenant. Jika Anda belum membuat akun pengguna di penyewa, Anda harus melakukannya sebelum melanjutkan. Untuk informasi lebih lanjut, lihat Cara membuat, mengundang, dan menghapus pengguna.
  • WebSphere
  • Visual Studio Code
  • Alat Azure untuk Visual Studio Code

Rekomendasi

  • Memiliki pemahaman dasar tentang Java / Jakarta Servlets.
  • 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 3-java-servlet-web-app/3-Authorization-II/roles

Atau, buka 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.

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 Azure.

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

Mendaftarkan aplikasi (java-servlet-webapp-roles)

Pertama, daftarkan aplikasi baru di portal Azure dengan mengikuti petunjuk dalam Mulai cepat: Mendaftarkan aplikasi dengan platform identitas Microsoft.

Kemudian, gunakan langkah-langkah berikut untuk menyelesaikan pendaftaran:

  1. Buka halaman platform identitas Microsoft untuk pengembang Pendaftaran aplikasi.

  2. Pilih Pendaftaran baru.

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

    • Di bagian Nama, masukkan nama aplikasi yang jelas untuk ditampilkan kepada pengguna aplikasi - misalnya, .

    • Di bawah Jenis akun yang didukung, pilih salah satu opsi berikut:

      • Pilih Akun hanya di direktori organisasi ini jika Anda membuat aplikasi yang hanya akan digunakan oleh pengguna di tenant Anda — yakni, aplikasi penyewa tunggal.

    • Di bagian Redirect URI, pilih Web di kotak kombo dan masukkan URI pengalihan berikut: .

  4. Pilih Daftar untuk membuat aplikasi.

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

  6. Pilih Simpan untuk menerapkan perubahan.

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

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

  9. Ketik deskripsi - misalnya, rahasia aplikasi.

  10. Pilih kedaluwarsa untuk rahasia atau tentukan masa pakai kustom. Rahasia klien dibatasi hingga masa pakai maksimum 24 bulan, dan Microsoft merekomendasikan kedaluwarsa kurang dari 12 bulan. Untuk aplikasi produksi, pilih sertifikat atau kredensial identitas federasi daripada rahasia klien.

  11. Pilih Tambahkan. Nilai yang dihasilkan ditampilkan.

  12. 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.

Menentukan peran aplikasi

Untuk menentukan peran aplikasi, gunakan langkah-langkah berikut:

  1. Masih pada pendaftaran aplikasi yang sama, pilih Peran aplikasi di panel navigasi.

  2. Pilih Buat peran aplikasi, lalu masukkan nilai berikut:

    • Untuk Nama tampilan, masukkan nama yang sesuai - misalnya, PrivilegedAdmin.
    • Untuk Jenis anggota yang diizinkan, pilih Pengguna.
    • Untuk Nilai, masukkan PrivilegedAdmin.
    • Untuk Deskripsi, masukkan PrivilegedAdmins yang dapat melihat Halaman Admin.

  3. Pilih Buat peran aplikasi, lalu masukkan nilai berikut:

    • Untuk Nama tampilan, masukkan nama yang sesuai - misalnya, RegularUser.
    • Untuk Jenis anggota yang diizinkan, pilih Pengguna.
    • Untuk Nilai, masukkan RegularUser.
    • Untuk Description, masukkan RegularUsers yang dapat melihat Halaman Pengguna.

  4. Pilih Terapkan untuk menyimpan perubahan.

Menetapkan pengguna ke peran aplikasi

Untuk menambahkan pengguna ke peran aplikasi yang telah ditentukan sebelumnya, ikuti panduan di sini: Menetapkan pengguna dan grup ke peran.

Konfigurasikan aplikasi (java-servlet-webapp-roles) agar menggunakan pendaftaran aplikasi Anda

Gunakan langkah-langkah berikut untuk mengonfigurasi aplikasi:

Catatan

Pada langkah-langkah berikut, sama dengan atau .

  1. Buka proyek di IDE Anda.

  2. Buka file authentication.properties.

  3. Temukan string . Ganti nilai yang ada dengan ID tenant Microsoft Entra ID Anda.

  4. Temukan string dan ganti nilai yang ada dengan ID aplikasi atau dari aplikasi yang disalin dari portal Azure.

  5. Temukan string dan ganti nilai yang ada dengan nilai yang Anda simpan selama pembuatan aplikasi di portal Azure.

  6. Temukan properti dan pastikan nilainya diatur ke , atau ganti dengan nama peran spesifik Anda.

Susun sampel

Untuk membuat sampel menggunakan Maven, navigasikan ke direktori yang berisi file pom.xml untuk sampel, lalu jalankan perintah berikut:

mvn clean package

Perintah ini menghasilkan file .war yang dapat Anda jalankan di berbagai server aplikasi.

Jalankan sampel

Instruksi ini mengasumsikan bahwa Anda menginstal WebSphere dan menyiapkan server. Anda dapat menggunakan panduan di Menyebarkan Kluster WebSphere Application Server (tradisional) di Azure Virtual Machines untuk konfigurasi server dasar.

Sebelum Anda dapat menyebarkan ke WebSphere, gunakan langkah-langkah berikut untuk membuat beberapa perubahan konfigurasi dalam sampel itu sendiri lalu membangun atau membangun kembali paket:

  1. Buka file authentication.properties milik aplikasi Anda dan ubah nilai menjadi URL server dan nomor port yang akan Anda gunakan, seperti yang ditunjukkan dalam contoh berikut:

    # app.homePage is by default set to dev server address and app context path on the server
# for apps deployed to azure, use https://your-sub-domain.azurewebsites.net
app.homePage=https://<server-url>:<port-number>/msal4j-servlet-auth/

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

    mvn clean package

  3. Setelah kode selesai dibangun, salin file .war ke sistem file server target Anda.

Anda juga perlu membuat perubahan yang sama di registrasi aplikasi Azure, tempat Anda menetapkannya di portal Azure sebagai nilai Redirect URI pada tab Authentication.

  1. Buka halaman platform identitas Microsoft untuk pengembang Pendaftaran aplikasi.

  2. Gunakan kotak pencarian untuk mencari pendaftaran aplikasi Anda - misalnya, .

  3. Buka pendaftaran aplikasi Anda dengan memilih namanya.

  4. Pilih Autentikasi dari menu.

  5. Di bagian WebURI Pengalihan, pilih Tambahkan URI.

  6. Isi URI aplikasi Anda dengan menambahkan /auth/redirect - misalnya, .

  7. Pilih Simpan.

Gunakan langkah-langkah berikut untuk menyebarkan sampel menggunakan Konsol Solusi Terintegrasi WebSphere:

  1. Pada tab Aplikasi, pilih Aplikasi Baru, lalu Aplikasi Perusahaan Baru.

  2. Pilih file .war yang Anda buat, lalu pilih Berikutnya sampai Anda mencapai langkah penginstalan Petakan root konteks untuk modul Web. Pengaturan default lainnya harus baik-baik saja.

  3. Untuk root konteks, atur nilainya agar sama dengan nilai setelah nomor port di 'URI Pengalihan' yang Anda tetapkan dalam konfigurasi sampel atau pendaftaran aplikasi Azure. Artinya, jika URI pengalihan adalah , maka akar konteks harus .

  4. Pilih Selesai.

  5. Setelah aplikasi selesai diinstal, buka bagian Aplikasi perusahaan WebSphere di tab Aplikasi .

  6. Pilih file .war yang Anda instal dari daftar aplikasi lalu pilih Mulai untuk menyebarkan.

  7. Setelah selesai diterapkan, buka dan Anda seharusnya dapat melihat aplikasinya.

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 pertama kali Anda menjalankan aplikasi.
  3. Pada halaman berikutnya, ikuti instruksi dan masuk menggunakan akun dalam tenant Microsoft Entra ID.
  4. Pada layar persetujuan, perhatikan cakupan yang diminta.
  5. Perhatikan bahwa tombol peka konteks sekarang mengatakan Keluar dan menampilkan nama pengguna Anda.
  6. Pilih Detail Token ID untuk melihat beberapa klaim yang telah didekode dari token ID.
  7. Pilih Khusus Admin untuk melihat halaman . Hanya pengguna dengan peran aplikasi yang dapat melihat halaman ini. Jika tidak, pesan kegagalan otorisasi ditampilkan.
  8. Pilih Pengguna Reguler untuk melihat halaman . Hanya pengguna dengan peran aplikasi atau yang dapat melihat halaman ini. Jika tidak, pesan kegagalan otorisasi ditampilkan.
  9. Gunakan tombol di sudut untuk keluar.

Tentang kode

Contoh ini menggunakan MSAL for Java (MSAL4J) untuk membuat pengguna masuk dan memperoleh token ID yang mungkin berisi klaim peran. Berdasarkan klaim peran yang ada, pengguna yang telah masuk dapat mengakses tidak satu pun, salah satu, atau kedua halaman yang dilindungi, dan .

Jika Anda ingin mereplikasi perilaku sampel ini, Anda dapat menyalin file pom.xml dan konten folder pembantu dan authservlets di folder src/main/java/com/microsoft/azuresamples/msal4j. Anda juga memerlukan file authentication.properties. Kelas dan file ini berisi kode generik yang dapat Anda gunakan dalam berbagai aplikasi. Anda juga dapat menyalin bagian lain dari sampel ini, tetapi kelas dan file lainnya dibuat khusus untuk memenuhi tujuan sampel ini.

Isi

Tabel berikut ini memperlihatkan konten folder proyek sampel:

Berkas/folder Deskripsi
src/main/java/com/microsoft/azuresamples/msal4j/roles/ Direktori ini berisi kelas yang menentukan logika bisnis backend aplikasi.
src/main/java/com/microsoft/azuresamples/msal4j/authservlets/ Direktori ini berisi kelas-kelas yang digunakan untuk endpoint login dan logout.
*Servlet.java Semua titik akhir yang tersedia ditentukan dalam kelas Java dengan nama yang berakhiran Servlet.
src/main/java/com/microsoft/azuresamples/msal4j/helpers/ Kelas bantu untuk autentikasi.
AuthenticationFilter.java Mengalihkan permintaan yang belum diautentikasi ke endpoint yang dilindungi ke halaman 401.
src/main/resources/authentication.properties ID Microsoft Entra dan konfigurasi program.
src/main/webapp/ Direktori ini berisi templat UI - JSP
CHANGELOG.md Daftar perubahan pada sampel.
CONTRIBUTING.md Panduan untuk berkontribusi pada sampel.
LISENSI Lisensi untuk sampel.

Memproses klaim peran dalam token ID

Klaim peran dalam token mencakup nama peran yang ditetapkan untuk pengguna yang masuk, seperti yang ditunjukkan dalam contoh berikut:

{
  ...
  "roles": [
    "Role1",
    "Role2",]
  ...
}

ConfidentialClientApplication

Sebuah instance dibuat di file AuthHelper.java, seperti yang ditunjukkan pada contoh berikut. Objek ini membantu membuat URL otorisasi Microsoft Entra dan juga membantu menukar token autentikasi dengan token akses.

// getConfidentialClientInstance method
IClientSecret secret = ClientCredentialFactory.createFromSecret(SECRET);
confClientInstance = ConfidentialClientApplication
                     .builder(CLIENT_ID, secret)
                     .authority(AUTHORITY)
                     .build();

Parameter berikut digunakan untuk instansiasi:

  • ID klien aplikasi.
  • Rahasia klien, yang merupakan persyaratan untuk Aplikasi Klien Rahasia.
  • Otoritas Microsoft Entra ID, yang mencakup ID tenant Microsoft Entra Anda.

Dalam sampel ini, nilai-nilai ini dibaca dari file authentication.properties menggunakan pembaca properti dalam file Config.java .

Panduan langkah demi langkah

Langkah-langkah berikut menyediakan panduan fungsionalitas aplikasi:

  1. Langkah pertama dalam proses masuk adalah mengirim permintaan ke endpoint untuk tenant Microsoft Entra ID Anda. Instans MSAL4J digunakan untuk menyusun URL permintaan otorisasi. Aplikasi mengalihkan browser ke URL ini, yang merupakan tempat pengguna masuk.

    final ConfidentialClientApplication client = getConfidentialClientInstance();
AuthorizationRequestUrlParameters parameters = AuthorizationRequestUrlParameters.builder(Config.REDIRECT_URI, Collections.singleton(Config.SCOPES))
        .responseMode(ResponseMode.QUERY).prompt(Prompt.SELECT_ACCOUNT).state(state).nonce(nonce).build();

final String authorizeUrl = client.getAuthorizationRequestUrl(parameters).toString();
contextAdapter.redirectUser(authorizeUrl);

    Daftar berikut menjelaskan fitur kode ini:

    • : Parameter yang harus ditetapkan untuk membuat AuthorizationRequestUrl.
    • : Tempat Microsoft Entra ID mengalihkan browser—bersama kode otorisasi—setelah mengumpulkan kredensial pengguna. Harus cocok dengan URI pengalihan dalam pendaftaran aplikasi Microsoft Entra ID di Azure portal.
    • : Cakupan izin merupakan izin yang diminta oleh aplikasi.
      • Biasanya, ketiga cakupan sudah memadai untuk menerima respons ID token.
      • Daftar lengkap cakupan yang diminta oleh aplikasi dapat ditemukan di file authentication.properties . Anda dapat menambahkan lebih banyak cakupan akses, seperti .

  2. Pengguna disajikan dengan perintah masuk oleh ID Microsoft Entra. Jika upaya masuk berhasil, browser pengguna dialihkan ke titik akhir pengalihan aplikasi. Permintaan yang valid ke endpoint ini berisi kode otorisasi.

  3. Instans kemudian menukarkan kode otorisasi ini dengan token ID dan token akses dari Microsoft Entra ID.

    // First, validate the state, then parse any error codes in response, then extract the authCode. Then:
// build the auth code params:
final AuthorizationCodeParameters authParams = AuthorizationCodeParameters
        .builder(authCode, new URI(Config.REDIRECT_URI)).scopes(Collections.singleton(Config.SCOPES)).build();

// Get a client instance and leverage it to acquire the token:
final ConfidentialClientApplication client = AuthHelper.getConfidentialClientInstance();
final IAuthenticationResult result = client.acquireToken(authParams).get();

    Daftar berikut menjelaskan fitur kode ini:

    • : Parameter yang harus ditetapkan untuk menukar kode otorisasi dengan token ID dan/atau token akses.
    • : Kode otorisasi yang diterima di endpoint pengalihan.
    • : URI pengalihan yang digunakan pada langkah sebelumnya harus dikirimkan kembali.
    • : Cakupan akses yang digunakan pada langkah sebelumnya harus diberikan kembali.

  4. Jika berhasil, klaim token diekstrak. Jika pemeriksaan nonce berhasil, hasilnya ditempatkan dalam - sebuah instans dari - dan disimpan dalam sesi. Aplikasi kemudian dapat membuat instance dari sesi melalui instance setiap kali aplikasi memerlukan akses ke sana, seperti yang ditunjukkan dalam kode berikut:

    // parse IdToken claims from the IAuthenticationResult:
// (the next step - validateNonce - requires parsed claims)
context.setIdTokenClaims(result.idToken());

// if nonce is invalid, stop immediately! this could be a token replay!
// if validation fails, throws exception and cancels auth:
validateNonce(context);

// set user to authenticated:
context.setAuthResult(result, client.tokenCache().serialize());

Melindungi rute

Untuk informasi tentang cara aplikasi sampel memfilter akses ke rute, lihat AuthenticationFilter.java. Dalam file authentication.properties, properti app.protect.authenticated berisi rute yang dipisahkan dengan koma dan hanya dapat diakses oleh pengguna yang terautentikasi, seperti yang ditunjukkan pada contoh berikut:

# for example, /token_details requires any user to be signed in and does not require special roles claim(s)
app.protect.authenticated=/token_details

Rute mana pun yang tercantum dalam kumpulan aturan yang dipisahkan dengan koma di bawah juga tidak dapat diakses oleh pengguna yang tidak diautentikasi, seperti yang ditunjukkan pada contoh berikut. Namun, rute ini juga berisi daftar keanggotaan peran aplikasi yang dipisahkan ruang: hanya pengguna yang memiliki setidaknya salah satu peran terkait yang dapat mengakses rute ini setelah mengautentikasi.

# local short names for app roles - for example, sets admin to mean PrivilegedAdmin (useful for long rule sets defined in the next key, app.protect.roles)
app.roles=admin PrivilegedAdmin, user RegularUser

# A route and its corresponding <space-separated> role(s) that can access it; the start of the next route & its role(s) is delimited by a <comma-and-space-separator>
# this says: /admins_only can be accessed by PrivilegedAdmin, /regular_user can be accessed by PrivilegedAdmin role and the RegularUser role
app.protect.roles=/admin_only admin, /regular_user admin user

Cakupan

Cakupan izin memberi tahu Microsoft Entra ID tentang tingkat akses yang diminta oleh aplikasi.

Berdasarkan cakupan yang diminta, MICROSOFT Entra ID menyajikan dialog persetujuan kepada pengguna saat masuk. Jika pengguna menyetujui satu atau beberapa scope dan memperoleh token, scope yang telah disetujui dikodekan ke dalam yang dihasilkan.

Untuk cakupan yang diminta oleh aplikasi, lihat authentication.properties. Ketiga cakupan ini diminta oleh MSAL dan diberikan oleh ID Microsoft Entra secara default.

Informasi selengkapnya

  • Pustaka Autentikasi Microsoft (MSAL) untuk Java
  • Platform identitas Microsoft
  • Mulai Cepat: Mendaftarkan aplikasi di platform identitas Microsoft
  • Memahami pengalaman persetujuan aplikasi Microsoft Entra ID
  • Memahami persetujuan pengguna dan administrator
  • Contoh kode MSAL
  • Cara: Menambahkan peran aplikasi ke aplikasi Anda dan menerimanya dalam token
  • Mengelola penugasan pengguna untuk aplikasi di Microsoft Entra ID

Langkah selanjutnya

Sebarkan aplikasi Java WebSphere ke WebSphere tradisional di Azure Virtual Machines

  • Terakhir diperbarui pada