Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

update readme for aad starter #18826

Merged
merged 11 commits into from
Jan 29, 2021
Merged

update readme for aad starter #18826

Changes from 4 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
51cf628
Move code and configuration files from example to key concepts
zhichengliu12581 Jan 27, 2021
d98a007
Replace the webapi code in the sample code with the webapp code
zhichengliu12581 Jan 27, 2021
7fd22d6
add Next steps for pipeline
zhichengliu12581 Jan 27, 2021
221a977
Modify the content display order
zhichengliu12581 Jan 27, 2021
83b6cf1
Modify the structure of the readme file
zhichengliu12581 Jan 28, 2021
65f7003
Merge branch 'update-readme-for-starter' of https://github.com/lzc-19…
zhichengliu12581 Jan 28, 2021
119e25d
merge master
zhichengliu12581 Jan 28, 2021
f53e4af
modify pictures and optimization doc
zhichengliu12581 Jan 28, 2021
11dd0ae
nothing changed, just modify case
zhichengliu12581 Jan 28, 2021
b0f22b7
rename files and format readme
zhichengliu12581 Jan 28, 2021
ef037b1
Merge branch 'master' into update-readme-for-starter
rujche Jan 29, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
154 changes: 74 additions & 80 deletions sdk/spring/azure-spring-boot-starter-active-directory/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -109,57 +109,9 @@ This starter provides following properties to be customized:
| **azure.activedirectory**.user-group.allowed-groups | Expected user groups that an authority will be granted to if found in the response from the MemeberOf Graph API Call. |

### Web application
Based on Azure AD as a Web application, it uses OAuth2 authorization code flow to authentication, and authorizes resources based on the groups or roles claim in the access token.
Based on Azure AD as a Web application, it uses OAuth2 authorization code flow to authentication, and authorizes resources based on the groups in the access token.
chenrujun marked this conversation as resolved.
Show resolved Hide resolved
This starter provides a convenient way to quickly access resource servers.
1. Resource servers should be registered as `ClientRegistration`.
2. In Controller, `@RegisteredOAuth2AuthorizedClient` can be used to get `OAuth2AuthorizedClient`.
`OAuth2AuthorizedClient` contains accessToken to access related client resource.

#### 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
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 of `openid, profile, offline_access, https://graph.microsoft.com/User.Read`.
* Return secured data.

#### 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 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
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
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)

* Access restricted resources related to Graph and Custom resources through resource server.
* Auto On-Behalf-Of to request an access token for other clients.
* Use each client's access token to request restricted resource.
* Return secured data.

## Examples
Refer to different samples for different authentication ways.

### [Web APP] Authenticate in web app
Please refer to [azure-spring-boot-sample-active-directory-webapp] for authenticate in web apps.

#### Configure application.yml:
```yaml
azure:
Expand All @@ -186,8 +138,12 @@ public class AADOAuth2LoginConfigSample extends AADWebSecurityConfigurerAdapter
}
```

### [Web APP] Configure scopes of multiple resources
By default, `azure-spring-boot-starter-active-directory` configures scopes of `openid`, `profile` and `https://graph.microsoft.com/user.read` to implement OpenID Connect protocol and access of membership information of logging in users.
#### 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 of `openid, profile, offline_access, https://graph.microsoft.com/User.Read`.
* Return secured data.
chenrujun marked this conversation as resolved.
Show resolved Hide resolved

To customize scope configurations of multiple resources, developers need to configure the registration id and scopes in the `application.yml` as needed. Here the {registration-id} is defined by developers themselves to generate correspondding `OAuth2AuthorizedClient` to acquire access tokens, and scope names should follow the specification of `resource-uri/permission`.
```yaml
Expand All @@ -200,7 +156,37 @@ azure:
scopes: {scope1}, {scope2}
```

### [Web APP] Configure on-demand resource authorization
#### 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 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.

1. Resource servers should be registered as `ClientRegistration`.
chenrujun marked this conversation as resolved.
Show resolved Hide resolved
2. In Controller, `@RegisteredOAuth2AuthorizedClient` can be used to get `OAuth2AuthorizedClient`.
`OAuth2AuthorizedClient` contains accessToken to access related client resource.

Support the use of `@RegisteredOAuth2AuthorizedClient` to get `OAuth2AuthorizedClient`:
chenrujun marked this conversation as resolved.
Show resolved Hide resolved
```java
@PreAuthorize("hasAuthority('SCOPE_Obo.Graph.Read')")
@GetMapping("call-graph")
public String callGraph(@RegisteredOAuth2AuthorizedClient("graph") OAuth2AuthorizedClient graph) {
return callMicrosoftGraphMeEndpoint(graph);
}

@PreAuthorize("hasAuthority('SCOPE_Obo.File.Read')")
@GetMapping("call-custom")
public String callCustom(
@RegisteredOAuth2AuthorizedClient("custom") OAuth2AuthorizedClient custom) {
return callCustomLocalFileEndpoint(custom);
}
```

#### 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.
To configure the authorization of certain resource as on-demand, developers need to add following property in `application.yml`:
```yaml
azure:
Expand All @@ -211,8 +197,8 @@ azure:
scopes: {scope1}, {scope2}
```

### [Web API] Protect the resource APIs in resource server
Please refer to [azure-spring-boot-sample-active-directory-resource-server] for access resource APIs.
### 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.

