Azure · yiliuTo · Dec 28, 2020 · Dec 25, 2020 · Dec 28, 2020 · Dec 28, 2020
diff --git a/sdk/spring/azure-spring-boot-starter-active-directory/CHANGELOG.md b/sdk/spring/azure-spring-boot-starter-active-directory/CHANGELOG.md
@@ -5,16 +5,39 @@
 - Change group id from `com.microsoft.azure` to `com.azure.spring`.
 - Change artifact id from `azure-active-directory-spring-boot-starter` to `azure-spring-boot-starter-active-directory`.
 - Deprecate `AADAppRoleStatelessAuthenticationFilter` and `AADAuthenticationFilter`.
+- Deprecate following `azure-spring-boot-starter-active-directory` configuration properties:
+    ```
+    spring.security.oauth2.client.provider.azure.*
+    spring.security.oauth2.client.registration.azure.*
+    azure.activedirectory.environment
+    azure.activedirectory.user-group.key
+    azure.activedirectory.user-group.value
+    azure.activedirectory.user-group.object-id-key
+    ```
+- Stop support of Azure Active Directory Endpoints.
 
 ### New Features
-- Support consent multiple client-registration when login.
-- Support on-demand client-registration.
-- Support the use of `@RegisteredOAuth2AuthorizedClient` to get `OAuth2AuthorizedClient`.
-- Support to obtain the claim in access token, such as `scp`, `roles` etc, to carry out permission control.
-- Support on-behalf-of flow when the `azure-spring-boot-starter-active-directory` used in resource-server.
-- Provide some AAD specific token validation, such as audience validation, issuer validation.
-- Expose a flag in the `AzureOAuth2AuthenticatedPrincipal` to tell which account type is being used, work account or personal account.
-
+- Support consent of multiple client registrations during user login.
+- Support on-demand client registrations.
+- Support the use of `@RegisteredOAuth2AuthorizedClient` annotation to get `OAuth2AuthorizedClient`.
+- Support access control through users' membership information.
+- Support on-behalf-of flow in the resource server.
+- Provide AAD specific token validation of audience validation and issuer validation.
+- Expose a flag `isPersonalAccount` in `AzureOAuth2AuthenticatedPrincipal` to specify the account type in use: work account or personal account.
+- Enable loading transitive membership information from Microsoft Graph API.
+- Enable following `azure-spring-boot-starter-active-directory` configuration properties:
+    ```yaml
+    # Redirect URI of authorization server
+    azure.activedirectory.redirect-uri-template
+    # Refresh time of the cached JWK set before it expires, default value is 5 minutes.
+    azure.activedirectory.jwk-set-cache-refresh-time
+    # Logout redirect URI
+    azure.activedirectory.post-logout-redirect-uri
+    # Authorization URI, default value is "https://login.microsoftonline.com/"
+    azure.activedirectory.authorization-server-uri
+    # Membership URI of Microsoft Graph API to get users' group information, default value is "https://graph.microsoft.com/v1.0/me/memberOf"
+    azure.activedirectory.graph-membership-uri
+    ```
 ## 2.3.5 (2020-09-14)
 ### Key Bug Fixes
 - Get full list of groups the user belongs to from Graph API

diff --git a/sdk/spring/azure-spring-boot-starter-active-directory/README.md b/sdk/spring/azure-spring-boot-starter-active-directory/README.md
@@ -16,27 +16,38 @@ With Spring Starter for Azure Active Directory, now you can get started quickly
 * **Create a client secret key for the application**: Go to API ACCESS - Keys to create a secret key (`client-secret`).
 
 ### Include the package
