次の方法で共有


Microsoft Entra 用の Spring Boot Starter の開発者ガイド

この記事の対象: ✔️ バージョン 4.19.0 ✔️ バージョン 5.17.0

この記事では、Spring Boot Starter for Microsoft Entra ID の機能と主要なシナリオについて説明します。 この記事には、一般的な問題、回避策、診断手順に関するガイダンスも含まれています。

Web アプリケーションを構築する場合、ID とアクセス管理は基本的な要素です。 Azure には、Azure エコシステムの他の部分と緊密に統合されたクラウドベースの ID サービスが用意されています。

Spring Security を使用すると、Spring ベースのアプリケーションを簡単に保護できますが、特定の ID プロバイダーに合わせて調整されてはいません。 Spring Boot Starter for Microsoft Entra ID を使用すると、Web アプリケーションを Microsoft Entra テナントに接続し、Microsoft Entra ID でリソース サーバーを保護できます。 これは Oauth 2.0 プロトコルを使用して、Web アプリケーションとリソース サーバーを保護します。

次のリンクを使用すると、スターター パッケージ、ドキュメント、およびサンプルにアクセスできます。

前提条件

このガイドの手順に従うには、次の前提条件を満たしている必要があります。

重要

この記事の手順を完了するには、Spring Boot 2.5 以降のバージョンが必要です。

主要なシナリオ

このガイドでは、次のシナリオで Microsoft Entra スターターを使用する方法について説明します。

"Web アプリケーション" は、ユーザーがサインインできるようにする任意の Web ベースのアプリケーションです。 "リソース サーバー" は、アクセス トークンの検証後にアクセスを許可または拒否します。

Web アプリケーションにアクセスする

このシナリオでは、OAuth 2.0 認可コード付与フローを使用して、ユーザーが Microsoft アカウントでサインインできるようにします。

このシナリオで Microsoft Entra スターターを使用するには、次の手順を使用します。

