Microsoft Entra Id kullanarak Java Spring Boot uygulamalarının güvenliğini sağlama

  • Makale

Bu makalede, Java için Microsoft Entra ID Spring Boot Starter istemci kitaplığını kullanarak Microsoft Entra ID kiracınızdaki kullanıcıları oturum açan bir Java Spring Boot web uygulaması gösterilmektedir. OpenID Bağlan protokollerini kullanır.

Aşağıdaki diyagramda uygulamanın topolojisi gösterilmektedir:

Uygulamanın topolojisini gösteren diyagram.

İstemci uygulaması, bir kullanıcıda oturum açmak ve Microsoft Entra ID'den kimlik belirteci almak için Java için Microsoft Entra ID Spring Boot Starter istemci kitaplığını kullanır. Kimlik belirteci, kullanıcının Kimliğinin Microsoft Entra Id ile doğrulandığını kanıtlar ve kullanıcının korumalı yollara erişmesini sağlar.

Önkoşullar

Öneriler

Örneği ayarlama

Aşağıdaki bölümlerde örnek uygulamanın nasıl ayarlanacağı gösterilmektedir.

Örnek depoyu kopyalama veya indirme

Örneği kopyalamak için bir Bash penceresi açın ve aşağıdaki komutu kullanın:

git clone https://github.com/Azure-Samples/ms-identity-java-spring-tutorial.git
cd ms-identity-java-spring-tutorial
cd 1-Authentication/sign-in

Alternatif olarak, ms-identity-java-spring-tutorial deposuna gidin, ardından .zip dosyası olarak indirin ve sabit sürücünüze ayıklayın.

Önemli

Windows'ta yol uzunluğu sınırlamalarını önlemek için sürücünüzün köküne yakın bir dizine kopyalamanızı öneririz.

Örnek uygulamaları Microsoft Entra ID kiracınıza kaydetme

Bu örnekte bir proje var. Uygulamayı Azure portalına kaydetmek için el ile yapılandırma adımlarını izleyebilir veya bir PowerShell betiği kullanabilirsiniz. Betik aşağıdaki görevleri yapar:

  • Microsoft Entra ID uygulamalarını ve parolalar, izinler ve bağımlılıklar gibi ilgili nesneleri oluşturur.
  • Proje yapılandırma dosyalarını değiştirir.
  • Varsayılan olarak, yalnızca kuruluş dizininizdeki hesaplarla çalışan bir uygulama ayarlar.

PowerShell betiğini çalıştırmak için aşağıdaki adımları kullanın:

  1. Windows'da PowerShell'i açın ve kopyalanan dizinin köküne gidin.

  2. PowerShell için yürütme ilkesini ayarlamak için aşağıdaki komutu kullanın:

    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process -Force

  3. Yapılandırma betiğini çalıştırmak için aşağıdaki komutları kullanın:

    cd .\AppCreationScripts\
.\Configure.ps1

    Not

    Betikleri çalıştırmanın diğer yolları Uygulama Oluşturma Betikleri bölümünde açıklanmıştır. Betikler ayrıca, CI/CD senaryolarınızda yardımcı olabilecek otomatik uygulama kaydı, yapılandırma ve kaldırma için bir kılavuz sağlar.

Uygulamayı (java-spring-webapp-auth) uygulama kaydınızı kullanacak şekilde yapılandırma

Uygulamayı yapılandırmak için aşağıdaki adımları kullanın:

Not

Aşağıdaki adımlarda veya ClientIDAppIdile Application ID aynıdır.

  1. Projeyi IDE'nizde açın.

  2. src\main\resources\application.yml dosyasını açın.

  3. Yer tutucuyu Enter_Your_Tenant_ID_Here bulun ve mevcut değeri Microsoft Entra kiracı kimliğiniz ile değiştirin.

  4. Yer tutucuyu Enter_Your_Client_ID_Here bulun ve mevcut değeri Azure portalından kopyalanan uygulama kimliğiyle veya clientIdjava-spring-webapp-auth uygulamanın kimliğiyle değiştirin.

  5. Yer tutucuyu Enter_Your_Client_Secret_Here bulun ve mevcut değeri Azure portalından kopyalanırken java-spring-webapp-auth kaydettiğiniz değerle değiştirin.

