Clarify AAD properties for Spring Cloud Azure

.vscode/cspell.json

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

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 information inherits from the delegated OAuth2 login client 'azure'.
+     * For instance, 'webapi:
+     *                   authorization-grant-type: on_behalf_of
+     *                   client-authentication-method: client_secret_post
+     *                   scopes:
+     *                      - ${WEB_API_APP_ID_URL}/WebApi.ExampleScope1
+     *                      - ${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". 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,17 @@ public class AadB2cProperties implements InitializingBean {
     private String loginFlow = DEFAULT_KEY_SIGN_UP_OR_SIGN_IN;
 
     /**
-     * User flows.
+     * User flows. For instance, 'sign-up-or-sign-in: B2C_signin_or_signup'.
      */
     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 information inherits from the OAuth2 login client(sign-in user flow).
+     * For instance, 'webapi:
+     *                   authorization-grant-type: client_credentials
+     *                   scopes:
+     *                       - ${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 {
 

sdk/spring/spring-cloud-azure-autoconfigure/src/main/resources/META-INF/additional-spring-configuration-metadata.json

@@ -43,7 +43,7 @@
     {
       "name": "azure.activedirectory.authenticate-additional-parameters",
       "type": "java.util.Map<java.lang.String,java.lang.Object>",
-      "description": "Add additional parameters to the Authorization URL.",
+      "description": "Add additional parameters to the Authorization URL. For instance, 'prompt: login'.",
       "deprecation": {
         "level": "error",
         "reason": "Use uniform property format(spring.cloud.azure.*) in all Spring Cloud Azure libraries.",
@@ -89,7 +89,7 @@
     },
     {
       "name": "azure.activedirectory.b2c.authorization-clients",
-      "description": "Specify client configuration.",
+      "description": "Specify client configuration. For instance, 'authorizationGrantType: client_credentials'.",
       "deprecation": {
         "level": "error",
         "reason": "Use uniform property format(spring.cloud.azure.*) in all Spring Cloud Azure libraries.",
@@ -129,7 +129,7 @@
     {
       "name": "azure.activedirectory.b2c.jwt-connect-timeout",
       "type": "java.lang.Integer",
-      "description": "Connection Timeout for the JWKSet Remote URL call.",
+      "description": "Connection Timeout(duration) for the JWKSet Remote URL call. The default value is `500s`.",
       "deprecation": {
         "level": "error",
         "reason": "Not used anymore, for any customization, provide a custom RestOperation bean."
@@ -138,7 +138,7 @@
     {
       "name": "azure.activedirectory.b2c.jwt-read-timeout",
       "type": "java.lang.Integer",
-      "description": "Read Timeout for the JWKSet Remote URL call.",
+      "description": "Read Timeout(duration) for the JWKSet Remote URL call. The default value is `500s`.",
       "deprecation": {
         "level": "error",
         "reason": "Not used anymore, for any customization, provide a custom RestOperation bean."
@@ -147,7 +147,7 @@
     {
       "name": "azure.activedirectory.b2c.jwt-size-limit",
       "type": "java.lang.Integer",
-      "description": "Size limit in Bytes of the JWKSet Remote URL call.",
+      "description": "Size limit in Bytes of the JWKSet Remote URL call. The default value is `50*1024`.",
       "deprecation": {
         "level": "error",
         "reason": "Not used anymore, for any customization, provide a custom RestOperation bean."
@@ -156,7 +156,7 @@
     {
       "name": "spring.cloud.azure.active-directory.b2c.jwt-connect-timeout",
       "type": "java.lang.Integer",
-      "description": "Connection Timeout for the JWKSet Remote URL call.",
+      "description": "Connection Timeout(duration) for the JWKSet Remote URL call. The default value is `500s`.",
       "deprecation": {
         "level": "error",
         "reason": "Not used anymore, for any customization, provide a custom RestOperation bean."
@@ -165,7 +165,7 @@
     {
       "name": "spring.cloud.azure.active-directory.b2c.jwt-read-timeout",
       "type": "java.lang.Integer",
-      "description": "Read Timeout for the JWKSet Remote URL call.",
+      "description": "Read Timeout(duration) for the JWKSet Remote URL call. The default value is `500s`.",
       "deprecation": {
         "level": "error",
         "reason": "Not used anymore, for any customization, provide a custom RestOperation bean."
@@ -174,7 +174,7 @@
     {
       "name": "spring.cloud.azure.active-directory.b2c.jwt-size-limit",
       "type": "java.lang.Integer",
-      "description": "Size limit in Bytes of the JWKSet Remote URL call.",
+      "description": "Size limit in Bytes of the JWKSet Remote URL call. The default value is `50*1024`.",
       "deprecation": {
         "level": "error",
         "reason": "Not used anymore, for any customization, provide a custom RestOperation bean."
@@ -300,7 +300,7 @@
     {
       "name": "azure.activedirectory.jwk-set-cache-lifespan",
       "type": "java.lang.Long",
-      "description": "The lifespan of the cached JWK set before it expires, default is 5 minutes.",
+      "description": "The lifespan(duration) of the cached JWK set before it expires.",
       "defaultValue": 5,
       "deprecation": {
         "level": "error",
@@ -311,7 +311,7 @@
     {
       "name": "azure.activedirectory.jwk-set-cache-refresh-time",
       "type": "java.lang.Long",
-      "description": "The refresh time of the cached JWK set before it expires, default is 5 minutes.",
+      "description": "The refresh time(duration) of the cached JWK set before it expires.",
       "defaultValue": 5,
       "deprecation": {
         "level": "error",
@@ -322,7 +322,7 @@
     {
       "name": "azure.activedirectory.jwt-connect-timeout",
       "type": "java.lang.Integer",
-      "description": "Connection Timeout for the JWKSet Remote URL call.",
+      "description": "Connection Timeout(duration) for the JWKSet Remote URL call. The default value is `500s`.",
       "deprecation": {
         "level": "error",
         "reason": "Not used anymore, for any customization, provide a custom RestOperation bean."
@@ -331,7 +331,7 @@
     {
       "name": "azure.activedirectory.jwt-read-timeout",
       "type": "java.lang.Integer",
-      "description": "Read Timeout for the JWKSet Remote URL call.",
+      "description": "Read Timeout(duration) for the JWKSet Remote URL call. The default value is `500s`.",
       "deprecation": {
         "level": "error",
         "reason": "Not used anymore, for any customization, provide a custom RestOperation bean."
@@ -340,7 +340,7 @@
     {
       "name": "azure.activedirectory.jwt-size-limit",
       "type": "java.lang.Integer",
-      "description": "Size limit in Bytes of the JWKSet Remote URL call.",
+      "description": "Size limit in Bytes of the JWKSet Remote URL call. The default value is `51200`.",
       "deprecation": {
         "level": "error",
         "reason": "Not used anymore, for any customization, provide a custom RestOperation bean."
@@ -349,7 +349,7 @@
     {
       "name": "spring.cloud.azure.active-directory.jwt-connect-timeout",
       "type": "java.lang.Integer",
-      "description": "Connection Timeout for the JWKSet Remote URL call.",
+      "description": "Connection Timeout(duration) for the JWKSet Remote URL call. The default value is `500s`.",
       "deprecation": {
         "level": "error",
         "reason": "Not used anymore, for any customization, provide a custom RestOperation bean."
@@ -358,7 +358,7 @@
     {
       "name": "spring.cloud.azure.active-directory.jwt-read-timeout",
       "type": "java.lang.Integer",
-      "description": "Read Timeout for the JWKSet Remote URL call.",
+      "description": "Read Timeout(duration) for the JWKSet Remote URL call. The default value is `500s`.",
       "deprecation": {
         "level": "error",
         "reason": "Not used anymore, for any customization, provide a custom RestOperation bean."
@@ -367,7 +367,7 @@
     {
       "name": "spring.cloud.azure.active-directory.jwt-size-limit",
       "type": "java.lang.Integer",
-      "description": "Size limit in Bytes of the JWKSet Remote URL call.",
+      "description": "Size limit in Bytes of the JWKSet Remote URL call. The default value is `51200`.",
       "deprecation": {
         "level": "error",
         "reason": "Not used anymore, for any customization, provide a custom RestOperation bean."
@@ -395,7 +395,7 @@
     {
       "name": "azure.activedirectory.resource-server.claim-to-authority-prefix-map",
       "type": "java.util.Map<java.lang.String,java.lang.String>",
-      "description": "Configure which claim will be used to build GrantedAuthority, and prefix of the GrantedAuthority's string value. Default value is: \"scp\" -> \"SCOPE_\", \"roles\" -> \"APPROLE_\". Example: If use the default value, and the access_token's \"scp\" scope value is \"testValue\", then GrantedAuthority with \"SCOPE_testValue\" will be created.",
+      "description": "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_\"`.",
       "deprecation": {
         "level": "error",
         "reason": "Use uniform property format(spring.cloud.azure.*) in all Spring Cloud Azure libraries.",
@@ -405,7 +405,7 @@
     {
       "name": "azure.activedirectory.resource-server.principal-claim-name",
       "type": "java.lang.String",
-      "description": "Configure which claim in access token be returned in AuthenticatedPrincipal#getName. Default value is \"sub\". Example: If use the default value, and the access_token's \"sub\" scope value is \"testValue\", then AuthenticatedPrincipal#getName will return \"testValue\".",
+      "description": "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\"`.",
       "deprecation": {
         "level": "error",
         "reason": "Use uniform property format(spring.cloud.azure.*) in all Spring Cloud Azure libraries.",