Clarify AAD properties for Spring Cloud Azure (#33538)

.vscode/cspell.json

@@ -953,6 +953,7 @@
         "OIDC",
         "qpid",
         "reqoest",
+        "signin",
         "Spel",
         "sqldb",
         "SQLDB",

sdk/spring/CHANGELOG.md

@@ -14,6 +14,14 @@ This section includes changes in `spring-cloud-azure-stream-binder-eventhubs` mo
 #### Breaking Changes
 - Make the default partition behavior of Spring Cloud Azure EventHubs binder be a round-robin assignment to align with Event Hubs.[#32816](https://github.com/Azure/azure-sdk-for-java/pull/32816).
 
+### Spring Cloud Azure Autoconfigure
+This section includes changes in `spring-cloud-azure-autoconfigure` module.
+
+#### Breaking Changes
+- Deprecated properties for AAD and AAD B2C. [#29471](https://github.com/Azure/azure-sdk-for-java/pull/33538).
+  - Deprecated properties `spring.cloud.azure.active-directory.jwt-connect-timeout`, `spring.cloud.azure.active-directory.jwt-read-timeout`, `spring.cloud.azure.active-directory.jwt-size-limit`, if you want to configure them, please provide a RestOperations bean.
+  - Deprecated properties `spring.cloud.azure.active-directory.b2c.jwt-connect-timeout`, `spring.cloud.azure.active-directory.b2c.jwt-read-timeout`, `spring.cloud.azure.active-directory.b2c.jwt-size-limit`, if you want to configure them, please provide a RestOperations bean.
+
 ## 4.6.0 (2023-02-07)
 - This release is compatible with Spring Boot 2.5.0-2.5.14, 2.6.0-2.6.14, 2.7.0-2.7.8. (Note: 2.5.x (x>14), 2.6.y (y>14) and 2.7.z (z>8) should be supported, but they aren't tested with this release.)
 - This release is compatible with Spring Cloud 2020.0.3-2020.0.6, 2021.0.0-2021.0.5. (Note: 2020.0.x (x>6) and 2021.0.y (y>5) should be supported, but they aren't tested with this release.)

sdk/spring/spring-cloud-azure-autoconfigure/src/main/java/com/azure/spring/cloud/autoconfigure/aad/properties/AadAuthenticationProperties.java

@@ -82,42 +82,51 @@ public class AadAuthenticationProperties implements InitializingBean {
     private String redirectUriTemplate = "{baseUrl}/login/oauth2/code/";
 
     /**
-     * App ID URI which might be used in the "aud" claim of an id_token.
+     * App ID URI which might be used in the "aud" claim of an id_token. For instance, 'api://{applicationId}'.
+     * See Microsoft doc about APP ID URL for more details: https://learn.microsoft.com/azure/active-directory/develop/security-best-practices-for-app-registration#application-id-uri
      */
     private String appIdUri;
 
     /**
-     * Add additional parameters to the Authorization URL.
+     * Additional parameters above the standard parameters defined in the OAuth 2.0 Authorization Framework. Would be added to the Authorization URL for customizing the Authorization Request. For instance, 'prompt: login'.
+     * See Microsoft doc about more additional parameters information: https://learn.microsoft.com/azure/active-directory/develop/v2-oauth2-auth-code-flow#request-an-authorization-code
      */
     private final Map<String, Object> authenticateAdditionalParameters = new HashMap<>();
 
     /**
-     * Connection Timeout for the JWKSet Remote URL call. Deprecated. If you want to configure this, please provide a RestOperations bean.
+     * Connection Timeout(duration) for the JWKSet Remote URL call. The default value is `500s`.
+     * @deprecated If you want to configure this, please provide a RestOperations bean.
      */
+    @Deprecated
     private Duration jwtConnectTimeout = Duration.ofMillis(RemoteJWKSet.DEFAULT_HTTP_CONNECT_TIMEOUT);
 
     /**
-     * Read Timeout for the JWKSet Remote URL call. Deprecated. If you want to configure this, please provide a RestOperations bean.
+     * Read Timeout(duration) for the JWKSet Remote URL call. The default value is `500s`.
+     * @deprecated If you want to configure this, please provide a RestOperations bean.
      */
+    @Deprecated
     private Duration jwtReadTimeout = Duration.ofMillis(RemoteJWKSet.DEFAULT_HTTP_READ_TIMEOUT);
 
     /**
-     * Size limit in Bytes of the JWKSet Remote URL call. Deprecated. If you want to configure this, please provide a RestOperations bean.
+     * Size limit in Bytes of the JWKSet Remote URL call. The default value is `51200`.
+     * @deprecated If you want to configure this, please provide a RestOperations bean.
      */
+    @Deprecated
     private int jwtSizeLimit = RemoteJWKSet.DEFAULT_HTTP_SIZE_LIMIT; /* bytes */
 
     /**
-     * The lifespan of the cached JWK set before it expires, default is 5 minutes.
+     * The lifespan(duration) of the cached JWK set before it expires. The default value is `5m`.
      */
     private Duration jwkSetCacheLifespan = Duration.ofMinutes(5);
 
     /**
-     * The refresh time of the cached JWK set before it expires, default is 5 minutes.
+     * The refresh time(duration) of the cached JWK set before it expires. The default value is `5m`.
      */
     private Duration jwkSetCacheRefreshTime = Duration.ofMinutes(5);
 
     /**
-     * The redirect uri after logout.
+     * The redirect uri after logout. For instance, 'http://localhost:8080/'.
+     * See Microsoft doc about Redirect URI for more details: https://learn.microsoft.com/azure/active-directory/develop/security-best-practices-for-app-registration#redirect-uri
      */
     private String postLogoutRedirectUri;
 
@@ -128,12 +137,19 @@ public class AadAuthenticationProperties implements InitializingBean {
     private Boolean sessionStateless = false;
 
     /**
-     * The OAuth2 authorization clients.
+     * The OAuth2 authorization clients, contains the authorization grant type, client authentication method and scope.
+     * The clients will be converted to OAuth2 ClientRegistration, the other ClientRegistration information(such as client id, client secret) inherits from the delegated OAuth2 login client 'azure'.
+     * For instance,'
+     * authorization-clients.webapi.authorization-grant-type=on_behalf_of,
+     * authorization-clients.webapi.client-authentication-method=client_secret_post,
+     * authorization-clients.webapi.scopes[0]={WEB_API_APP_ID_URL}/WebApi.ExampleScope1,
+     * authorization-clients.webapi.scopes[0]={WEB_API_APP_ID_URL}/WebApi.ExampleScope2
+     * '.
      */
     private final Map<String, AuthorizationClientProperties> authorizationClients = new HashMap<>();
 
     /**
-     * Type of the Azure AD application.
+     * Type of the Azure AD application. Supported types are: WEB_APPLICATION, RESOURCE_SERVER, RESOURCE_SERVER_WITH_OBO, WEB_APPLICATION_AND_RESOURCE_SERVER. The value can be inferred by dependencies, only 'web_application_and_resource_server' must be configured manually.
      */
     private AadApplicationType applicationType;
 
@@ -201,7 +217,7 @@ public static class UserGroupProperties {
         private Set<String> allowedGroupIds = new HashSet<>();
 
         /**
-         * If "true", use "v1.0/me/transitiveMemberOf" to get members. Otherwise, use "v1.0/me/memberOf".
+         * Whether to use transitive way to get members. If "true", use "v1.0/me/transitiveMemberOf" to get members. Otherwise, use "v1.0/me/memberOf". The default value is `false`.
          */
         private boolean useTransitiveMembers = false;
 

sdk/spring/spring-cloud-azure-autoconfigure/src/main/java/com/azure/spring/cloud/autoconfigure/aad/properties/AadProfileProperties.java

@@ -18,7 +18,7 @@ public class AadProfileProperties {
      */
     private String tenantId; // tenantId can not set to "common" here, otherwise we can not know whether it's set by customer or it is the default value.
     /**
-     * Name of the Azure cloud to connect to. Supported types are: AZURE, AZURE_CHINA, AZURE_GERMANY, AZURE_US_GOVERNMENT, OTHER.
+     * Name of the Azure cloud to connect to. Supported types are: AZURE, AZURE_CHINA, AZURE_GERMANY, AZURE_US_GOVERNMENT, OTHER. The default value is `AZURE`.
      */
     private AzureProfileOptionsProvider.CloudType cloudType;
     /**

sdk/spring/spring-cloud-azure-autoconfigure/src/main/java/com/azure/spring/cloud/autoconfigure/aad/properties/AadResourceServerProperties.java

@@ -38,13 +38,12 @@ public class AadResourceServerProperties implements InitializingBean {
 
     /**
      *
-     * Configure which claim in access token be returned in AuthenticatedPrincipal#getName. Default value is "sub".
+     * Configure which claim in access token be returned in AuthenticatedPrincipal#getName. Example: If use the default value, and the access_token's "sub" scope value is "testValue", then AuthenticatedPrincipal#getName will return "testValue". The default value is `"sub"`.
      */
     private String principalClaimName;
 
     /**
-     * Configure which claim will be used to build GrantedAuthority, and prefix of the GrantedAuthority's string value.
-     * Default value is: "scp" -> "SCOPE_", "roles" -> "APPROLE_".
+     * Configure which claim will be used to build GrantedAuthority, and prefix of the GrantedAuthority's string value. Example: If use the default value, and the access_token's "scp" scope value is "testValue", then GrantedAuthority with "SCOPE_testValue" will be created. The default value is `"scp" -> "SCOPE_", "roles" -> "APPROLE_"`.
      */
     private Map<String, String> claimToAuthorityPrefixMap;
 

sdk/spring/spring-cloud-azure-autoconfigure/src/main/java/com/azure/spring/cloud/autoconfigure/aad/properties/AuthorizationClientProperties.java

@@ -9,7 +9,7 @@
 import java.util.List;
 
 /**
- * Properties for an oauth2 client.
+ * Properties for an OAuth2 client.
  */
 public class AuthorizationClientProperties {
 

sdk/spring/spring-cloud-azure-autoconfigure/src/main/java/com/azure/spring/cloud/autoconfigure/aadb2c/properties/AadB2cProperties.java

@@ -54,23 +54,30 @@ public class AadB2cProperties implements InitializingBean {
     private final AadB2cCredentialProperties credential = new AadB2cCredentialProperties();
 
     /**
-     * App ID URI which might be used in the "aud" claim of a token.
+     * App ID URI which might be used in the "aud" claim of a token. For instance, 'https://{hostname}/{applicationId}'.
+     * See Microsoft doc about APP ID URL for more details: https://learn.microsoft.com/azure/active-directory/develop/security-best-practices-for-app-registration#application-id-uri
      */
     private String appIdUri;
 
     /**
-     * Connection Timeout for the JWKSet Remote URL call.  Deprecated. If you want to configure this, please provide a RestOperations bean.
+     * Connection Timeout(duration) for the JWKSet Remote URL call. The default value is `500s`.
+     * @deprecated If you want to configure this, please provide a RestOperations bean.
      */
+    @Deprecated
     private Duration jwtConnectTimeout = Duration.ofMillis(RemoteJWKSet.DEFAULT_HTTP_CONNECT_TIMEOUT);
 
     /**
-     * Read Timeout for the JWKSet Remote URL call.  Deprecated. If you want to configure this, please provide a RestOperations bean.
+     * Read Timeout(duration) for the JWKSet Remote URL call. The default value is `500s`.
+     * @deprecated If you want to configure this, please provide a RestOperations bean.
      */
+    @Deprecated
     private Duration jwtReadTimeout = Duration.ofMillis(RemoteJWKSet.DEFAULT_HTTP_READ_TIMEOUT);
 
     /**
-     * Size limit in Bytes of the JWKSet Remote URL call.  Deprecated. If you want to configure this, please provide a RestOperations bean.
+     * Size limit in Bytes of the JWKSet Remote URL call. The default value is `50*1024`.
+     * @deprecated If you want to configure this, please provide a RestOperations bean.
      */
+    @Deprecated
     private int jwtSizeLimit = RemoteJWKSet.DEFAULT_HTTP_SIZE_LIMIT; /* bytes */
 
     /**
@@ -79,7 +86,8 @@ public class AadB2cProperties implements InitializingBean {
     private String logoutSuccessUrl = DEFAULT_LOGOUT_SUCCESS_URL;
 
     /**
-     * Additional parameters for authentication.
+     * Additional parameters above the standard parameters defined in the OAuth 2.0 Authorization Framework. Would be added to the Authorization URL for customizing the Authorization Request. For instance, 'prompt: login'.
+     * See Microsoft doc about more additional parameters information: https://learn.microsoft.com/azure/active-directory/develop/v2-oauth2-auth-code-flow#request-an-authorization-code
      */
     private final Map<String, Object> authenticateAdditionalParameters = new HashMap<>();
 
@@ -104,12 +112,18 @@ public class AadB2cProperties implements InitializingBean {
     private String loginFlow = DEFAULT_KEY_SIGN_UP_OR_SIGN_IN;
 
     /**
-     * User flows.
+     * Azure AD B2C User flows. Configure the user flow type and name mapping. For instance, 'sign-up-or-sign-in: B2C_signin_or_signup'.
+     * See Microsoft doc about User flows for more details: https://learn.microsoft.com/azure/active-directory-b2c/user-flow-overview#user-flows
      */
     private Map<String, String> userFlows = new HashMap<>();
 
     /**
-     * Specify client configuration.
+     * The OAuth2 authorization clients, contains the authorization grant type(only support client credentials) and scope.
+     * The clients will be converted to OAuth2 ClientRegistration, the other ClientRegistration information(such as client id, client secret) inherits from the OAuth2 login client(sign-in user flow).
+     * For instance, '
+     * authorization-clients.webapi.authorization-grant-type=client_credentials,
+     * authorization-clients.webapi.scopes[0]={WEB_API_APP_ID_URL}/.default
+     * '.
      */
     private final Map<String, AuthorizationClientProperties> authorizationClients = new HashMap<>();
 

sdk/spring/spring-cloud-azure-autoconfigure/src/main/java/com/azure/spring/cloud/autoconfigure/aadb2c/properties/AuthorizationClientProperties.java

@@ -8,7 +8,7 @@
 import java.util.List;
 
 /**
- * Properties for an oauth2 client.
+ * Properties for an OAuth2 client.
  */
 public class AuthorizationClientProperties {