{"id":14973025,"url":"https://github.com/ch4mpy/spring-addons","last_synced_at":"2025-05-14T14:08:33.957Z","repository":{"id":37662073,"uuid":"184077868","full_name":"ch4mpy/spring-addons","owner":"ch4mpy","description":"Ease OAuth2 / OpenID in Spring RESTful backends","archived":false,"fork":false,"pushed_at":"2025-05-04T22:31:22.000Z","size":14768,"stargazers_count":618,"open_issues_count":3,"forks_count":97,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-05-04T23:30:06.710Z","etag":null,"topics":["auth0","cognito","hacktoberfest","keycloak","oidc","openid","openidconnect","spring-boot","spring-security"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ch4mpy.png","metadata":{"files":{"readme":"README.MD","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"license.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":"ch4mpy","tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"polar":null,"custom":null}},"created_at":"2019-04-29T13:37:17.000Z","updated_at":"2025-05-04T22:31:25.000Z","dependencies_parsed_at":"2022-07-12T16:42:38.226Z","dependency_job_id":"cde18173-22a6-4dfb-b2d8-f6ef82034625","html_url":"https://github.com/ch4mpy/spring-addons","commit_stats":{"total_commits":1656,"total_committers":19,"mean_commits":87.15789473684211,"dds":"0.012077294685990392","last_synced_commit":"5d3e3dd9ed1b40aa7efeef4aab5e107f8c836c92"},"previous_names":[],"tags_count":316,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ch4mpy%2Fspring-addons","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ch4mpy%2Fspring-addons/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ch4mpy%2Fspring-addons/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ch4mpy%2Fspring-addons/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ch4mpy","download_url":"https://codeload.github.com/ch4mpy/spring-addons/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254159800,"owners_count":22024564,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["auth0","cognito","hacktoberfest","keycloak","oidc","openid","openidconnect","spring-boot","spring-security"],"created_at":"2024-09-24T13:47:57.882Z","updated_at":"2025-05-14T14:08:33.951Z","avatar_url":"https://github.com/ch4mpy.png","language":"Java","readme":"# Ease OAuth2 / OpenID in Spring RESTful backends\n\n`8.1.13` is :rocket: to prevent [Open Redirect (CWE-601)](https://cwe.mitre.org/data/definitions/601.html) attacks. See [the manual](https://github.com/ch4mpy/spring-addons/tree/master/spring-addons-starter-oidc#1-2-11) or [the release notes](https://github.com/ch4mpy/spring-addons/blob/master/release-notes.md) for details.\n\n`8.1.13` is designed to work with Spring Boot `3.4.x` (Security `6.4.x` and Cloud `2024.0.x`). \n\nThe new [`spring-addons-starter-rest`](https://github.com/ch4mpy/spring-addons/tree/master/spring-addons-starter-rest) can be a game changer for inter-service calls when OAuth2 or an HTTP proxy is involved. Give it a try!\n\n## Minimal OAuth2 Background for Spring Backends\n\nThis repo hosts [tutorials for configuring Spring RESTful backends with OAuth2 / OIDC](https://github.com/ch4mpy/spring-addons/tree/master/samples/tutorials#securing-spring-applications-with-oauth2). **Remember that a few weeks of trials and error can save 15 minutes in a README.** So, you'd better carefully read the [_OAuth2 essentials_](https://github.com/ch4mpy/spring-addons/tree/master/samples/tutorials#1-oauth2-essentials) section, as well as [`spring-addons-starter-oidc`](https://github.com/ch4mpy/spring-addons/tree/master/spring-addons-starter-oidc#spring-addons-starter-oidc) and [`spring-addons-starter-rest`](https://github.com/ch4mpy/spring-addons/tree/master/spring-addons-starter-rest#auto-configure-restclient-or-webclient-beans) READMEs before jumping into implementation.\n\nThree tutorials from this repo have been moved to Baeldung:\n- [Getting started with Keycloak \u0026 Spring Boot](https://www.baeldung.com/spring-boot-keycloak)\n- [Creating an OAuth2 BFF with `spring-cloud-gateway` and consuming it with Single-Page Applications](https://www.baeldung.com/spring-cloud-gateway-bff-oauth2)\n- [Testing access control with mocked OAuth2 authentications](https://www.baeldung.com/spring-oauth-testing-access-control)\n\n## [`spring-addons-starter-oidc`](https://github.com/ch4mpy/spring-addons/tree/master/spring-addons-starter-oidc)\n\nWhen using just `spring-boot-starter-oauth2-client` or `spring-boot-starter-resource-server` we almost always end up writing the `Security(Web)FilterChain` ourselves, which requires a solid security background, some knowledge of Spring Security internals, and can be verbose.\n\n`spring-addons-starter-oidc` builds on top of _\"offical\"_ starters to significantly reduce the need for security configuration code. It even brings it down to 0 in most cases.\n\n**We have complete control over what `spring-addons-starter-oidc` auto-configures.** With application properties, of course, but also bean definitions: almost all auto-configured components are `@ConditionalOnMissingBean`, meaning that `spring-addons` backs off each time a component is explicitly defined in an application. But no need to define a complete security filter-chain, defining just the component to override should be enough.\n\nAuto-configuration for resource servers:\n- accepting tokens issued by several trusted authorization servers\n- mapping authorities from a variety of claims (including nested ones), with custom prefix and case\n- CORS configuration\n- allowing anonymous preflight requests using the path-matchers in CORS configuration\n\nAuto-configuration for clients with `oauth2Login`:\n- customizing responses returned to the frontend during the authorization-code and RP-Initiated Logout flows:\n  - specify the URI in `Location` header to activate a route after login / logout (defaults can be defined in application properties and overridden by the frontend using headers or query parameters)\n  - avoid some CORS issues with the authorization server: set the HTTP status in the `2xx` range to observe the response and handle the redirection in Javascript code instead of letting the browser follow with an Ajax request. There is no reason for these redirections to be cross-origin requests, plain navigation is what should actually happen.\n- exposing CSRF token as a cookie accessible to a single-page application\n- logging out from an authorization server not strictly implementing RP-Initiated Logout (case of Auth0 and Amazon Cognito for instance)\n- activating and configuring Back-Channel Logout\n- adding extra parameters to authorization \u0026 token requests (like the `audience` required by Auth0)\n- CORS configuration\n- allowing anonymous preflight requests using the path-matchers in CORS configuration\n\n## [`spring-addons-starter-rest`](https://github.com/ch4mpy/spring-addons/tree/master/spring-addons-starter-rest)\n\nAt an age where OpenAPI specs can be generated from REST APIs source code, and the client code to consume these APIs generated from the specs, the main challenge for inter-service communication is the configuration of REST clients. \n\nSpring promotes the usage of `RestClient` or `WebClient`, but configuring those for `Basic` or `Bearer` authentication, an HTTP proxy, and connection \u0026 read timeouts is pretty complicated, verbose, and error-prone.\n\n`spring-addons-starter-rest` makes this configuration a snap.\n\nSample usage\n```yaml\ncom:\n  c4-soft:\n    springaddons:\n      rest:\n        client:\n          # Exposes a RestClient bean named machinClient (or WebClient in a WebFlux app)\n          machin-client:\n            base-url: ${machin-api}\n            authorization:\n              oauth2:\n                # Authorize outgoing requests with the Bearer token in the security context (possible only in a resource server app)\n                forward-bearer: true\n          # Exposes a RestClient.Builder bean named biduleClientBuilder (mind the \"expose-builder: true\")\n          bidule-client:\n            base-url: ${bidule-api}\n            # Expose the builder instead of an already built client (to fine tune its conf)\n            expose-builder: true\n            authorization:\n              oauth2:\n                # Authorize outgoing requests with the Bearer token obtained using an OAuth2 client registration\n                oauth2-registration-id: bidule-registration\n```\nThis exposes pre-configured `RestClient` or `WebClient` beans (or their builders) that we can auto-wire in any kind of `@Component` - like `@Controller` \u0026 `@Service` - or use in `@Configuration` - for instance to generate implementations of `@HttpExchange` interfaces and expose them as beans.\n\nProxy configuration is applied by default to REST clients as soon as the `HTTP_PROXY` and `NO_PROXY` environment variables are set. This can be overridden and disabled with application properties.\n\n## Unit \u0026 Integration Testing With Security\n\nTesting access control requires configuring the test security context with a fine-tuned `Authentication` instance.\n\nFor that, `spring-security-test`  provides `MockMvc` request post-processors and `WebTestClient` mutators, but it can work only in the context of a request, which limits its usage to controllers. **To test any type of `@Component`** (`@Controller`, of course, but also `@Service` and `@Repository`) there are  only two options:\n- build tests security context by ourself and populate it with stubbed / mocked authentications :cry:\n- **use annotations** to do it for us (this is where [spring-addons-oauth2-test](https://github.com/ch4mpy/spring-addons/tree/master/spring-addons-oauth2-test) jumps in) :smiley:\n\nAlso, a notable difference between `@MockJwt` and those in `spring-security-test` is that **`spring-security-test` ignores the authentication converter defined in the security conf :sob:**. To understand the consequences, let's consider the flow to build the security context in a resource server with a JWT decoder:\n1. the JWT Bearer string is decoded, validated, and turned into a `org.springframework.security.oauth2.jwt.Jwt` by a `JwtDecoder`\n2. this `Jwt` (not JWT) is turned into something extending `AbstractAuthenticationToken` by an authentication converter. This step includes converting claims to authorities and the choice of a specific `Authentication` implementation.\n3. the `Authentication` instance is put in the security context\n\nWith `@WithJwt`, only the 1st step is mocked. A stub `Jwt` (not JWT) is built using a JSON payload in test resources and provided to the authentication converter. With `spring-security-test` post-processors and mutators, factories skip to step 3 and build a stub `Authentication` themselves, setting properties with what is provided in the test code. So, authorities conversion logic is used only with `@WithJwt`. Similarly, a custom `Authentication` implementation will be used in tests only if the authentication converter is called by the factory, and as so, with `@WithJwt`, but not with `.jwt()` post-processor.\n\nUseful resources:\n- [spring-addons-oauth2-test](https://github.com/ch4mpy/spring-addons/tree/master/spring-addons-oauth2-test) contains test annotations and its README documents usage\n- [spring-addons-starter-oidc-test](https://github.com/ch4mpy/spring-addons/tree/master/spring-addons-starter-oidc-test) if you use `spring-addons-starter-oidc`\n- [Baeldung article](https://www.baeldung.com/spring-oauth-testing-access-control)\n- [samples](https://github.com/ch4mpy/spring-addons/tree/master/samples) and [tutorials](https://github.com/ch4mpy/spring-addons/tree/master/samples/tutorials) source-code (which contain a lot of unit and integration testing)\n\n## Useful links\n- [`spring-addons-starter-oidc`](https://github.com/ch4mpy/spring-addons/tree/master/spring-addons-starter-oidc) a Spring Boot starter pushing OAuth2 clients \u0026 resource server security auto-configuration to the next level\n- [`spring-addons-oauth2-test`](https://github.com/ch4mpy/spring-addons/tree/master/spring-addons-oauth2-test) annotations for populating test security-context with OAuth2 authentication instances\n- [`spring-addons-starter-oidc-test`](https://github.com/ch4mpy/spring-addons/tree/master/spring-addons-starter-oidc-test) ease unit-tests in applications using `spring-addons-starter-oidc`\n- [`spring-addons-starter-rest`](https://github.com/ch4mpy/spring-addons/tree/master/spring-addons-starter-rest) experimental auto-configuration for `RestClient`, `WebClient` and `@HttpExchange` proxies (base-URL, Basic \u0026 OAuth2 Bearer auth)\n- [Getting started with Keycloak \u0026 Spring Boot](https://www.baeldung.com/spring-boot-keycloak)\n- [OAuth2 security configuration tutorials](https://github.com/ch4mpy/spring-addons/tree/master/samples/tutorials#securing-spring-applications-with-oauth2) (with and without `spring-addons-starter-oidc`)\n- [OAuth2 BFF tutorial](https://www.baeldung.com/spring-cloud-gateway-bff-oauth2)\n- [Release Notes](https://github.com/ch4mpy/spring-addons/tree/master/release-notes.md)\n- [Maven-Central Reminders](https://github.com/ch4mpy/spring-addons/tree/master/maven-central.md)\n","funding_links":["https://ko-fi.com/ch4mpy"],"categories":["测试"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fch4mpy%2Fspring-addons","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fch4mpy%2Fspring-addons","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fch4mpy%2Fspring-addons/lists"}