+To use this starter in an web application, please add following packages:
+
 [//]: # "{x-version-update-start;com.azure.spring:azure-spring-boot-starter-active-directory;current}"
 ```xml
 <dependency>
     <groupId>com.azure.spring</groupId>
     <artifactId>azure-spring-boot-starter-active-directory</artifactId>
     <version>3.0.0-beta.1</version>
 </dependency>
+<dependency>
+  <groupId>org.springframework.security</groupId>
+  <artifactId>spring-security-oauth2-client</artifactId>
+</dependency>
 ```
 [//]: # "{x-version-update-end}"
 
 ## Key concepts
-This package provides 2 ways to integrate with Spring Security and authenticate with Azure Active Directory.
+This package provides 2 ways to integrate with Spring Security and authenticate with Azure Active Directory, which are designed for scenarios of web application and resource server.
+
+The authorization flow for web application includes:
+* Login with credentials by self-defined `azure` client registration and trigger **authorization code flow**. Application gets user's consent for all configured scopes except on-demand resources' scopes, and acquires an access token only for scopes of `openid, profile, offline_access, https://graph.microsoft.com/User.Read`.
+* When other resources are visited, associated clients will be loaded to trigger **refresh token flow** for authorization, and acquire an access token for configured scopes of that resource.
+* When on-demand resources are visited, associated clients will be loaded and trigger **authorization code flow** like the `azure` client.
 
-The authorization flow is composed of 3 phrases:
+The authorization flow for resource server:
 * Login with credentials and validate id_token from Azure AD 
 * Get On-Behalf-Of token and membership info from Azure AD Graph API
 * Evaluate the permission based on membership info to grant or deny access
 
 ### Group membership
-The way to get group relationship depends on the graph api used, the default to get membership is the direct group of the user. 
-To get all transitive relationships, the following configuration is required:
+The way this starter uses to load users' membership depends on the configured membership URI. By default, the starter uses `https://graph.microsoft.com/v1.0/me/memberOf` to get direct membership of current user. 
+To get all transitive membership, the following configuration is required:
 
 ```yaml
 azure:
@@ -54,34 +65,34 @@ This starter provides a convenient way to quickly access resource servers.
 #### On-demand authorization
 By default, the starter will launch the Oauth2 Authorization Code flow for a logging in user. During the authorization flow, `azure-spring-boot-starter-active-directory` adds all the configured scopes except **on-demand** ones into authorization code requests to ask for user's authorization consent. The authorization flow of `on-demand` resources will be launched at the first time the user wants to access them.
 
-#### Standalone web application usage
+#### Standalone web application
 Only as a Web application, no further access to other resources protected by Azure AD.
 ![Standalone Web Application](resource/aad-based-standalone-web-application.png)
 
-* Access restricted resources of web application, login with credentials using default scopes.
+* Access restricted resources of web application, login with credentials using default scopes of `openid, profile, offline_access, https://graph.microsoft.com/User.Read`.
 * Return secured data.
 
-#### Web application access resources usage
-Web application and resource server use scenarios, web application access the resources of resource server which is protected by Azure AD.
+#### Web application visit other resource servers
+Web application visits resource servers which are protected by Azure AD.
 ![Web Application Access Resources](resource/add-based-web-application-access-resources.png)
 
-* Login with credentials, the scope includes all other clients. 
+* Login with credentials, the scope includes default scopes and all configured scopes. 
 * Auto-acquire the access token of other clients based on the root refresh token.
 * Use each client's access token to request restricted resource.
 * Return secured data.
 
 ### Resource Server
 Based on Azure AD as a Resource Server, it uses `BearerTokenAuthenticationFilter` authorize request. The current resource server also can access other resources, there's a similar method to the web application usage to obtain access to the client access token, the difference is the access token obtained based on the `MSAL On-Behalf-Of` process.
 
-#### Standalone resource server usage
+#### Standalone resource server
 Only as a Resource Server, no further access to other resources protected by Azure AD.
 ![Standalone resource server usage](resource/add-based-standalone-resource-server.png)
 
 * Access restricted resources of Resource Server.
 * Validate access token.
 * Return secured data.
 
-#### Resource server access other resources usage
+#### Resource server access other resources
 Resource server accesses other resource servers which are protected by Azure AD.
 ![Resource Server Access Other Resources](resource/add-based-resource-server-access-other-resources.png)
 

diff --git a/sdk/spring/azure-spring-boot-starter/CHANGELOG.md b/sdk/spring/azure-spring-boot-starter/CHANGELOG.md
@@ -1,7 +1,42 @@
 # Release History
 
 ## 3.0.0-beta.2 (Unreleased)
+### Breaking Changes
+- Deprecate `AADAppRoleStatelessAuthenticationFilter` and `AADAuthenticationFilter`.
+- Change artifact id from `azure-active-directory-spring-boot-starter` to `azure-spring-boot-starter-active-directory`.
+- Deprecate following `azure-spring-boot-starter-active-directory` configuration properties:
+    ```
+    spring.security.oauth2.client.provider.azure.*
+    spring.security.oauth2.client.registration.azure.*
+    azure.activedirectory.environment
+    azure.activedirectory.user-group.key
+    azure.activedirectory.user-group.value
+    azure.activedirectory.user-group.object-id-key
+    ```
+- Stop support of Azure Active Directory Endpoints.
 
+### New Features
+- Support consent of multiple client registrations during user login.
+- Support on-demand client registrations.
+- Support the use of `@RegisteredOAuth2AuthorizedClient` annotation to get `OAuth2AuthorizedClient`.
+- Support access control through users' membership information.
+- Support on-behalf-of flow in the resource server.
+- Provide AAD specific token validation methods of audience validation and issuer validation.
+- Expose a flag `isPersonalAccount` in `AzureOAuth2AuthenticatedPrincipal` to specify the account type in use: work account or personal account.
+- Enable loading transitive membership information from Microsoft Graph API.
+- Enable following `azure-spring-boot-starter-active-directory` configuration properties:
+    ```yaml
+    # Redirect URI of authorization server
+    azure.activedirectory.redirect-uri-template
+    # Refresh time of the cached JWK set before it expires, default value is 5 minutes.
+    azure.activedirectory.jwk-set-cache-refresh-time
+    # Logout redirect URI
+    azure.activedirectory.post-logout-redirect-uri
+    # Authorization URI, default value is "https://login.microsoftonline.com/"
+    azure.activedirectory.authorization-server-uri
+    # Membership URI of Microsoft Graph API to get users' group information, default value is "https://graph.microsoft.com/v1.0/me/memberOf"
+    azure.activedirectory.graph-membership-uri
+    ```
 
 ## 3.0.0-beta.1 (2020-11-18)
 ### Breaking Changes

diff --git a/sdk/spring/azure-spring-boot/CHANGELOG.md b/sdk/spring/azure-spring-boot/CHANGELOG.md
@@ -3,17 +3,40 @@
 ## 3.0.0-beta.2 (Unreleased)
 ### Breaking Changes
 - Deprecate `AADAppRoleStatelessAuthenticationFilter` and `AADAuthenticationFilter`.
-- Support the setting of post logout redirect uri 
+- Change artifact id from `azure-active-directory-spring-boot-starter` to `azure-spring-boot-starter-active-directory`.
+- Deprecate following `azure-spring-boot-starter-active-directory` configuration properties:
+    ```
+    spring.security.oauth2.client.provider.azure.*
+    spring.security.oauth2.client.registration.azure.*
+    azure.activedirectory.environment
+    azure.activedirectory.user-group.key
+    azure.activedirectory.user-group.value
+    azure.activedirectory.user-group.object-id-key
+    ```
+- Stop support of Azure Active Directory Endpoints.
 
 ### New Features
-- Support consent multiple client-registration when login.
-- Support on-demand client-registration.
-- Support the use of `@RegisteredOAuth2AuthorizedClient` to get `OAuth2AuthorizedClient`.
-- Support to obtain the claim in access token, such as `scp`, `roles` etc, to carry out permission control.
-- Support on-behalf-of flow when the `azure-spring-boot-starter-active-directory` used in resource-server.
-- Provide some AAD specific token validation, such as audience validation, issuer validation.
-- Expose a flag in the `AzureOAuth2AuthenticatedPrincipal` to tell which account type is being used, work account or personal account.
-
+- Support consent of multiple client registrations during user login.
+- Support on-demand client registrations.
+- Support the use of `@RegisteredOAuth2AuthorizedClient` annotation to get `OAuth2AuthorizedClient`.
+- Support access control through users' membership information.
+- Support on-behalf-of flow in the resource server.
+- Provide AAD specific token validation methods of audience validation and issuer validation.
+- Expose a flag `isPersonalAccount` in `AzureOAuth2AuthenticatedPrincipal` to specify the account type in use: work account or personal account.
+- Enable loading transitive membership information from Microsoft Graph API.
+- Enable following `azure-spring-boot-starter-active-directory` configuration properties:
+    ```yaml
+    # Redirect URI of authorization server
+    azure.activedirectory.redirect-uri-template
+    # Refresh time of the cached JWK set before it expires, default value is 5 minutes.
+    azure.activedirectory.jwk-set-cache-refresh-time
+    # Logout redirect URI
+    azure.activedirectory.post-logout-redirect-uri
+    # Authorization URI, default value is "https://login.microsoftonline.com/"
+    azure.activedirectory.authorization-server-uri
+    # Membership URI of Microsoft Graph API to get users' group information, default value is "https://graph.microsoft.com/v1.0/me/memberOf"
+    azure.activedirectory.graph-membership-uri
+    ```
 ## 3.0.0-beta.1 (2020-11-18)
 ### Breaking Changes
 - Update `com.azure` group id to `com.azure.spring`.