Örneği çalıştırma

Aşağıdaki bölümlerde, örneğin Azure Spring Apps'e nasıl dağıtılacağı gösterilmektedir.

Önkoşullar

Spring projesini hazırlama

Projeyi hazırlamak için aşağıdaki adımları kullanın:

  1. Projeyi oluşturmak için aşağıdaki Maven komutunu kullanın:

    mvn clean package

  2. Aşağıdaki komutu kullanarak örnek projeyi yerel olarak çalıştırın:

    mvn spring-boot:run

Maven eklentisini yapılandırma

Azure Spring Apps için Maven eklentisini kullanarak uygulamayı yapılandırmak üzere projenin kökünde aşağıdaki komutu çalıştırın:

mvn com.microsoft.azure:azure-spring-apps-maven-plugin:1.19.0:config

Aşağıdaki listede komut etkileşimleri açıklanmaktadır:

  • OAuth2 oturum açma: OAuth2 protokolüne göre Azure'da oturum açmayı yetkilendirmeniz gerekir.
  • Aboneliği seçin: Azure Spring Apps örneğinizi oluşturmak istediğiniz abonelik listesi numarasını seçin. Bu numara varsayılan olarak listedeki ilk aboneliktir. Varsayılan sayıyı kullanmak istiyorsanız Enter tuşuna basın.
  • Azure Spring Apps adını girin: Oluşturmak istediğiniz spring apps örneğinin adını girin. Varsayılan adı kullanmak istiyorsanız Enter tuşuna basın.
  • Kaynak grubu adını girin: Spring apps örneğinizi oluşturmak istediğiniz kaynak grubunun adını girin. Varsayılan adı kullanmak istiyorsanız Enter tuşuna basın.
  • Sku'lar: Spring apps örneğiniz için kullanmak istediğiniz SKU'yu seçin. Varsayılan sayıyı kullanmak istiyorsanız Enter tuşuna basın.
  • Uygulama adını (tanıtım) girin: Bir uygulama adı girin. Varsayılan proje yapıt kimliğini kullanmak istiyorsanız Enter tuşuna basın.
  • Çalışma zamanları: Spring apps örneğiniz için kullanmak istediğiniz çalışma zamanını seçin. Bu durumda, varsayılan sayıyı kullanmanız gerekir, bu nedenle Enter tuşuna basın.
  • Bu uygulama için genel erişimi kullanıma sunma (azure için önyükleme): y tuşuna basın.
  • Yukarıdaki tüm yapılandırmaları kaydetmek için onaylayın: y tuşuna basın. n tuşuna basarsanız, yapılandırma .pom dosyasına kaydedilmez.

Aşağıdaki örnekte dağıtım işleminin çıkışı gösterilmektedir:

Summary of properties:
Subscription id   : 12345678-1234-1234-1234-123456789101
Resource group name : rg-ms-identity-spring-boot-webapp
Azure Spring Apps name : cluster-ms-identity-spring-boot-webapp
Runtime Java version : Java 11
Region            : eastus
Sku               : Standard
App name          : ms-identity-spring-boot-webapp
Public access     : true
Instance count/max replicas : 1
CPU count         : 1
Memory size(GB)   : 2
Confirm to save all the above configurations (Y/n):
[INFO] Configurations are saved to: /home/user/ms-identity-java-spring-tutorial/1-Authentication/sign-in/pom.    xml
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  01:57 min
[INFO] Finished at: 2024-02-14T13:50:44Z
[INFO] ------------------------------------------------------------------------

Seçimlerinizi onayladıktan sonra eklenti, uygulamanızı Azure Spring Apps'te çalışacak şekilde yapılandırmak için gerekli eklenti öğesini ve ayarlarını projenizin pom.xml dosyasına ekler.

pom.xml dosyasının ilgili bölümü aşağıdaki örneğe benzer olmalıdır:

<plugin>
    <groupId>com.microsoft.azure</groupId>
    <artifactId>azure-spring-apps-maven-plugin</artifactId>
    <version>1.19.0</version>
    <configuration>
        <subscriptionId>12345678-1234-1234-1234-123456789101</subscriptionId>
        <resourceGroup>rg-ms-identity-spring-boot-webapp</resourceGroup>
        <clusterName>cluster-ms-identity-spring-boot-webapp</clusterName>
        <region>eastus</region>
        <sku>Standard</sku>
        <appName>ms-identity-spring-boot-webapp</appName>
        <isPublic>true</isPublic>
        <deployment>
            <cpu>1</cpu>
            <memoryInGB>2</memoryInGB>
            <instanceCount>1</instanceCount>
            <runtimeVersion>Java 11</runtimeVersion>
            <resources>
                <resource>
                    <directory>${project.basedir}/target</directory>
                    <includes>
                        <include>*.jar</include>
                    </includes>
                </resource>
            </resources>
        </deployment>
    </configuration>
</plugin>

Azure Spring Apps yapılandırmalarını doğrudan pom.xml dosyanızda değiştirebilirsiniz. Bazı yaygın yapılandırmalar aşağıdaki tabloda listelenmiştir:

Özellik Zorunlu Açıklama
subscriptionId yanlış Abonelik kimliği.
resourceGroup true Azure Spring Apps örneğinin Azure kaynak grubu.
clusterName true Azure Spring Apps küme adı. Zaten bir Azure Spring Apps örneğinin dağıtılmış olduğu bir abonelik ve kaynak grubu kullanıyorsanız, dağıtmak için bu mevcut kümeyi de kullanabilirsiniz.
appName true Azure Spring Apps'te uygulamanızın adı.
region yanlış Azure Spring Apps örneğinizin barındırıldığı bölge. Varsayılan değer şudur: eastus. Geçerli bölgeler için bkz . Desteklenen Bölgeler.
sku yanlış Azure Spring Apps örneğinizin fiyatlandırma katmanı. Varsayılan değer, Basicyalnızca geliştirme ve test ortamları için uygun olan değeridir.
runtime yanlış Çalışma zamanı ortamı yapılandırması. Daha fazla bilgi için bkz . Yapılandırma Ayrıntıları.
deployment yanlış Dağıtım yapılandırması. Daha fazla bilgi için bkz . Yapılandırma Ayrıntıları.

Yapılandırmaların tam listesi için eklenti başvuru belgelerine bakın. Tüm Azure Maven eklentileri ortak bir yapılandırma kümesini paylaşır. Bu yapılandırmalar için bkz . Ortak Yapılandırmalar. Azure Spring Apps'e özgü yapılandırmalar için bkz . Azure Spring Apps: Yapılandırma Ayrıntıları.

ve appName değerlerini daha sonra kullanmak üzere bir kenara kaydettiğinizden clusterName emin olun.

Uygulamayı dağıtım için hazırlama

Uygulamanızı Azure Spring Apps'e dağıttığınızda, yeniden yönlendirme URL'niz Azure Spring Apps'te dağıtılan uygulama örneğinizin yeniden yönlendirme URL'sine dönüşür. application.yml dosyanızdaki bu ayarları değiştirmek için aşağıdaki adımları kullanın:

  1. Aşağıdaki örnekte gösterildiği gibi uygulamanızın src\main\resources\application.yml dosyasına gidin ve değerini post-logout-redirect-uri dağıtılan uygulamanızın etki alanı adıyla değiştirin. Örneğin, önceki adımda ve ms-identity-spring-boot-webapp uygulama adınız için Azure Spring Apps örneğinizi seçtiysenizcluster-ms-identity-spring-boot-webapp, şimdi değeri için post-logout-redirect-uri kullanmanız https://cluster-ms-identity-spring-boot-webapp-ms-identity-spring-boot-webapp.azuremicroservices.io gerekir.

    post-logout-redirect-uri: https://<cluster-name>-<app-name>.azuremicroservices.io

  2. Bu dosyayı kaydettikten sonra uygulamanızı yeniden derlemek için aşağıdaki komutu kullanın:

    mvn clean package

Önemli

Uygulamanın application.yml dosyası şu anda parametresindeki istemci gizli dizinizin değerini barındırıyor client-secret . Bu değeri bu dosyada tutmak iyi bir uygulama değildir. Bunu bir Git deposuna işliyorsanız da risk alıyor olabilirsiniz.

Ek bir güvenlik adımı olarak, bu değeri Azure Key Vault'ta depolayabilir ve anahtarı uygulamanızda kullanılabilir hale getirmek için Key Vault'tan yükleyebilirsiniz.