#### Using `AADOAuth2ResourceServerSecurityConfig` to extends `WebSecurityConfigurerAdapter`:
```java
Expand All @@ -230,9 +216,6 @@ public class AADOAuth2ResourceServerSecurityConfig extends WebSecurityConfigurer
}
```

### [Web API] OAuth 2.0 On-Behalf-Of flow
Please refer [azure-spring-boot-sample-active-directory-resource-server-obo] to for access On-Behalf-Of flow.

#### Configure application.yml:
```yaml
azure:
Expand All @@ -250,22 +233,24 @@ azure:
- <Web-API-B-app-id-url>/File.Read
```

#### Support the use of `@RegisteredOAuth2AuthorizedClient` to get `OAuth2AuthorizedClient`:
```java
@PreAuthorize("hasAuthority('SCOPE_Obo.Graph.Read')")
@GetMapping("call-graph")
public String callGraph(@RegisteredOAuth2AuthorizedClient("graph") OAuth2AuthorizedClient graph) {
return callMicrosoftGraphMeEndpoint(graph);
}

@PreAuthorize("hasAuthority('SCOPE_Obo.File.Read')")
@GetMapping("call-custom")
public String callCustom(@RegisteredOAuth2AuthorizedClient("custom") OAuth2AuthorizedClient custom) {
return callCustomEndpoint(custom);
}
```
#### 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)

### [Web API] (Deprecated) Authenticate in web API by a filter
* Access restricted resources of Resource Server.
* Validate access token.
* Return secured data.

#### 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)

* Access restricted resources related to Graph and Custom resources through resource server.
* Auto On-Behalf-Of to request an access token for other clients.
* Use each client's access token to request restricted resource.
* Return secured data.

### (Deprecated) Authenticate in web API by a filter
chenrujun marked this conversation as resolved.
Show resolved Hide resolved
Please refer to [azure-spring-boot-sample-active-directory-resource-server-by-filter] for how to integrate Spring Security and Azure AD for authentication and authorization in a Single Page Application (SPA) scenario.

#### Configure application.yml:
Expand All @@ -292,7 +277,7 @@ public class AADAuthenticationFilterConfigSample extends WebSecurityConfigurerAd
* Role-based Authorization with annotation `@PreAuthorize("hasRole('GROUP_NAME')")`
* Role-based Authorization with method `isMemberOf()`

### [Web API] (Deprecated) Authenticate stateless web API by a filter, using AAD app roles
### (Deprecated) Authenticate stateless web API by a filter, using AAD app roles
This scenario fits best for stateless Spring backends exposing an API to SPAs ([OAuth 2.0 implicit grant flow]) or service-to-service access using the [client credentials grant flow].
The stateless processing can be activated with the `azure.activedirectory.session-stateless` property. The authorization is using the [AAD App Roles feature], so instead of using the `groups` claim the token has a `roles` claim which contains roles [configured in your manifest].

Expand Down Expand Up @@ -346,7 +331,7 @@ public class AADAppRoleStatelessAuthenticationFilterConfigSample extends WebSecu

The roles you want to use within your application have to be [set up in the manifest of your application registration].

### [Web APP & Web API] Use Azure China instead of Azure Global
### Use Azure China instead of Azure Global
If you use [Azure China] instead of **Azure Global**, you need to configure your `application.yml`:
```yaml
azure:
Expand All @@ -355,6 +340,21 @@ azure:
graph-membership-uri: https://microsoftgraph.chinacloudapi.cn/v1.0/me/memberOf
```

## Examples
Refer to different samples for different authentication ways.
chenrujun marked this conversation as resolved.
Show resolved Hide resolved

### [Web APP] Authenticate in web app
Please refer to [azure-spring-boot-sample-active-directory-webapp] for authenticate in web apps.

### [Web API] Protect the resource APIs in resource server
Please refer to [azure-spring-boot-sample-active-directory-resource-server] for access resource APIs.

### [Web API] OAuth 2.0 On-Behalf-Of flow
Please refer to [azure-spring-boot-sample-active-directory-resource-server-obo] for access On-Behalf-Of flow.

### [Web API] (Deprecated) Authenticate in web API by a filter
chenrujun marked this conversation as resolved.
Show resolved Hide resolved
Please refer to [azure-spring-boot-sample-active-directory-resource-server-by-filter] for how to integrate Spring Security and Azure AD for authentication and authorization in a Single Page Application (SPA) scenario.

## Troubleshooting
### Enable client logging
Azure SDKs for Java offers a consistent logging story to help aid in troubleshooting application errors and expedite their resolution. The logs produced will capture the flow of an application before reaching the terminal state to help locate the root issue. View the [logging][logging] wiki for guidance about enabling logging.
Expand All @@ -373,12 +373,6 @@ logging.level.org.hibernate=ERROR
For more information about setting logging in spring, please refer to the [official doc].

## Next steps
The following section provides sample projects illustrating how to use the starter in different cases.
### More sample code
- [Azure Active Directory for Web apps][azure-spring-boot-sample-active-directory-webapp]
- [Azure Active Directory for Web APIs][azure-spring-boot-sample-active-directory-resource-server]
- [Azure Active Directory for On-Behalf-Of flow][azure-spring-boot-sample-active-directory-resource-server-obo]
- [Azure Active Directory for Resource Server by Filter(Deprecated)][azure-spring-boot-sample-active-directory-resource-server-by-filter]

## Contributing
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.
Expand Down