リダイレクト URI を <application-base-uri>/login/oauth2/code/ に設定します。 (例: http://localhost:8080/login/oauth2/code/)。 必ず、末尾の / を含めるようにしてください。 リダイレクト URI の詳細については、「クイック スタート: Microsoft ID プラットフォームにアプリケーションを登録する」の「リダイレクト URI を追加する」を参照してください。

リダイレクト URI が強調表示された Web アプリ認証ページを示す Azure Portal のスクリーンショット。

pom.xml ファイルに次の依存関係を追加します。

<dependency>
   <groupId>com.azure.spring</groupId>
   <artifactId>spring-cloud-azure-starter-active-directory</artifactId>
</dependency>
<dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-oauth2-client</artifactId>
</dependency>

Note

部品表 (BOM) を使用して Spring Cloud Azure ライブラリのバージョンを管理する方法の詳細については、 「Spring Cloud Azure 開発者ガイド」「概要」 セクションを参照してください。

application.yml ファイルに次のプロパティを追加します。 これらのプロパティの値は、前提条件で説明されているように、Azure portal で作成したアプリの登録から取得できます。

spring:
 cloud:
   azure:
     active-directory:
       enabled: true
       profile:
         tenant-id: <tenant>
       credential:
         client-id: <your-client-ID>
         client-secret: <your-client-secret>

Note

tenant-id に使用できる値: commonorganizationsconsumers、またはテナント ID。 これらの値の詳細については、「エラー AADSTS50020 - ID プロバイダーのユーザー アカウントがテナントに存在しない」の「間違ったエンドポイント (個人用アカウントと organization アカウント) を使用しました」セクションを参照してください。 シングルテナント アプリの変換については、「Microsoft Entra ID でシングルテナント アプリをマルチテナントに変換する」を参照してください。

既定のセキュリティ構成を使用するか、独自の構成を指定します。

オプション 1: 既定の構成を使用します。

このオプションを使用する場合、何もする必要はありません。 DefaultAadWebSecurityConfigurerAdapter クラスは自動的に構成されます。

オプション 2: 自己定義の構成を指定します。

構成を指定するには、次の例に示すように、AadWebSecurityConfigurerAdapter クラスを拡張し、configure(HttpSecurity http) 関数で super.configure(http) を呼び出します。

@EnableWebSecurity
@EnableGlobalMethodSecurity(prePostEnabled = true)
public class AadOAuth2LoginSecurityConfig extends AadWebSecurityConfigurerAdapter {

   /**
    * Add configuration logic as needed.
   */
   @Override
   protected void configure(HttpSecurity http) throws Exception {
       super.configure(http);
       http.authorizeRequests()
           .anyRequest().authenticated();
       // Do some custom configuration.
   }
}

Web アプリケーションからリソース サーバーにアクセスする

このシナリオで Microsoft Entra スターターを使用するには、次の手順を使用します。

前に説明したようにリダイレクト URI を設定します。

pom.xml ファイルに次の依存関係を追加します。

<dependency>
   <groupId>com.azure.spring</groupId>
   <artifactId>spring-cloud-azure-starter-active-directory</artifactId>
</dependency>
<dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-oauth2-client</artifactId>
</dependency>

Note

部品表 (BOM) を使用して Spring Cloud Azure ライブラリのバージョンを管理する方法の詳細については、 「Spring Cloud Azure 開発者ガイド」「概要」 セクションを参照してください。

前に説明したように、application.yml ファイルに次のプロパティを追加します。

spring:
 cloud:
   azure:
     active-directory:
       enabled: true
       profile:
         tenant-id: <tenant>
       credential:
         client-id: <your-client-ID>
         client-secret: <your-client-secret>
       authorization-clients:
         graph:
           scopes: https://graph.microsoft.com/Analytics.Read, email

Note

tenant-id に使用できる値: commonorganizationsconsumers、またはテナント ID。 これらの値の詳細については、「エラー AADSTS50020 - ID プロバイダーのユーザー アカウントがテナントに存在しない」の「間違ったエンドポイント (個人用アカウントと organization アカウント) を使用しました」セクションを参照してください。 シングルテナント アプリの変換については、「Microsoft Entra ID でシングルテナント アプリをマルチテナントに変換する」を参照してください。

ここで、graphOAuth2AuthorizedClient の名前であり、scopes はログイン時の同意に必要なスコープです。

次の例のように、アプリケーションにコードを追加します。

@GetMapping("/graph")
@ResponseBody
public String graph(
   @RegisteredOAuth2AuthorizedClient("graph") OAuth2AuthorizedClient graphClient
) {
   // toJsonString() is just a demo.
   // oAuth2AuthorizedClient contains access_token. We can use this access_token to access the resource server.
   return toJsonString(graphClient);
}

ここで、graph は、前の手順で構成したクライアント ID です。 OAuth2AuthorizedClient には、リソース サーバーへのアクセスに使用されるアクセス トークンが含まれています。

このシナリオを示す完全なサンプルについては、spring-cloud-azure-starter-active-directory サンプル: aad-web-application を参照してください。

リソース サーバーまたは API を保護する

このシナリオではサインインはサポートされていませんが、アクセス トークンを検証することによってサーバーを保護します。 アクセス トークンが有効な場合、サーバーによって要求が処理されます。

このシナリオで Microsoft Entra スターターを使用するには、次の手順を使用します。

pom.xml ファイルに次の依存関係を追加します。

<dependency>
   <groupId>com.azure.spring</groupId>
   <artifactId>spring-cloud-azure-starter-active-directory</artifactId>
</dependency>
<dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
</dependency>

Note

部品表 (BOM) を使用して Spring Cloud Azure ライブラリのバージョンを管理する方法の詳細については、 「Spring Cloud Azure 開発者ガイド」「概要」 セクションを参照してください。

前に説明したように、application.yml ファイルに次のプロパティを追加します。

spring:
 cloud:
   azure:
     active-directory:
       enabled: true
       credential:
         client-id: <your-client-ID>
       app-id-uri: <your-app-ID-URI>

アクセス トークンの確認には、<your-client-ID><your-app-ID-URI> の両方の値を使用できます。 次の図に示すように、Azure portal から <your-app-ID-URI> 値を取得できます。

アプリケーション ID URI が強調表示された API ページが公開された Web アプリを示す Azure Portalのスクリーンショット。

既定のセキュリティ構成を使用するか、独自の構成を指定します。

オプション 1: 既定の構成を使用します。

このオプションを使用する場合、何もする必要はありません。 DefaultAadResourceServerWebSecurityConfigurerAdapter クラスは自動的に構成されます。

オプション 2: 自己定義の構成を指定します。

構成を指定するには、次の例に示すように、AadResourceServerWebSecurityConfigurerAdapter クラスを拡張し、configure(HttpSecurity http) 関数で super.configure(http) を呼び出します。

@EnableWebSecurity
@EnableGlobalMethodSecurity(prePostEnabled = true)
public class AadOAuth2ResourceServerSecurityConfig extends AadResourceServerWebSecurityConfigurerAdapter {

   /**
    * Add configuration logic as needed.
    */
   @Override
   protected void configure(HttpSecurity http) throws Exception {
       super.configure(http);
       http.authorizeRequests((requests) -> requests.anyRequest().authenticated());
   }
}

このシナリオを示す完全なサンプルについては、spring-cloud-azure-starter-active-directory サンプル: aad-resource-server を参照してください。

リソース サーバーから他のリソース サーバーにアクセスする

このシナリオでは、他のリソース サーバーにアクセスするリソース サーバーをサポートします。

このシナリオで Microsoft Entra スターターを使用するには、次の手順を使用します。

pom.xml ファイルに次の依存関係を追加します。

<dependency>
   <groupId>com.azure.spring</groupId>
   <artifactId>spring-cloud-azure-starter-active-directory</artifactId>
</dependency>
<dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
</dependency>
<dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-oauth2-client</artifactId>
</dependency>

Note

部品表 (BOM) を使用して Spring Cloud Azure ライブラリのバージョンを管理する方法の詳細については、 「Spring Cloud Azure 開発者ガイド」「概要」 セクションを参照してください。

application.yml ファイルに次のプロパティを追加します。

spring:
 cloud:
   azure:
     active-directory:
       enabled: true
       profile:
         tenant-id: <tenant>
       credential:
         client-id: <web-API-A-client-ID>
         client-secret: <web-API-A-client-secret>
       app-id-uri: <web-API-A-app-ID-URI>
       authorization-clients:
         graph:
           scopes:
              - https://graph.microsoft.com/User.Read

Note

tenant-id に使用できる値: commonorganizationsconsumers、またはテナント ID。 これらの値の詳細については、「エラー AADSTS50020 - ID プロバイダーのユーザー アカウントがテナントに存在しない」の「間違ったエンドポイント (個人用アカウントと organization アカウント) を使用しました」セクションを参照してください。 シングルテナント アプリの変換については、「Microsoft Entra ID でシングルテナント アプリをマルチテナントに変換する」を参照してください。

関連するリソース サーバーにアクセスするには、次の例に示すように、コードで @RegisteredOAuth2AuthorizedClient 属性を使用します。

@PreAuthorize("hasAuthority('SCOPE_Obo.Graph.Read')")
@GetMapping("call-graph")
public String callGraph(@RegisteredOAuth2AuthorizedClient("graph") OAuth2AuthorizedClient graph) {
   return callMicrosoftGraphMeEndpoint(graph);
}

このシナリオを示す完全なサンプルについては、spring-cloud-azure-starter-active-directory サンプル: aad-resource-server-obo を参照してください。

1 つのアプリケーション内の Web アプリケーションとリソース サーバー

このシナリオでは、Web アプリケーションへのアクセスリソース サーバーまたは API の保護を 1 つのアプリケーションでサポートします。

このシナリオで aad-starter を使用するには、次の手順を実行します。

pom.xml ファイルに次の依存関係を追加します。

<dependency>
   <groupId>com.azure.spring</groupId>
   <artifactId>spring-cloud-azure-starter-active-directory</artifactId>
</dependency>
<dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
</dependency>
<dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-oauth2-client</artifactId>
</dependency>

Note

部品表 (BOM) を使用して Spring Cloud Azure ライブラリのバージョンを管理する方法の詳細については、 「Spring Cloud Azure 開発者ガイド」「概要」 セクションを参照してください。

application.yml ファイルを更新します。 次の例で示すように、spring.cloud.azure.active-directory.application-type プロパティを web_application_and_resource_server に設定し、各承認クライアントの承認の種類を指定します。

spring:
 cloud:
   azure:
     active-directory:
       enabled: true
       profile:
         tenant-id: <tenant>
       credential:
         client-id: <Web-API-C-client-id>
         client-secret: <Web-API-C-client-secret>
       app-id-uri: <Web-API-C-app-id-url>
       application-type: web_application_and_resource_server  # This is required.
       authorization-clients:
         graph:
           authorizationGrantType: authorization_code  # This is required.
           scopes:
             - https://graph.microsoft.com/User.Read
             - https://graph.microsoft.com/Directory.Read.All

Note

tenant-id に使用できる値: commonorganizationsconsumers、またはテナント ID。 これらの値の詳細については、「エラー AADSTS50020 - ID プロバイダーのユーザー アカウントがテナントに存在しない」の「間違ったエンドポイント (個人用アカウントと organization アカウント) を使用しました」セクションを参照してください。 シングルテナント アプリの変換については、「Microsoft Entra ID でシングルテナント アプリをマルチテナントに変換する」を参照してください。

複数の HttpSecurity インスタンスを構成する Java コードを記述します。

次のコード例では、AadWebApplicationAndResourceServerConfig に 2 つのセキュリティ構成が含まれています。1 つはリソース サーバー用で、もう 1 つは Web アプリケーション用です。 ApiWebSecurityConfigurationAdapter クラスの、リソース サーバーのセキュリティ アダプターの構成は、高い優先順位です。 HtmlWebSecurityConfigurerAdapter クラスの、Web アプリケーションのセキュリティ アダプターの構成は、低い優先順位です。

@EnableWebSecurity
@EnableGlobalMethodSecurity(prePostEnabled = true)
public class AadWebApplicationAndResourceServerConfig {

   @Order(1)
   @Configuration
   public static class ApiWebSecurityConfigurationAdapter extends AadResourceServerWebSecurityConfigurerAdapter {
       protected void configure(HttpSecurity http) throws Exception {
           super.configure(http);
           // All the paths that match `/api/**`(configurable) work as the esource server. Other paths work as  the web application.
           http.antMatcher("/api/**")
               .authorizeRequests().anyRequest().authenticated();
       }
   }

   @Configuration
   public static class HtmlWebSecurityConfigurerAdapter extends AadWebSecurityConfigurerAdapter {

       @Override
       protected void configure(HttpSecurity http) throws Exception {
           super.configure(http);
           // @formatter:off
           http.authorizeRequests()
                   .antMatchers("/login").permitAll()
                   .anyRequest().authenticated();
           // @formatter:on
       }
   }
}

アプリケーションの種類

spring.cloud.azure.active-directory.application-type プロパティは、依存関係によってその値を推定できるので、省略可能です。 web_application_and_resource_server 値を使用する場合にのみ、プロパティを手動で設定する必要があります。

依存関係: spring-security-oauth2-client 依存関係: spring-security-oauth2-resource-server アプリケーションの種類の有効な値 規定値
はい いいえ web_application web_application
番号 イエス resource_server resource_server
イエス はい web_applicationresource_server
resource_server_with_obo, web_application_and_resource_server
resource_server_with_obo

構成プロパティ

Microsoft Entra ID 用の Spring Boot Starter には、次のプロパティがあります。

プロパティ 説明
spring.cloud.azure.active-directory.app-id-uri リソース サーバーがアクセス トークンの対象ユーザーを検証するために使用します。 アクセス トークンは、対象ユーザーが前に説明した <your-client-ID> または <your-app-ID-URI> の値と等しい場合にのみ有効です。
spring.cloud.azure.active-directory.authorization-clients アプリケーションがアクセスするリソース API を構成するマップ。 各項目は、アプリケーションがアクセスする 1 つのリソース API に対応します。 Spring コードでは、各項目は 1 つの OAuth2AuthorizedClient オブジェクトに対応します。
spring.cloud.azure.active-directory.authorization-clients.<your-client-name>.scopes アプリケーションが取得するリソース サーバーの API アクセス許可。
spring.cloud.azure.active-directory.authorization-clients.<your-client-name>.authorization-grant-type 認証クライアントの種類。 サポートされている種類は、authorization_code (webapp の既定の種類)、on_behalf_of (resource-server の既定の種類)、client_credentials です。
spring.cloud.azure.active-directory.application-type アプリケーションの種類」を参照してください。
spring.cloud.azure.active-directory.profile.environment.active-directory-endpoint 承認サーバーのベース URI。 既定値は https://login.microsoftonline.com/ です。
spring.cloud.azure.active-directory.credential.client-id Microsoft Entra ID で登録されたアプリケーション ID。
spring.cloud.azure.active-directory.credential.client-secret 登録されているアプリケーションのクライアント シークレット。
spring.cloud.azure.active-directory.user-group.use-transitive-members v1.0/me/transitiveMemberOftrue に設定されている場合は、グループを取得するために を使用します。 それ以外の場合は、/v1.0/me/memberOf を使用します。
spring.cloud.azure.active-directory.post-logout-redirect-uri サインアウトを POST するためのリダイレクト URI。
spring.cloud.azure.active-directory.profile.tenant-id Azure テナント ID。 tenant-id に使用できる値: commonorganizationsconsumers、またはテナント ID。
spring.cloud.azure.active-directory.user-group.allowed-group-names MemberOf Graph API 呼び出しからの応答で見つかった場合に、権限が付与される予定のユーザー グループ。
spring.cloud.azure.active-directory.user-name-attribute どのクレームがプリンシパルの名前になるかを示します。

次の例は、これらのプロパティの使用方法を示します。

プロパティ例 1: Azure グローバルの代わりに Azure China 21Vianet を使用するには、次の手順に従います。

  • application.yml ファイルに次のプロパティを追加します。

    spring:
       cloud:
         azure:
           active-directory:
             enabled: true
             profile:
               environment:
                 active-directory-endpoint: https://login.partner.microsoftonline.cn
    

この方法を使用した場合は、Azure パブリック クラウドの代わりに Azure ソブリン クラウド (国内クラウド) を使用できます。

プロパティ例 2: グループ名を使用して Web アプリケーションの一部のメソッドを保護するには、次の手順に従います。

application.yml ファイルに次のプロパティを追加します。

spring:
 cloud:
   azure:
     active-directory:
       enabled: true
       user-group:
         allowed-groups: group1, group2

既定のセキュリティ構成を使用するか、独自の構成を指定します。

オプション 1: 既定の構成を使用します。 このオプションを使用する場合、何もする必要はありません。 DefaultAadWebSecurityConfigurerAdapter クラスは自動的に構成されます。

オプション 2: 自己定義の構成を指定します。 構成を指定するには、次の例に示すように、AadWebSecurityConfigurerAdapter クラスを拡張し、configure(HttpSecurity http) 関数で super.configure(http) を呼び出します。

@EnableWebSecurity
@EnableGlobalMethodSecurity(prePostEnabled = true)
public class AadOAuth2LoginSecurityConfig extends AadWebSecurityConfigurerAdapter {

   /**
    * Add configuration logic as needed.
    */
   @Override
   protected void configure(HttpSecurity http) throws Exception {
       super.configure(http);
       http.authorizeRequests()
           .anyRequest().authenticated();
       // Do some custom configuration.
   }
}

次の例に示すように、@PreAuthorize 注釈を使用してメソッドを保護します。

@Controller
public class RoleController {
   @GetMapping("group1")
   @ResponseBody
   @PreAuthorize("hasRole('ROLE_group1')")
   public String group1() {
       return "group1 message";
   }

   @GetMapping("group2")
   @ResponseBody
   @PreAuthorize("hasRole('ROLE_group2')")
   public String group2() {
       return "group2 message";
   }

   @GetMapping("group1Id")
   @ResponseBody
   @PreAuthorize("hasRole('ROLE_<group1-id>')")
   public String group1Id() {
       return "group1Id message";
   }

   @GetMapping("group2Id")
   @ResponseBody
   @PreAuthorize("hasRole('ROLE_<group2-id>')")
   public String group2Id() {
       return "group2Id message";
   }
}

プロパティ例 3: リソース サーバーにアクセスするリソース サーバーでクライアント資格情報のフローを有効にするには、次の手順に従います。

application.yml ファイルに次のプロパティを追加します。

spring:
 cloud:
   azure:
     active-directory:
       enabled: true
       authorization-clients:
         webapiC:   # When authorization-grant-type is null, on behalf of flow is used by default
           authorization-grant-type: client_credentials
           scopes:
             - <Web-API-C-app-id-url>/.default

次の例のように、アプリケーションにコードを追加します。

@PreAuthorize("hasAuthority('SCOPE_Obo.WebApiA.ExampleScope')")
@GetMapping("webapiA/webapiC")
public String callClientCredential() {
   String body = webClient
       .get()
       .uri(CUSTOM_LOCAL_READ_ENDPOINT)
       .attributes(clientRegistrationId("webapiC"))
       .retrieve()
       .bodyToMono(String.class)
       .block();
   LOGGER.info("Response from Client Credential: {}", body);
   return "client Credential response " + (null != body ? "success." : "failed.");
}

高度な機能

Web アプリケーションでの ID トークンによるアクセス制御のサポート

スターターでは、ID トークンの roles クレームからの GrantedAuthority の作成がサポートされています。これにより、Web アプリケーションでの承認に ID トークンを使用できるようになります。 Microsoft Entra ID の appRoles 機能を使用すると、roles クレームを作成し、アクセス制御を実装できます。

Note

appRoles から生成された roles クレームは、プレフィックス APPROLE_ で修飾されます。

appRolesroles クレームとして使用する場合は、グループ属性を roles として同時に構成しないようにしてください。 そうしないと、グループ属性によって、appRoles の代わりにグループ情報を含むようにクレームがオーバーライドされます。 マニフェストでは、次の構成を避ける必要があります。

"optionalClaims": {
    "idtoken": [{
        "name": "groups",
        "additionalProperties": ["emit_as_roles"]
    }]
}

Web アプリケーションで ID トークンによるアクセス制御をサポートするには、次の手順に従います。

アプリケーションにアプリ ロールを追加し、ユーザーまたはグループに割り当てます。 詳細については、方法: アプリケーションにアプリ ロールを追加してトークンで受け取るに関する記事を参照してください。

アプリケーションのマニフェストに次の appRoles 構成を追加します。

 "appRoles": [
   {
     "allowedMemberTypes": [
       "User"
     ],
     "displayName": "Admin",
     "id": "2fa848d0-8054-4e11-8c73-7af5f1171001",
     "isEnabled": true,
     "description": "Full admin access",
     "value": "Admin"
    }
 ]

次の例のように、アプリケーションにコードを追加します。

@GetMapping("Admin")
@ResponseBody
@PreAuthorize("hasAuthority('APPROLE_Admin')")
public String Admin() {
   return "Admin message";
}

トラブルシューティング

クライアントのログ記録を有効にする

Azure SDK for Javaには、アプリケーション エラーのトラブルシューティングと解決に役立つ一貫したログ ストーリーが用意されています。 生成されたログには、最終状態に達する前のアプリケーションのフローがキャプチャされ、根本原因を特定するのに役立ちます。 ログの有効化に関するガイダンスについては、ログに関する Wiki を参照してください。

Spring ログの有効化

Spring を使用すると、サポートされているすべてのログ システムが Spring 環境で (たとえば application.properties で) ロガー レベルを設定できるようになります。これには logging.level.<logger-name>=<level> を使用します。ここで、level は TRACE、DEBUG、INFO、WARN、ERROR、FATAL、OFF のいずれかです。 ルート ロガーは、logging.level.root を使用して構成できます。

次の例では、application.properties ファイルの考えられるログ設定を示します。

logging.level.root=WARN
logging.level.org.springframework.web=DEBUG
logging.level.org.hibernate=ERROR

Spring のログ構成の詳細については、Spring ドキュメントの「Logging」 (ログ) を参照してください。

次のステップ

Spring および Azure の詳細については、Azure ドキュメント センターで引き続き Spring に関するドキュメントをご確認ください。