Microsoft Entra ID uygulama kaydınızı güncelleştirme

Azure Spring Apps'te yeniden yönlendirme URI'si dağıtılan uygulamanızda değiştiğinden, Microsoft Entra Id uygulama kaydınızda yeniden yönlendirme URI'sini de değiştirmeniz gerekir. Bu değişikliği yapmak için aşağıdaki adımları kullanın:

  1. Geliştiriciler için Microsoft kimlik platformu Uygulama kayıtları sayfasına gidin.

  2. Uygulama kaydınızı aramak için arama kutusunu kullanın; örneğin, java-servlet-webapp-authentication.

  3. Adını seçerek uygulama kaydınızı açın.

  4. Menüden Kimlik Doğrulaması'nı seçin.

  5. Web - Yeniden Yönlendirme URI'leri bölümünde URI Ekle'yi seçin.

  6. Uygulamanızın URI'sini doldurun; örneğin, https://<cluster-name>-<app-name>.azuremicroservices.io/login/oauth2/code/öğesini ekleyerek /login/oauth2/code/ .

  7. Kaydet'i seçin.

Uygulamayı dağıtma

Uygulamayı dağıtmak için aşağıdaki komutu kullanın:

mvn azure-spring-apps:deploy

Aşağıdaki listede komut etkileşimi açıklanmaktadır:

  • OAuth2 oturum açma: OAuth2 protokolüne göre Azure'da oturum açmayı yetkilendirmeniz gerekir.

Komut yürütüldükten sonra, dağıtımın başarılı olduğunu aşağıdaki günlük iletilerinden görebilirsiniz:

[INFO] Deployment(default) is successfully created
[INFO] Starting Spring App after deploying artifacts...
[INFO] Deployment Status: Running
[INFO]   InstanceName:demo-default-x-xxxxxxxxxx-xxxxx  Status:Running Reason:null       DiscoverStatus:UNREGISTERED
[INFO]   InstanceName:demo-default-x-xxxxxxxxx-xxxxx  Status:Terminating Reason:null       DiscoverStatus:UNREGISTERED
[INFO] Getting public url of app(demo)...
[INFO] Application url: https://<your-Azure-Spring-Apps-instance-name>-demo.azuremicroservices.io

Uygulamayı doğrulama

Dağıtım tamamlandıktan sonra çıkış uygulaması URL'si ile uygulamaya erişin. Herhangi bir dağıtım sorununu araştırmak üzere uygulamanın günlüklerini denetlemek için aşağıdaki adımları kullanın:

  1. Dağıtım bölümünün Çıkışlar sayfasından çıkış uygulaması URL'sine erişin.

  2. Azure Spring Apps örneğine Genel Bakış sayfasının gezinti bölmesinden Günlükler'i seçerek uygulamanın günlüklerini denetleyin.

Örneği keşfetme

Örneği keşfetmek için aşağıdaki adımları kullanın:

  1. Ekranın ortasında oturum açma veya oturum kapatma durumunun görüntülendiğine dikkat edin.
  2. Köşedeki bağlama duyarlı düğmeyi seçin. Bu düğme, uygulamayı ilk kez çalıştırdığınızda Oturum Aç'ı okur. Alternatif olarak belirteç ayrıntılarını da seçebilirsiniz. Bu sayfa korumalı olduğundan ve kimlik doğrulaması gerektirdiğinden, otomatik olarak oturum açma sayfasına yönlendirilirsiniz.
  3. Sonraki sayfada yönergeleri izleyin ve Microsoft Entra Id kiracısında bir hesapla oturum açın.
  4. Onay ekranında, istenen kapsamlara dikkat edin.
  5. Oturum açma akışını başarıyla tamamladıktan sonra, oturum açma akışınızı tetikleyen düğmeye bağlı olarak oturum açma durumunu gösteren giriş sayfasına veya belirteç ayrıntıları sayfasına yönlendirilmelisiniz.
  6. Bağlama duyarlı düğmenin artık Oturumu kapat ifadesinin gösterildiğine ve kullanıcı adınızı görüntülediğine dikkat edin.
  7. Giriş sayfasındaysanız kimlik belirtecinin çözülen taleplerinden bazılarını görmek için Kimlik Belirteci Ayrıntıları'nı seçin.
  8. Oturumu kapatmak için köşedeki düğmeyi kullanın. Durum sayfası yeni durumu yansıtır.

