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

Bu makalede, Java için Microsoft Entra ID Spring Boot Starter istemci kitaplığını kullanarak Microsoft Entra ID kiracınızda kullanıcıların oturum açmasını sağlayan bir Java Spring Boot web uygulaması gösterilmektedir. OpenID Connect protokolunu 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

  • Spring Framework hakkında biraz bilgi sahibi olmak.
  • Linux/OSX terminali hakkında biraz bilgi.
  • jwt.ms belirteçlerinizi incelemek için.
  • Fiddler ağ etkinliğinizi izlemek ve sorun gidermek için.
  • En son gelişmelerden haberdar olmak için Microsoft Entra Blogu'nu takip edin.

Örneği kurun

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-msal-java-samples.git
cd 4-spring-web-app/1-Authentication/sign-in

Alternatif olarak, ms-identity-msal-java-samples 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 kaydedin

Bu örnekte bir proje var. Aşağıdaki bölümlerde, Azure portalını kullanarak uygulamayı nasıl kaydedeceğiniz gösterilmektedir.

Uygulamalarınızı oluşturmak istediğiniz Microsoft Entra ID kiracısını seçin

Kiracınızı seçmek için aşağıdaki adımları kullanın:

  1. Azure Portal’ında oturum açın.

  2. Hesabınız birden fazla Microsoft Entra ID kiracısında varsa Azure portalının köşesindeki profilinizi seçin ve ardından Dizini değiştir'i seçerek oturumunuzu istediğiniz Microsoft Entra ID kiracısına değiştirin.

Uygulamayı kaydetme (java-spring-webapp-auth)

Uygulamayı kaydetmek için aşağıdaki adımları kullanın:

  1. Azure portalına gidin ve Microsoft Entra Id'yi seçin.

  2. Gezinti bölmesinde Uygulama kayıtları öğesini seçin ve ardından Yeni kayıt öğesini seçin.

  3. Görüntülenen Uygulamayı kaydet sayfasında aşağıdaki uygulama kayıt bilgilerini girin:

    • Name bölümünde, uygulamanın kullanıcılarına gösterilecek anlamlı bir uygulama adı girin; örneğin, java-spring-webapp-auth.
    • Desteklenen hesap türleri'nin altında Yalnızca tek kiracı - TENANT_NAME (TENANT_NAMEkiracıya göre değişir) seçeneğini belirleyin.
    • Yeniden Yönlendirme URI'si (isteğe bağlı) bölümünde, açılır kutudan Web'i seçin ve aşağıdaki yeniden yönlendirme URI'sini girin: http://localhost:8080/login/oauth2/code/.

  4. Uygulamayı kaydetmek için Kaydet'i seçin.

  5. Uygulamanın kayıt sayfasında, daha sonra kullanmak üzere Uygulama (istemci) kimliği değerini bulun ve kopyalayın. Bu değeri uygulamanızın yapılandırma dosyasında veya dosyalarında kullanırsınız.

  6. Uygulamanın kayıt sayfasında, gizli diziler oluşturabileceğiniz ve sertifikaları yükleyebileceğiniz sayfayı açmak için gezinti bölmesinde Sertifikalar ve gizli diziler seçeneğini belirleyin.

  7. Gizli anahtarlar bölümünün altında, Yeni gizli anahtar'ı seçin.

  8. Örneğin, app secret gibi bir açıklama yazın.

  9. Kullanılabilir sürelerden birini seçin : Önerilen: 180 gün (6 ay), 90 gün (3 ay), 365 gün (12 ay), 545 gün (18 ay) veya 730 gün (24 ay).

  10. Ekle'yi seçin. Oluşturulan değer görüntülenir.

  11. Oluşturulan değeri kopyalayıp sonraki adımlarda kullanmak üzere kaydedin. Kodunuzun yapılandırma dosyaları için bu değere ihtiyacınız vardır. Bu değer yeniden görüntülenmez ve başka bir yolla alamazsınız. Bu nedenle, başka bir ekrana veya bölmeye gitmeden önce Azure portalından kaydettiğinizden emin olun.

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, ClientID, Application ID veya AppId ile aynıdır.

  1. Projeyi IDE'nizde açın.

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

  3. Enter_Your_Tenant_ID_Here yer tutucusunu bulun ve mevcut değeri Microsoft Entra kiracı kimliğinizle değiştirin.

  4. Enter_Your_Client_ID_Here yer tutucusunu bulun ve var olan değeri java-spring-webapp-auth uygulamasının uygulama kimliği veya Azure portalından kopyaladığınız clientId ile değiştirin.

  5. Enter_Your_Client_Secret_Here yer tutucusunu bulun ve mevcut değeri, Azure portalından kopyaladığınız ve java-spring-webapp-auth oluşturulması sırasında kaydettiğiniz değerle değiştirin.

Örneği çalıştırma

Aşağıdaki bölümlerde, örneğin Azure Container 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 derlemek için aşağıdaki Maven komutunu kullanın:

    mvn clean verify

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

    mvn spring-boot:run

Ayarlama

CLI'dan Azure'da oturum açmak için aşağıdaki komutu çalıştırın ve istemleri izleyerek kimlik doğrulama işlemini tamamlayın.

az login

CLI'nın en son sürümünü çalıştırdığınızdan emin olmak için yükseltme komutunu çalıştırın.

az upgrade

Ardından CLI için Azure Container Apps uzantısını yükleyin veya güncelleştirin.

