Skip to content

Commit

Permalink
Single spring-addons starter
Browse files Browse the repository at this point in the history
  • Loading branch information
ch4mpy committed Jul 9, 2023
1 parent ee40e16 commit 2582fd5
Show file tree
Hide file tree
Showing 327 changed files with 3,450 additions and 6,372 deletions.
47 changes: 47 additions & 0 deletions 7.0.0-migration-guide.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
# Migration Guide from 6.x to 7.0.0

## Dependencies
- replace any spring-addons starter with `com.c4-soft.springaddons:spring-addons-starter-oidc`
- replace any spring-addons test starter with `com.c4-soft.springaddons:spring-addons-starter-oidc-test`
- depending or your needs, add a dependency to
* `org.springframework.boot:spring-boot-starter-oauth2-resource-server` for a REST API secured with access tokens
* `org.springframework.boot:spring-boot-starter-oauth2-client` when configuring `spring-cloud-gateway` as BFF or exposing server-side rendered templates with frameworks like Thymeleaf
* both of above when exposing publicly both a REST API secured with access tokens and other resources secured with sessions

## Java Sources

### Main Code
- rename `SpringAddonsSecurityProperties` to `SpringAddonsOidcProperties`. Also, if using nested properties, rename
* `getIssuers()` to `getOps()`
* `getLocation()` to `getIss()`
- replace `SpringAddonsOAuth2ClientProperties` with `SpringAddonsOidcProperties::getClient` (only `SpringAddonsOidcProperties` can be autowired)
- organize imports

### Tests
- replace `@AutoConfigureAddonsSecurity` with `@AutoConfigureAddonsMinimalSecurity`
- replace `@AutoConfigureAddonsWebSecurity` with one of:
* `@AutoConfigureAddonsWebmvcSecurity`
* `@AutoConfigureAddonsWefluxSecurity`

## Application Properties
This is probably the most tedious part of the migration. Hopefully, your IDE auto-completion and syntax highliting should help you there.

### Common Configuration
- rename `com.c4-soft.springaddons.security` to `com.c4-soft.springaddons.oidc`
- rename `issuers` to `ops` which stands for OpenID Providers (`com.c4-soft.springaddons.security.issuers` becomes `com.c4-soft.springaddons.oidc.ops`)
- rename OpenID Providers `location` to `iss`: if set, the is used to add an "issuer" (tokens `iss` claim) validator to JWT decoder (`com.c4-soft.springaddons.security.issuers[].location` becomes `com.c4-soft.springaddons.oidc.ops[].iss`)
- rename`audience` to `aud`: if set, the is used to add an "audience" (tokens `aud` claim) validator to JWT decoder (`com.c4-soft.springaddons.security.issuers[].aud` becomes `com.c4-soft.springaddons.oidc.ops[].aud`)

CORS configuration has also improved for both clients and resource servers: `allowed-origin-patterns` is used instead of `allowed-origins`. This is a requirement for using `allow-credentials` and is also more flexible: you can define ant patterns like `https://*.my-domain.pf`.
- rename `allowed-origins` to `allowed-origin-patterns`
- add `allow-credentials` and `max-age` if it makes sens (this are added configuration options)

### Resource Servers
Resource server `Security(Web)FilterChain` can now be completely disabled with `com.c4-soft.springaddons.security.resourceserver.enabled=false`

Resource server specific properties are grouped in a new `resourceserver` subset:
- move `cors` down 1 level into `resourceserver` (`com.c4-soft.springaddons.security.cors` becomes `com.c4-soft.springaddons.security.resourceserver.cors`)
- move `permit-all` down one level to `resourceserver` (`com.c4-soft.springaddons.security.permit-all` becomes `com.c4-soft.springaddons.security.resourceserver.permit-all`)