Kod hakkında

Bu örnek, Kullanıcıları Microsoft Entra ID kiracınızda oturum açmak üzere Java için Microsoft Entra ID Spring Boot Starter istemci kitaplığının nasıl kullanılacağını gösterir. Örnek ayrıca Spring Oauth2 İstemcisi ve Spring Web önyükleme başlatıcılarını da kullanır. Örnek, oturum açmış kullanıcının ayrıntılarını görüntülemek için Microsoft Entra Id'den alınan kimlik belirtecinden talepler kullanır.

İçindekiler

Aşağıdaki tabloda örnek proje klasörünün içeriği gösterilmektedir:

Dosya/klasör Açıklama
AppCreationScripts/ Microsoft Entra Id uygulama kayıtlarını otomatik olarak yapılandırmak için betikler.
pom.xml Uygulama bağımlılıkları.
src/main/resources/templates/ Kullanıcı arabirimi için Kekik Şablonları.
src/main/resources/application.yml Application ve Microsoft Entra ID Boot Starter Library Configuration.
src/main/java/com/microsoft/azuresamples/msal4j/msidentityspringbootwebapp/ Bu dizin ana uygulama giriş noktasını, denetleyiciyi ve yapılandırma sınıflarını içerir.
.../MsIdentitySpringBootWebappApplication.java Ana sınıf.
.../SampleController.java Uç nokta eşlemeleri olan denetleyici.
.../SecurityConfig.java Güvenlik yapılandırması - örneğin, hangi yolların kimlik doğrulaması gerektirdiği.
.../Utilities.java Yardımcı program sınıfı - örneğin, filtre kimliği belirteci talepleri.
CHANGELOG.md Örnekteki değişikliklerin listesi.
CONTRIBUTING.md Örneğe katkıda bulunma yönergeleri.
LİSANS Örneğin lisansı.

Kimlik belirteci talepleri

Belirteç ayrıntılarını ayıklamak için uygulama, aşağıdaki örnekte gösterildiği gibi bir istek eşlemesinde Spring Security'nin AuthenticationPrincipal ve OidcUser nesnesini kullanır. Bu uygulamanın kimlik belirteci taleplerini nasıl kullandığına ilişkin tüm ayrıntılar için Örnek Denetleyici'ye bakın.

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();
}

Oturum açmak için uygulama, aşağıdaki örnekte gösterildiği gibi Java için Microsoft Entra ID Spring Boot Starter istemci kitaplığı tarafından otomatik olarak yapılandırılan Microsoft Entra Id oturum açma uç noktasına bir istekte bulunur:

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

Oturum kapatma için uygulama, aşağıdaki örnekte gösterildiği gibi uç noktaya bir POST isteğinde logout bulunur:

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

Kimlik doğrulamasına bağımlı kullanıcı arabirimi öğeleri

Uygulamanın kullanıcı arabirimi şablonu sayfalarında, Spring Security Thymeleaf etiketlerini kullanan aşağıdaki örnekte gösterildiği gibi, kullanıcının kimliğinin doğrulanıp doğrulanmadığına göre görüntülenecek içeriği belirlemek için bazı basit mantık vardır:

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

AADWebSecurityConfigurerAdapter ile yolları koruma

Varsayılan olarak, uygulama kimlik belirteci ayrıntıları sayfasını yalnızca oturum açmış kullanıcıların erişebilmesi için korur. Uygulama, application.yml dosyasındaki app.protect.authenticatedözelliğini kullanarak bu yolları yapılandırıyor. Uygulamanızın özel gereksinimlerini yapılandırmak için yöntemini HttpSecurity örneğe uygulayınAadWebApplicationHttpSecurityConfigurer#aadWebApplication. Örneğin, aşağıdaki kodda gösterilen bu uygulamanın SecurityConfig sınıfına bakın:

@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();
    }    
}

Daha Fazla Bilgi

OAuth 2.0 protokollerinin bu senaryoda ve diğer senaryolarda nasıl çalıştığı hakkında daha fazla bilgi için bkz . Microsoft Entra Id için Kimlik Doğrulama Senaryoları.