Azure CLI’da az containerapp komutlarını çalıştırdığınızda eksik parametre hataları alırsanız, Azure Container Apps uzantısının en güncel sürümünün kurulu olduğundan emin olun.

az extension add --name containerapp --upgrade

Not

Mayıs 2024'den itibaren Azure CLI uzantıları artık önizleme özelliklerini varsayılan olarak etkinleştirmez. Container Apps önizleme özelliklerine erişmek için Container Apps uzantısını --allow-preview true ile yükleyin.

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

Artık mevcut uzantı veya modül yüklendiğine göre, Microsoft.App ve Microsoft.OperationalInsights ad alanlarını kaydedin.

Not

Azure Container Apps kaynakları, Microsoft.Web ad alanından Microsoft.App ad alanına taşındı. Daha fazla bilgi için Microsoft.Web'den Microsoft.App'e Mart 2022 ad alanı geçişi bölümüne bakın.

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

Azure Container Apps ortamını oluşturma

Azure CLI kurulumunuz tamamlandıktan sonra bu makalenin tamamında kullanılan ortam değişkenlerini tanımlayabilirsiniz.

Bash kabuğunuzda aşağıdaki değişkenleri tanımlayın.

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"

Kaynak grubu oluşturun.

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

Otomatik olarak oluşturulan log analytics çalışma alanıyla bir ortam oluşturun.

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

Kapsayıcı uygulaması ortamının varsayılan etki alanını gösterin. Sonraki bölümlerde kullanmak için bu etki alanını not edin.

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

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

Uygulamanızı Azure Container Apps'e dağıttığınızda, yeniden yönlendirme URL'niz Azure Container 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 post-logout-redirect-uri değerini dağıtılmış uygulamanızın etki alanı adı olarak değiştirin. <API_NAME> ve <default-domain-of-container-app-environment> değerlerini gerçek değerlerinizle değiştirdiğinizden emin olun. Örneğin, önceki adımdan Azure Container App ortamınızın varsayılan etki alanını ve uygulama adınız için ms-identity-api değerini kullanarak, https://ms-identity-api.<default-domain> değeri için post-logout-redirect-uri kullanırsınız.

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

  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 istemci sırrınızın değerini client-secret parametresinde barındırıyor. Bu değeri bu dosyada tutmak iyi bir uygulama değildir. Dosyayı bir Git deposuna işlerseniz de risk alıyor olabilirsiniz. Önerilen yaklaşım için bkz. Azure Container Apps'te gizli dizileri yönetme.

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

Azure Container 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 platformundaki 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, sonuna /login/oauth2/code/ ekleyerek girin; örneğin, https://<containerapp-name>.<default domain of container app environment>/login/oauth2/code/.

  7. Kaydet'i seçin.

Uygulamayı dağıt

JAR paketini Azure Container Apps'e dağıtın.

Not

Gerekirse Java derleme ortamı değişkenlerinde JDK sürümünü belirtebilirsiniz. Daha fazla bilgi için Azure Container Apps'te Java için derleme ortamı değişkenleri bölümüne bakın.

Artık WAR dosyanızı az containerapp up CLI komutuyla dağıtabilirsiniz.

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

Not

Varsayılan JDK sürümü 17'dir. Uygulamanızla uyumluluk sağlamak için JDK sürümünü değiştirmeniz gerekiyorsa, sürüm numarasını ayarlamak üzere --build-env-vars BP_JVM_VERSION=<YOUR_JDK_VERSION> argümanını kullanabilirsiniz.

Daha fazla derleme ortamı değişkeni için bkz. Azure Container Apps'te Java için derleme ortamı değişkenleri.

Uygulamayı doğrulama

Bu örnekte, containerapp up komutu, uygulamanın URL’si olarak da bilinen tam etki alanı adını (FQDN) döndüren --query properties.configuration.ingress.fqdn argümanını içerir. 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. Uygulamanın günlüklerini kontrol etmek için Azure Container Apps örneğinin Genel Bakış sayfasındaki gezinti bölmesinden Günlükler'i seçin.

Örneği keşfedin

Ö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. Uygulamayı ilk kez çalıştırdığınızda bu düğmede Oturum Aç yazar. Alternatif olarak, belirteç ayrıntıları'nı seçin. 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. Ana sayfadaysanız, kimlik belirtecinin çözümlenmiş 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ın Microsoft Entra ID kiracınızda oturum açmasını sağlamak için 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
pom.xml Uygulama bağımlılıkları.
src/main/resources/templates/ Kullanıcı arayüzü için Thymeleaf şablonları.
src/main/resources/application.yml Uygulama ve Microsoft Entra ID Boot Starter Kitaplığı Yapılandırması.
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ı sınıf - örneğin, kimlik belirteci istemlerini filtrelemek için.
CHANGELOG.md Örnekteki değişikliklerin listesi.
CONTRIBUTING.md Örneğe katkıda bulunma yönergeleri.
LİSANS Örnek 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 nesnelerinden yararlanır. Bu uygulamanın ID belirteci claim’lerini 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>

Oturumu kapatmak için uygulama, aşağıdaki örnekte gösterildiği gibi logout uç noktasına bir POST isteğinde 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, bu rotaları app.protect.authenticated dosyasındaki özelliğini kullanarak yapılandırır. Uygulamanızın özel gereksinimlerini yapılandırmak için, AadWebApplicationHttpSecurityConfigurer#aadWebApplication yöntemini HttpSecurity örneğine uygulayın. Bir örnek iç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 Microsoft Entra ID için Kimlik Doğrulama Senaryoları konusuna bakın.

  • Last updated on