### Clients
- rename `allowed-origins` to `allowed-origin-patterns` (`com.c4-soft.springaddons.security.client.cors.allowed-origins` becomes `com.c4-soft.springaddons.security.client.cors.allowed-origin-patterns`)
42 changes: 23 additions & 19 deletions README.MD
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
Do not hesitate to fork this repo and send pull requests, even for things as small as a typo in READMEs or Javadoc. This would promote you as contributor.
7.0.0 is a break through in usability: all 6 `spring-addons` Boot starters are merged into a single one: [`com.c4-soft.springaddons:spring-addons-starter-oidc`](https://repo1.maven.org/maven2/com/c4-soft/springaddons/spring-addons-starter-oidc/), and so are the 4 test libs: [`com.c4-soft.springaddons:spring-addons-starter-oidc-test`](https://repo1.maven.org/maven2/com/c4-soft/springaddons/spring-addons-starter-oidc-test/) (if you are using just the test annotations, without the starter, the dependency is still the same: [`com.c4-soft.springaddons:spring-addons-oauth2-test`](https://repo1.maven.org/maven2/com/c4-soft/springaddons/spring-addons-oauth2-test/)).

# Spring-addons
Please follow the [migration guide](https://github.com/ch4mpy/spring-addons/blob/master/7.0.0-migration-guide.md) to bump from `6.x` to `7.0.0`. Also, all samples and tutorials are migrated to latest starter and test annotations.

# Configuring and Testing OAuth2 / OpenID Spring applications Made Easy
The libraries hosted in this repo shine in two domains:
- provide with annotations to mock OAuth2 `Authentication` during tests (`@WithMockJwtAuth`, `@WithOAuth2Login`, `@WithOidcLogin`, `@WithMockBearerTokenAuthentication`, etc.), which allow to test method security on any `@Component`. **New in 6.1.12: `@JwtAuthenticationSource` and alike to work with JUnit 5 `@ParameterizedTest`**. Details below.
- provide with annotations to mock OAuth2 `Authentication` during tests (`@WithMockAuthentication`, `@WithJwt`, `@WithMockOpaqueToken`, `@WithOidcLogin`, etc.), which allow to test method security on any `@Component`. **New in 6.1.12: `@AuthenticationSource` and alike to work with JUnit 5 `@ParameterizedTest`**. Details below.
- help configuring Spring Boot 3 applications OAuth2 configuration by pushing auto-configuration to the next level. As shown in **[Tutorials](https://github.com/ch4mpy/spring-addons/tree/master/samples/tutorials)**, with 0 Java conf (just properties), we can configure:
* authorities mapping (source claims, prefix and case transformation), without having to provide authentication converter, user service or `GrantedAuthoritiesMapper` in each app
* fine grained CORS configuration (per path matcher), which enables to override allowed origins as environment variable when switching from `localhost` to `dev` or `prod` environments
Expand All @@ -16,7 +18,7 @@ The libraries hosted in this repo shine in two domains:

Jump to:
- [1. Unit & Integration Testing With Security](#unit-tests)
- [2. Spring Boot OAuth2 Starters](#oauth2-starters)
- [2. Spring Boot OIDC Starter](#oauth2-starters)
- [3. Where to Start](#start)
- [4. Versions & Requirements](#versions)
- [5. Additional Modules](#additional-modules)
Expand Down Expand Up @@ -92,16 +94,14 @@ There are we few things worth noting above:
- we are using JUnit 5 `@ParameterizedTest`: the test will run once for each of the authentication in the stream provided by the `identities` method
- the claim used as `username` is a potentially a nested claim resolved with JSON-Path
## 2. <a name="oauth2-starters"/>Spring Boot Starters
**This starters are designed to push auto-configuration to the next level** (and does nothing more than helping you with auto-configuration from applicationproperties). In most cases, you should need 0 Java conf. An effort was made to make [tutorials](https://github.com/ch4mpy/spring-addons/tree/master/samples/tutorials), Javadoc and modules READMEs as informative as possible. Please refer there for more details.
## 2. <a name="oauth2-starters"/>Spring Boot Starter
**This starters is designed to push auto-configuration to the next level** (and does nothing more than helping you with auto-configuration from application properties). In most cases, you should need 0 Java conf. An effort was made to make [tutorials](https://github.com/ch4mpy/spring-addons/tree/master/samples/tutorials), Javadoc and modules READMEs as informative as possible. Please refer there for more details.
`spring-addons-oidc-starter` does not replace `spring-boot-starter-oauth2-resource-server` and `spring-boot-starter-oauth2-client`, it defines a few beans designed to be picked by it.
Spring Boot starters are thin wrappers around `spring-boot-starter-oauth2-resource-server` or `spring-boot-starter-oauth2-client`:
- [spring-addons-webflux-client](https://github.com/ch4mpy/spring-addons/tree/master/webflux/spring-addons-webflux-client) to be used in reactive applications rendering templates on the server (Thymeleaf, JSF, etc.), **or in `spring-cloud-gateway` used as BFF** (server-side OAuth2 confidential client securing a browser application with sessions and replacing session cookies with OAuth2 access tokens before forwarding requests from browsers to resource servers)
- [spring-addons-webflux-introspecting-resource-server](https://github.com/ch4mpy/spring-addons/tree/master/webflux/spring-addons-webflux-introspecting-resource-server) to be used in reactive REST APIs secured with access token introspection
- [spring-addons-webflux-jwt-resource-server](https://github.com/ch4mpy/spring-addons/tree/master/webflux/spring-addons-webflux-jwt-resource-server) to be used in **reactive REST APIs secured with JWT decoders**
- [spring-addons-webmvc-client](https://github.com/ch4mpy/spring-addons/tree/master/webmvc/spring-addons-webmvc-client) to be used in servlet applications rendering templates on the server (Thymeleaf, JSF, etc.)
- [spring-addons-webmvc-introspecting-resource-server](https://github.com/ch4mpy/spring-addons/tree/master/webmvc/spring-addons-webmvc-introspecting-resource-server) to be used in servlet REST APIs secured with access token introspection
- [spring-addons-webmvc-jwt-resource-server](https://github.com/ch4mpy/spring-addons/tree/master/webmvc/spring-addons-webmvc-jwt-resource-server) to be used in **servlet REST APIs secured with JWT decoders**
It uses Spring Boot mechanisms to detect the kind of web application it is part of (servlet or reactive), what kind of application you are configuring (mostly based on properties: OAuth2 client or OAuth2 resource server and for the second, using JWT decoding or token introspection).
If you are curious enough, you might inspect what is auto-configured by reading the source code, starting from the [org.springframework.boot.autoconfigure.AutoConfiguration.imports](https://github.com/ch4mpy/spring-addons/blob/master/spring-addons-starter-oidc/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports) file, which is the Spring Boot standard entry-point defining what is loaded when a jar is on the classpath.
## 3. <a name="start"/>Where to Start
[Tutorials](https://github.com/ch4mpy/spring-addons/tree/master/samples/tutorials) which cover:
Expand All @@ -126,27 +126,26 @@ If locked wtih a lower JDK or spring-boot version, you'll have to use a 5.4.x re
I could forget to update README before releasing, so please refer to [maven central](https://repo1.maven.org/maven2/com/c4-soft/springaddons/spring-addons/) to pick latest available release
```xml
<properties>
<springaddons.version>6.2.0</springaddons.version>
<springaddons.version>7.0.0</springaddons.version>
<app-type>webmvc</app-type><!-- alternative value is webflux !-->
<token>jwt</token><!-- alternative value is introspecting !-->
</properties>
<dependencies>
<!-- to pull resource-server stater with its companion for unit-tests -->
<!-- to pull addons stater with its companion for unit-tests -->
<dependency>
<groupId>com.c4-soft.springaddons</groupId>
<artifactId>spring-addons-${app-type}-${token}-resource-server</artifactId>
<artifactId>spring-addons-starter-oidc</artifactId>
<version>${springaddons.version}</version>
</dependency>
<dependency>
<groupId>com.c4-soft.springaddons</groupId>
<artifactId>spring-addons-${app-type}-${token}-test</artifactId>
<artifactId>spring-addons-starter-oidc-test</artifactId>
<version>${springaddons.version}</version>
<scope>test</scope>
</dependency>
<!-- If you don't want starters but need @WithMockJwtAuth or WithMockBearerTokenAuthentication -->
<!-- instead of the two preceding, you can pull test annotations only -->
<!-- If you don't want to use the starter but need test annotations -->
<dependency>
<groupId>com.c4-soft.springaddons</groupId>
<artifactId>spring-addons-oauth2-test</artifactId>
Expand Down Expand Up @@ -180,6 +179,11 @@ Using such libs is dead simple: just declare depedency on one of those libs and
2.0 comes with a noticeable amount of breaking changes. So lets start tracking features.
### 7.0.0
See the [migration guide](https://github.com/ch4mpy/spring-addons/blob/master/7.0.0-migration-guide.md)
- merge all starters into 1
- reduce test libs count to 2: one with just annotations and another to ease testing of apps using the starter
### 6.2.0
- remove `OAuth2AuthenticationFactory`: instead, use `Converter<Jwt, ? extends AbstractAuthenticationToken>`, `Converter<Jwt, ? extends Mono<? extends AbstractAuthenticationToken>>`, `OpaqueTokenAuthenticationConverter` or `ReactiveOpaqueTokenAuthenticationConverter`
- create `@WithJwt` to build OAuth2 `Authentication` during tests, using a JSON string or file on the classpath and submitting it to the JWT authentication converter. All samples and tutorials are updated with this new annotation.
Expand Down
93 changes: 9 additions & 84 deletions pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@
<connection>scm:git:git://github.com/ch4mpy/spring-addons.git</connection>
<developerConnection>scm:git:[email protected]:ch4mpy/spring-addons.git</developerConnection>
<url>https://github.com/ch4mpy/spring-addons</url>
<tag>spring-addons-6.1.14</tag>
<tag>HEAD</tag>
</scm>

<distributionManagement>
Expand Down Expand Up @@ -101,88 +101,15 @@
<artifactId>spring-addons-oauth2-test</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>com.c4-soft.springaddons</groupId>
<artifactId>spring-addons-web-test</artifactId>
<version>${project.version}</version>
</dependency>

<dependency>
<groupId>com.c4-soft.springaddons</groupId>
<artifactId>spring-addons-webmvc-core</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>com.c4-soft.springaddons</groupId>
<artifactId>spring-addons-webmvc-introspecting-resource-server</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>com.c4-soft.springaddons</groupId>
<artifactId>spring-addons-webmvc-jwt-resource-server</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>com.c4-soft.springaddons</groupId>
<artifactId>spring-addons-webmvc-client</artifactId>
<version>${project.version}</version>
</dependency>

<dependency>
<groupId>com.c4-soft.springaddons</groupId>
<artifactId>spring-addons-webflux-core</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>com.c4-soft.springaddons</groupId>
<artifactId>spring-addons-webflux-introspecting-resource-server</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>com.c4-soft.springaddons</groupId>
<artifactId>spring-addons-webflux-jwt-resource-server</artifactId>
<artifactId>spring-addons-starter-oidc</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>com.c4-soft.springaddons</groupId>
<artifactId>spring-addons-webflux-client</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>com.c4-soft.springaddons</groupId>
<artifactId>spring-addons-webmvc-introspecting-test</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>com.c4-soft.springaddons</groupId>
<artifactId>spring-addons-webmvc-jwt-test</artifactId>
<version>${project.version}</version>
</dependency>

<dependency>
<groupId>com.c4-soft.springaddons</groupId>
<artifactId>spring-addons-webmvc-test</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>com.c4-soft.springaddons</groupId>
<artifactId>spring-addons-webflux-test</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>com.c4-soft.springaddons</groupId>
<artifactId>spring-addons-webflux-introspecting-test</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>com.c4-soft.springaddons</groupId>
<artifactId>spring-addons-webflux-jwt-test</artifactId>
<version>${project.version}</version>
</dependency>

<dependency>
<groupId>com.c4-soft.springaddons</groupId>
<artifactId>spring-addons-keycloak</artifactId>
<artifactId>spring-addons-starter-oidc-test</artifactId>
<version>${project.version}</version>
</dependency>
</dependencies>
Expand Down Expand Up @@ -392,12 +319,11 @@
<profile>
<id>release</id>
<modules>
<module>starters</module>
<module>spring-addons-oauth2</module>
<module>spring-addons-web-test</module>
<module>spring-addons-oauth2-test</module>
<module>webmvc</module>
<module>webflux</module>
<module>spring-addons-starter-oidc</module>
<module>spring-addons-starter-oidc-test</module>
<module>starters</module>
</modules>
<build>
<plugins>
Expand Down Expand Up @@ -432,12 +358,11 @@
<activeByDefault>true</activeByDefault>
</activation>
<modules>
<module>starters</module>
<module>spring-addons-oauth2</module>
<module>spring-addons-web-test</module>
<module>spring-addons-oauth2-test</module>
<module>webmvc</module>
<module>webflux</module>
<module>spring-addons-starter-oidc</module>
<module>spring-addons-starter-oidc-test</module>
<module>starters</module>
<module>samples</module>
</modules>
</profile>
Expand Down
4 changes: 2 additions & 2 deletions samples/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -87,7 +87,7 @@

<dependency>
<groupId>com.c4-soft.springaddons</groupId>
<artifactId>spring-addons-webmvc-jwt-resource-server</artifactId>
<artifactId>spring-addons-starter-oidc</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
Expand All @@ -97,7 +97,7 @@
</dependency>
<dependency>
<groupId>com.c4-soft.springaddons</groupId>
<artifactId>spring-addons-webmvc-test</artifactId>
<artifactId>spring-addons-starter-oidc-test</artifactId>
<version>${project.version}</version>
</dependency>

Expand Down
8 changes: 5 additions & 3 deletions samples/tutorials/bff/gateway/pom.xml
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>com.c4-soft.springaddons.samples.tutorials.bff</groupId>
Expand All @@ -10,7 +12,7 @@
<artifactId>bff-gateway</artifactId>
<name>BFF gateway</name>
<description>Backend For Frontend</description>

<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
Expand All @@ -30,7 +32,7 @@
</dependency>
<dependency>
<groupId>com.c4-soft.springaddons</groupId>
<artifactId>spring-addons-webflux-client</artifactId>
<artifactId>spring-addons-starter-oidc</artifactId>
</dependency>
<dependency>
<groupId>io.swagger.core.v3</groupId>
Expand Down
Loading

0 comments on commit 2582fd5

Please sign in to comment.