diff --git a/README.md b/README.md
index 4ade748..724166a 100644
--- a/README.md
+++ b/README.md
@@ -1,15 +1,21 @@
-# jwt-auth-demo
+# spring-auth-demo
-Runnable companion code for two articles on [ankurm.com](https://ankurm.com):
+Runnable companion code for three articles on [ankurm.com](https://ankurm.com):
| | article | code |
|---|---|---|
| 1 | [Spring Security 7.1 JWT Authentication: The Complete Guide (Spring Boot 4.1)](https://ankurm.com/spring-security-7-1-jwt-authentication-guide/) | [`jwt-authentication/`](jwt-authentication) |
| 2 | [Spring Security OAuth2 Resource Server: JWT Validation, JWKS and Key Rotation](https://ankurm.com/spring-security-oauth2-resource-server-jwks-key-rotation/) | [`oauth2-resource-server/`](oauth2-resource-server) |
+| 3 | [Spring Authorization Server: Running Your Own OAuth2 / OIDC Provider](https://ankurm.com/spring-authorization-server-oauth2-oidc-provider/) | [`authorization-server/`](authorization-server) |
-Two Maven projects, one shared [`docs/`](docs) tree. The first mints and verifies its own
-tokens with a hand-written filter; the second verifies tokens minted by somebody else —
-a real Keycloak, and a stub issuer whose signing keys can be rotated on command.
+Three Maven projects, one shared [`docs/`](docs) tree. The first mints and verifies its own
+tokens with a hand-written filter. The second verifies tokens minted by somebody else —
+a real Keycloak, and a stub issuer whose signing keys can be rotated on command. The third
+*is* the somebody else: a real OAuth2 / OIDC provider, with a client and a resource server
+in front of it.
+
+> This repository was called `jwt-auth-demo` until the third project landed. Gitea keeps the
+> old URL redirecting, but please update any bookmarks to `spring-auth-demo`.
Everything here was compiled and executed. Every file under [`docs/output/`](docs/output) is
real program output, regenerated by a script — not transcribed by hand.
@@ -23,6 +29,7 @@ real program output, regenerated by a script — not transcribed by hand.
| Nimbus JOSE+JWT | **10.9.1** |
| Tomcat | **11.0.24** |
| Jackson | **3.1.5** (`tools.jackson`) |
+| Spring Authorization Server | **7.1.1** — the same artifact, now versioned with Spring Security |
| Keycloak | **26.7.2** (resource server project only) |
| Caffeine | **3.2.4** (resource server project only) |
@@ -33,8 +40,8 @@ real program output, regenerated by a script — not transcribed by hand.
### Project 1 — JWT authentication with a hand-written filter
```bash
-git clone https://ankurm.com/git.app/asmhatre/jwt-auth-demo.git
-cd jwt-auth-demo/jwt-authentication
+git clone https://ankurm.com/git.app/asmhatre/spring-auth-demo.git
+cd spring-auth-demo/jwt-authentication
./scripts/run.sh hs256 # or: mvn spring-boot:run -Dspring-boot.run.profiles=hs256
# in another shell
@@ -44,7 +51,7 @@ cd jwt-auth-demo/jwt-authentication
### Project 2 — OAuth2 resource server, JWKS and rotation
```bash
-cd jwt-auth-demo/oauth2-resource-server
+cd spring-auth-demo/oauth2-resource-server
# a stub issuer whose JWK Set can be mutated on command
./scripts/run-stub-issuer.sh
@@ -57,6 +64,20 @@ docker compose -f docker/compose.yaml up -d
./scripts/keycloak-demo.sh
```
+### Project 3 — your own OAuth2 / OIDC provider
+
+```bash
+cd spring-auth-demo/authorization-server
+
+./scripts/run.sh auth # the provider, :9000
+./scripts/run.sh rs # an API that trusts it, :8090
+./scripts/run.sh client # a relying party, :8080
+
+# then open http://127.0.0.1:8080/orders and log in as alice / password
+# or drive the whole thing with curl:
+./scripts/authcode-pkce.sh
+```
+
---
## Project 1 — `jwt-authentication/`
@@ -167,9 +188,70 @@ Regenerate its captured output with `./oauth2-resource-server/scripts/run-all.sh
---
+## Project 3 — `authorization-server/`
+
+Three Maven modules, three JVMs, three ports. Nothing about an authorization server is
+observable without a client to drive the browser redirect and a resource server to accept
+or reject what comes out.
+
+| module | port | what it is |
+|---|---|---|
+| [`auth-server/`](authorization-server/auth-server) | 9000 | the provider: clients, PKCE, consent, token customisation |
+| [`resource-server/`](authorization-server/resource-server) | 8090 | an API that trusts its tokens |
+| [`oidc-client/`](authorization-server/oidc-client) | 8080 | a relying party that logs in and calls the API |
+
+Two users: `alice` / `password` (`ROLE_USER`, `ROLE_ADMIN`) and `bob` / `password`
+(`ROLE_USER`).
+
+Three registered clients:
+
+| client | secret | authentication | grants |
+|---|---|---|---|
+| `demo-web` | `web-secret` | `client_secret_basic` | authorization code + refresh |
+| `demo-spa` | — | `none` (public) | authorization code + refresh |
+| `demo-service` | `service-secret` | `client_secret_basic` | client credentials |
+
+### Profiles
+
+| module | profile | what it changes |
+|---|---|---|
+| auth-server | *(none)* | consent on, PKCE required, custom claims, JWT tokens |
+| auth-server | `noconsent` | `requireAuthorizationConsent(false)` on every client |
+| auth-server | `nopkce` | `requireProofKey(false)` on the public client |
+| auth-server | `noclaims` | the `OAuth2TokenCustomizer` bean is not registered |
+| auth-server | `opaque` | `demo-service` gets reference tokens instead of JWTs |
+| auth-server | `acceptall` | the entry-point matcher without `setIgnoredMediaTypes` — see [docs/authorization-server/09](docs/authorization-server/09-entry-point.md) |
+| auth-server | `trace` | `TRACE` logging for `org.springframework.security` |
+| resource-server | `noaud` | audience validation off, i.e. the Spring Boot default |
+| oidc-client | `nopkce` | rebuilds the registration the way Spring Security 6.x would |
+
+### Endpoints
+
+| method | path | port | what it is |
+|---|---|---|---|
+| `GET` | `/.well-known/openid-configuration` | 9000 | OIDC discovery. Only present because `.oidc(...)` is on |
+| `GET` | `/.well-known/oauth-authorization-server` | 9000 | the OAuth2 metadata document, always present |
+| `GET` | `/oauth2/jwks` | 9000 | public keys |
+| `GET` | `/oauth2/authorize` | 9000 | the authorization endpoint |
+| `POST` | `/oauth2/token` | 9000 | the token endpoint |
+| `POST` | `/oauth2/introspect` | 9000 | for opaque tokens |
+| `GET` | `/oauth2/consent` | 9000 | **our** consent page |
+| `GET` | `/userinfo` | 9000 | OIDC UserInfo |
+| `GET` | `/diag/settings`, `/diag/clients`, `/diag/chains` | 9000 | **diagnostics. Delete before shipping** |
+| `GET` | `/api/orders` | 8090 | needs `SCOPE_orders.read` |
+| `POST` | `/api/orders` | 8090 | needs `SCOPE_orders.write` |
+| `GET` | `/api/admin` | 8090 | needs `ROLE_ADMIN`, which only exists via the token customiser |
+| `GET` | `/whoami` | 8090 | everything the resource server decoded |
+| `GET` | `/orders` | 8080 | the relying party's page; triggers the whole flow |
+
+Regenerate its captured output with `./authorization-server/scripts/run-all.sh`
+(no Docker needed; roughly three minutes).
+
+---
+
## Documentation
-One numbered trail across both projects. Start at
+One numbered trail across the first two projects, plus a separate set for the third. Start at
[`docs/01-architecture.md`](docs/01-architecture.md).
| doc | covers |
@@ -193,6 +275,24 @@ One numbered trail across both projects. Start at
| [17 — Keycloak setup](docs/17-keycloak-setup.md) | compose, realm import, and three ways it bites |
| [18 — Resource server checklist](docs/18-resource-server-checklist.md) | the list for the resource-server side |
+### Project 3 — running your own provider
+
+A separate chapter set, indexed at
+[`docs/authorization-server/`](docs/authorization-server/README.md).
+
+| doc | covers |
+|---|---|
+| [01 — Versions and the 7.0 move](docs/authorization-server/01-versions.md) | why there is no SAS version to pin, and which starter to use |
+| [02 — The minimum working provider](docs/authorization-server/02-minimum-provider.md) | two chains, and the API that replaced `applyDefaultSecurity` |
+| [03 — Clients, PKCE and the defaults that moved](docs/authorization-server/03-clients-and-pkce.md) | `requireProofKey` flipped to `true` on both sides |
+| [04 — The consent page](docs/authorization-server/04-consent-page.md) | the form contract, and the redirect loop |
+| [05 — Token customisation](docs/authorization-server/05-token-customisation.md) | the bean the JWT generator looks for, and the one it ignores |
+| [06 — The resource server side](docs/authorization-server/06-resource-server.md) | what `issuer-uri` does and does not validate |
+| [07 — Diagnostics](docs/authorization-server/07-diagnostics.md) | reading the effective configuration back out |
+| [08 — The relying party](docs/authorization-server/08-client.md) | a real browser flow, and the client-side PKCE default |
+| [09 — Entry point and the Accept header](docs/authorization-server/09-entry-point.md) | why the token endpoint 302s to a login page |
+| [10 — Should you run one at all](docs/authorization-server/10-should-you.md) | the honest answer |
+
---
## Captured output
@@ -229,6 +329,22 @@ One numbered trail across both projects. Start at
| [`rs-keycloak-default-converter.txt`](docs/output/rs-keycloak-default-converter.txt) | real Keycloak, roles unmapped |
| [`rs-test-run.txt`](docs/output/rs-test-run.txt) | 10 tests pinning the default validator stack |
+### Project 3
+
+Indexed in full at
+[`docs/authorization-server/README.md`](docs/authorization-server/README.md). The ones worth
+opening first:
+
+| file | what it shows |
+|---|---|
+| [`as-settings-defaults.txt`](docs/output/as-settings-defaults.txt) | `requireProofKey` false in SAS 1.5.8 and Spring Security 6.5.1, true in 7.1.1 — both sides |
+| [`as-legacy-compile-failure.txt`](docs/output/as-legacy-compile-failure.txt) | the pre-7.0 configuration, and the four compiler errors it now produces |
+| [`as-authcode-pkce.txt`](docs/output/as-authcode-pkce.txt) | the whole authorization-code + PKCE flow, every parameter visible |
+| [`as-client-flow-nopkce.txt`](docs/output/as-client-flow-nopkce.txt) | a pre-7.0 client against a 7.1 provider, failing on the client's own error page |
+| [`as-entrypoint-accept.txt`](docs/output/as-entrypoint-accept.txt) | 302 vs 401 from the token endpoint, decided by the `Accept` header |
+| [`as-client-credentials-opaque.txt`](docs/output/as-client-credentials-opaque.txt) | a reference token, and what introspection returns for it |
+| [`as-test-run.txt`](docs/output/as-test-run.txt) | 7 contract tests |
+
---
## Security note
@@ -244,6 +360,12 @@ them at anything you care about — see
`/api/public/decoder` reads private fields by reflection and prints your JWK Set URI and
cache timings. It is a diagnostic. Delete it before you ship.
+The authorization server's `/diag/*` endpoints are the same kind of thing: they publish
+client ids, grant types, scopes and your filter-chain ordering with no authentication. Its
+signing key is generated fresh on every boot, and its users are hard-coded. Read
+[docs/authorization-server/10-should-you.md](docs/authorization-server/10-should-you.md)
+before taking any of it near production.
+
## License
MIT.
diff --git a/authorization-server/auth-server/pom.xml b/authorization-server/auth-server/pom.xml
new file mode 100644
index 0000000..768d9ae
--- /dev/null
+++ b/authorization-server/auth-server/pom.xml
@@ -0,0 +1,65 @@
+
+
+ 4.0.0
+
+
+ com.ankurm
+ authorization-server-demo
+ 1.0.0
+
+
+ auth-server
+ auth-server
+ The OAuth2 / OIDC provider itself
+
+
+
+
+ org.springframework.boot
+ spring-boot-starter-security-oauth2-authorization-server
+
+
+ org.springframework.boot
+ spring-boot-starter-thymeleaf
+
+
+
+ org.springframework.boot
+ spring-boot-starter-test
+ test
+
+
+
+ org.springframework.boot
+ spring-boot-starter-webmvc-test
+ test
+
+
+ org.springframework.boot
+ spring-boot-starter-security-test
+ test
+
+
+
+
+
+
+ org.springframework.boot
+ spring-boot-maven-plugin
+
+
+
+
diff --git a/authorization-server/auth-server/src/main/java/com/ankurm/authserver/AuthServerApplication.java b/authorization-server/auth-server/src/main/java/com/ankurm/authserver/AuthServerApplication.java
new file mode 100644
index 0000000..94fdd99
--- /dev/null
+++ b/authorization-server/auth-server/src/main/java/com/ankurm/authserver/AuthServerApplication.java
@@ -0,0 +1,28 @@
+package com.ankurm.authserver;
+
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+/**
+ * The provider. Runs on :9000 and is the issuer for everything else in this module.
+ *
+ *
Start it with {@code ../scripts/run.sh auth} (default profile) or with one of the
+ * variant profiles that deliberately break something:
+ *
+ *
+ *
{@code noconsent} — consent turned off for the confidential client
+ *
{@code nopkce} — the public client no longer requires PKCE
+ *
{@code noclaims} — the token customiser is not registered
+ *
{@code opaque} — the service client gets reference tokens, not JWTs
+ *
+ * And {@code OAuth2AuthorizationServerConfiguration.applyDefaultSecurity(http)} — the
+ * static method essentially every blog post calls — no longer exists. It was public
+ * and static in 1.5.8; in 7.1.1 the class exposes only {@code @Bean} methods. The
+ * replacement is {@code http.with(new OAuth2AuthorizationServerConfigurer(), ...)}, which
+ * is what this class does.
+ *
+ * @see
+ * docs/authorization-server/01-versions.md
+ * @see
+ * docs/authorization-server/02-minimum-provider.md
+ */
+@Configuration(proxyBeanMethods = false)
+public class AuthorizationServerConfig {
+
+ /**
+ * Order matters and the ordering is not cosmetic. This chain carries a
+ * {@code securityMatcher} restricted to the protocol endpoints, so it must be
+ * consulted before the catch-all form-login chain in {@link DefaultSecurityConfig}.
+ * If the two are swapped, the form-login chain matches {@code /oauth2/token} first,
+ * the token endpoint is never reached, and a token request 302s to {@code /login}.
+ * That redirect is the fingerprint of a mis-ordered pair of chains.
+ */
+ @Bean
+ @Order(Ordered.HIGHEST_PRECEDENCE)
+ public SecurityFilterChain authorizationServerChain(
+ HttpSecurity http,
+ @Value("${demo.ignore-accept-all:true}") boolean ignoreAcceptAll) throws Exception {
+ OAuth2AuthorizationServerConfigurer authorizationServer =
+ new OAuth2AuthorizationServerConfigurer();
+
+ http
+ .securityMatcher(authorizationServer.getEndpointsMatcher())
+ .with(authorizationServer, server -> server
+ // Turning OIDC on is one line, and it is not on by default: without it
+ // there is no /userinfo, no id_token, and no
+ // /.well-known/openid-configuration - only the OAuth2 metadata document
+ // at /.well-known/oauth-authorization-server.
+ .oidc(Customizer.withDefaults())
+ // Replace the built-in consent page with our own. The value is a path the
+ // authorization endpoint redirects the browser to; it is *our* MVC
+ // controller, protected by the form-login chain, and it must POST back to
+ // /oauth2/authorize. See ConsentController.
+ .authorizationEndpoint(endpoint -> endpoint.consentPage("/oauth2/consent"))
+ )
+ .authorizeHttpRequests(auth -> auth.anyRequest().authenticated())
+ // An unauthenticated GET /oauth2/authorize must send a *browser* to the login
+ // page, and must not do that to a machine calling /oauth2/token.
+ //
+ // Scoping the entry point with MediaTypeRequestMatcher(TEXT_HTML) is the
+ // documented way to express that, and on its own it does not work. curl,
+ // most HTTP clients and anything that does not set Accept send `*/*`, and
+ // `*/*` matches text/html, so the matcher fires and the token endpoint
+ // answers a failed public-client authentication with `302 -> /login`
+ // instead of a JSON 401. setIgnoredMediaTypes(ALL) is the line that fixes
+ // it. Run with the `acceptall` profile to see the unfixed behaviour, and
+ // compare docs/output/as-entrypoint-accept.txt.
+ .exceptionHandling(ex -> ex.defaultAuthenticationEntryPointFor(
+ new LoginUrlAuthenticationEntryPoint("/login"),
+ htmlOnly(ignoreAcceptAll)))
+ .oauth2ResourceServer(rs -> rs.jwt(Customizer.withDefaults()));
+
+ return http.build();
+ }
+
+ private static MediaTypeRequestMatcher htmlOnly(boolean ignoreAcceptAll) {
+ MediaTypeRequestMatcher matcher = new MediaTypeRequestMatcher(MediaType.TEXT_HTML);
+ if (ignoreAcceptAll) {
+ matcher.setIgnoredMediaTypes(Set.of(MediaType.ALL));
+ }
+ return matcher;
+ }
+
+ /**
+ * These two look optional and are not, the moment you write a custom consent page.
+ *
+ *
{@code OAuth2AuthorizationServerConfigurer} creates in-memory implementations for
+ * its own use when you do not supply them, but they are not published as beans you can
+ * inject. A {@code ConsentController} that constructor-injects
+ * {@code OAuth2AuthorizationConsentService} therefore fails the context at startup with
+ * {@code No qualifying bean of type ...OAuth2AuthorizationConsentService available} -
+ * the exact message is committed in
+ * {@code docs/output/as-missing-consent-service.txt}. Declaring them here fixes it and,
+ * more usefully, makes the storage decision explicit: both of these are per-instance
+ * memory, so a second replica of the authorization server cannot complete a code
+ * exchange started on the first.
+ */
+ @Bean
+ public OAuth2AuthorizationService authorizationService() {
+ return new InMemoryOAuth2AuthorizationService();
+ }
+
+ @Bean
+ public OAuth2AuthorizationConsentService authorizationConsentService() {
+ return new InMemoryOAuth2AuthorizationConsentService();
+ }
+
+ /**
+ * The issuer identifier. Everything downstream keys off this string: it is the
+ * {@code iss} claim, the base of the discovery document, and the value a resource
+ * server compares against. {@code http://localhost:9000} works only because both
+ * sides agree on it exactly — a trailing slash here and no trailing slash on
+ * the resource server is a mismatch, and produces
+ * {@code The iss claim is not valid} at validation time, not at startup.
+ */
+ @Bean
+ public AuthorizationServerSettings authorizationServerSettings() {
+ return AuthorizationServerSettings.builder()
+ .issuer("http://localhost:9000")
+ .build();
+ }
+
+ /**
+ * A fresh RSA keypair per boot. That is deliberate for a demo — restart the
+ * server and every previously issued token stops verifying, which is exactly the
+ * behaviour you want to notice now rather than in production. A real deployment
+ * loads a persistent key (or a rotating set) and serves both the current and the
+ * previous public key from the JWK Set so in-flight tokens survive rotation; that is
+ * the subject of docs/15-jwks-caching-and-rotation.md in the resource-server project.
+ */
+ @Bean
+ public JWKSource jwkSource() {
+ KeyPair keyPair = generateRsaKey();
+ RSAPublicKey publicKey = (RSAPublicKey) keyPair.getPublic();
+ RSAPrivateKey privateKey = (RSAPrivateKey) keyPair.getPrivate();
+ RSAKey rsaKey = new RSAKey.Builder(publicKey)
+ .privateKey(privateKey)
+ .keyID(UUID.randomUUID().toString())
+ .build();
+ return new ImmutableJWKSet<>(new JWKSet(rsaKey));
+ }
+
+ private static KeyPair generateRsaKey() {
+ try {
+ KeyPairGenerator generator = KeyPairGenerator.getInstance("RSA");
+ generator.initialize(2048);
+ return generator.generateKeyPair();
+ } catch (Exception ex) {
+ throw new IllegalStateException("cannot generate an RSA keypair", ex);
+ }
+ }
+
+ /**
+ * The authorization server is also a resource server for its own UserInfo endpoint.
+ * This static helper is one of the few things that survived the 7.0 package move
+ * unchanged in shape - only its package changed.
+ */
+ @Bean
+ public JwtDecoder jwtDecoder(JWKSource jwkSource) {
+ return OAuth2AuthorizationServerConfiguration.jwtDecoder(jwkSource);
+ }
+}
diff --git a/authorization-server/auth-server/src/main/java/com/ankurm/authserver/config/DefaultSecurityConfig.java b/authorization-server/auth-server/src/main/java/com/ankurm/authserver/config/DefaultSecurityConfig.java
new file mode 100644
index 0000000..e5bba8d
--- /dev/null
+++ b/authorization-server/auth-server/src/main/java/com/ankurm/authserver/config/DefaultSecurityConfig.java
@@ -0,0 +1,63 @@
+package com.ankurm.authserver.config;
+
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.security.config.Customizer;
+import org.springframework.security.config.annotation.web.builders.HttpSecurity;
+import org.springframework.security.core.userdetails.User;
+import org.springframework.security.core.userdetails.UserDetails;
+import org.springframework.security.core.userdetails.UserDetailsService;
+import org.springframework.security.crypto.factory.PasswordEncoderFactories;
+import org.springframework.security.crypto.password.PasswordEncoder;
+import org.springframework.security.provisioning.InMemoryUserDetailsManager;
+import org.springframework.security.web.SecurityFilterChain;
+
+/**
+ * The second chain: everything that is not a protocol endpoint. The login form, the
+ * consent page, static assets, the diagnostics endpoint.
+ *
+ *
Two chains is the shape, not an optimisation. The protocol chain in
+ * {@link AuthorizationServerConfig} carries a {@code securityMatcher} and therefore
+ * declines every request that is not an OAuth2 or OIDC endpoint; something has to pick
+ * those up, and it needs a completely different authentication mechanism (a browser
+ * session, not a bearer token).
+ *
+ * @see
+ * docs/authorization-server/03-clients-and-pkce.md
+ */
+@Configuration(proxyBeanMethods = false)
+public class DefaultSecurityConfig {
+
+ @Bean
+ public SecurityFilterChain defaultChain(HttpSecurity http) throws Exception {
+ http
+ .authorizeHttpRequests(auth -> auth
+ .requestMatchers("/diag/**", "/error", "/favicon.ico").permitAll()
+ .anyRequest().authenticated())
+ .formLogin(Customizer.withDefaults());
+ return http.build();
+ }
+
+ /**
+ * Two users so the consent screen and the token claims have something to differ on.
+ * {@code alice} is an admin, {@code bob} is not, and the token customiser copies
+ * their authorities into a {@code roles} claim the resource server reads.
+ *
+ *
{@code {noop}} is not a placeholder for a password hash - it is a
+ * {@code DelegatingPasswordEncoder} prefix meaning "stored in clear". Useful for a
+ * demo, an incident in production.
+ */
+ @Bean
+ public UserDetailsService users() {
+ PasswordEncoder encoder = PasswordEncoderFactories.createDelegatingPasswordEncoder();
+ UserDetails alice = User.withUsername("alice")
+ .password(encoder.encode("password"))
+ .roles("USER", "ADMIN")
+ .build();
+ UserDetails bob = User.withUsername("bob")
+ .password(encoder.encode("password"))
+ .roles("USER")
+ .build();
+ return new InMemoryUserDetailsManager(alice, bob);
+ }
+}
diff --git a/authorization-server/auth-server/src/main/java/com/ankurm/authserver/config/RegisteredClientConfig.java b/authorization-server/auth-server/src/main/java/com/ankurm/authserver/config/RegisteredClientConfig.java
new file mode 100644
index 0000000..56590c2
--- /dev/null
+++ b/authorization-server/auth-server/src/main/java/com/ankurm/authserver/config/RegisteredClientConfig.java
@@ -0,0 +1,126 @@
+package com.ankurm.authserver.config;
+
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.security.crypto.factory.PasswordEncoderFactories;
+import org.springframework.security.crypto.password.PasswordEncoder;
+import org.springframework.security.oauth2.core.AuthorizationGrantType;
+import org.springframework.security.oauth2.core.ClientAuthenticationMethod;
+import org.springframework.security.oauth2.core.oidc.OidcScopes;
+import org.springframework.security.oauth2.server.authorization.client.InMemoryRegisteredClientRepository;
+import org.springframework.security.oauth2.server.authorization.client.RegisteredClient;
+import org.springframework.security.oauth2.server.authorization.client.RegisteredClientRepository;
+import org.springframework.security.oauth2.server.authorization.settings.ClientSettings;
+import org.springframework.security.oauth2.server.authorization.settings.OAuth2TokenFormat;
+import org.springframework.security.oauth2.server.authorization.settings.TokenSettings;
+
+import java.time.Duration;
+import java.util.UUID;
+
+/**
+ * Client registration. Three clients, each demonstrating a different half of the
+ * {@link ClientSettings} / {@link TokenSettings} surface.
+ *
+ *
A {@code RegisteredClient} is not a user and not a credential - it is a *policy*.
+ * It says which grants this caller may use, which redirect URIs are acceptable, which
+ * scopes it may ask for, whether the user has to consent, whether PKCE is mandatory, and
+ * how long the resulting tokens live. Almost every "it works in Postman but not in the
+ * browser" report is one of these fields.
+ *
+ * @see
+ * docs/authorization-server/03-clients-and-pkce.md
+ */
+@Configuration(proxyBeanMethods = false)
+public class RegisteredClientConfig {
+
+ /**
+ * Set to {@code false} by the {@code noconsent} profile, and to {@code false} for PKCE
+ * by the {@code nopkce} profile. Both exist so the failure is one flag away and can be
+ * captured as real output rather than described.
+ */
+ @Bean
+ public RegisteredClientRepository registeredClientRepository(
+ @Value("${demo.require-consent:true}") boolean requireConsent,
+ @Value("${demo.require-pkce:true}") boolean requirePkce,
+ @Value("${demo.service-token-format:jwt}") String serviceTokenFormat) {
+
+ PasswordEncoder encoder = PasswordEncoderFactories.createDelegatingPasswordEncoder();
+
+ // ---- 1. A confidential web application: authorization_code + refresh_token ----
+ RegisteredClient webClient = RegisteredClient.withId(UUID.randomUUID().toString())
+ .clientId("demo-web")
+ // The secret is *hashed*. Registering a bare string here and then sending
+ // it from the client produces "invalid_client" with no further detail,
+ // because the server bcrypt-compares the presented secret against what it
+ // believes is a hash. This is the single most common first-hour failure.
+ .clientSecret(encoder.encode("web-secret"))
+ .clientAuthenticationMethod(ClientAuthenticationMethod.CLIENT_SECRET_BASIC)
+ .authorizationGrantType(AuthorizationGrantType.AUTHORIZATION_CODE)
+ .authorizationGrantType(AuthorizationGrantType.REFRESH_TOKEN)
+ // Exact-match, including scheme, port and path. No wildcards, no prefix
+ // matching. A mismatch is rejected *before* login, with the error rendered
+ // by the authorization server rather than sent to the client - by design,
+ // since redirecting to an unvalidated URI is the vulnerability.
+ .redirectUri("http://127.0.0.1:8080/login/oauth2/code/demo-web")
+ .postLogoutRedirectUri("http://127.0.0.1:8080/")
+ .scope(OidcScopes.OPENID)
+ .scope(OidcScopes.PROFILE)
+ .scope("orders.read")
+ .scope("orders.write")
+ .clientSettings(ClientSettings.builder()
+ .requireAuthorizationConsent(requireConsent)
+ .build())
+ .tokenSettings(TokenSettings.builder()
+ .accessTokenTimeToLive(Duration.ofMinutes(5))
+ .refreshTokenTimeToLive(Duration.ofMinutes(60))
+ // false means every refresh returns a *new* refresh token and
+ // invalidates the old one. That is rotation, and it is how a
+ // stolen refresh token becomes detectable.
+ .reuseRefreshTokens(false)
+ .build())
+ .build();
+
+ // ---- 2. A public client (SPA / native): no secret, PKCE mandatory ----
+ RegisteredClient spaClient = RegisteredClient.withId(UUID.randomUUID().toString())
+ .clientId("demo-spa")
+ .clientAuthenticationMethod(ClientAuthenticationMethod.NONE)
+ .authorizationGrantType(AuthorizationGrantType.AUTHORIZATION_CODE)
+ .authorizationGrantType(AuthorizationGrantType.REFRESH_TOKEN)
+ .redirectUri("http://127.0.0.1:8080/authorized")
+ .scope(OidcScopes.OPENID)
+ .scope("orders.read")
+ .clientSettings(ClientSettings.builder()
+ // With NONE authentication this is the only thing standing between
+ // an intercepted authorization code and an access token. Spring
+ // Authorization Server does not infer it: a public client with
+ // requireProofKey(false) will happily complete a code exchange
+ // with no verifier at all. The `nopkce` profile shows that.
+ .requireProofKey(requirePkce)
+ .requireAuthorizationConsent(requireConsent)
+ .build())
+ .build();
+
+ // ---- 3. A machine client: client_credentials, no user, no refresh token ----
+ RegisteredClient serviceClient = RegisteredClient.withId(UUID.randomUUID().toString())
+ .clientId("demo-service")
+ .clientSecret(encoder.encode("service-secret"))
+ .clientAuthenticationMethod(ClientAuthenticationMethod.CLIENT_SECRET_BASIC)
+ .authorizationGrantType(AuthorizationGrantType.CLIENT_CREDENTIALS)
+ .scope("orders.read")
+ .tokenSettings(TokenSettings.builder()
+ .accessTokenTimeToLive(Duration.ofMinutes(10))
+ // SELF_CONTAINED is a signed JWT the resource server verifies
+ // offline. REFERENCE is an opaque string that only means anything
+ // to /oauth2/introspect - which turns every API call into a
+ // network round trip to the authorization server, and gives you
+ // instant revocation in exchange. The `opaque` profile flips it.
+ .accessTokenFormat("reference".equals(serviceTokenFormat)
+ ? OAuth2TokenFormat.REFERENCE
+ : OAuth2TokenFormat.SELF_CONTAINED)
+ .build())
+ .build();
+
+ return new InMemoryRegisteredClientRepository(webClient, spaClient, serviceClient);
+ }
+}
diff --git a/authorization-server/auth-server/src/main/java/com/ankurm/authserver/diag/ProviderDiagnostics.java b/authorization-server/auth-server/src/main/java/com/ankurm/authserver/diag/ProviderDiagnostics.java
new file mode 100644
index 0000000..ede736f
--- /dev/null
+++ b/authorization-server/auth-server/src/main/java/com/ankurm/authserver/diag/ProviderDiagnostics.java
@@ -0,0 +1,105 @@
+package com.ankurm.authserver.diag;
+
+import org.springframework.security.oauth2.server.authorization.client.RegisteredClient;
+import org.springframework.security.oauth2.server.authorization.client.RegisteredClientRepository;
+import org.springframework.security.oauth2.server.authorization.settings.AuthorizationServerSettings;
+import org.springframework.security.web.FilterChainProxy;
+import org.springframework.security.web.SecurityFilterChain;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Runtime state that is otherwise invisible: the resolved endpoint paths, the registered
+ * clients as the server actually holds them, and the live filter chains in order.
+ *
+ *
This exists because the interesting configuration in an authorization server is
+ * spread across three builders and two filter chains, and the effective result is not
+ * printed anywhere at startup. Reading the beans back is faster than reasoning about them.
+ *
+ *
Delete this before shipping. It exposes client ids, scopes, grant types and
+ * your chain ordering to anyone who can reach {@code /diag}.
+ *
+ * @see
+ * docs/authorization-server/07-diagnostics.md
+ */
+@RestController
+@RequestMapping("/diag")
+public class ProviderDiagnostics {
+
+ private final RegisteredClientRepository clients;
+ private final AuthorizationServerSettings settings;
+ private final FilterChainProxy filterChainProxy;
+
+ public ProviderDiagnostics(RegisteredClientRepository clients,
+ AuthorizationServerSettings settings,
+ FilterChainProxy filterChainProxy) {
+ this.clients = clients;
+ this.settings = settings;
+ this.filterChainProxy = filterChainProxy;
+ }
+
+ /** Every endpoint path the server resolved, including the ones you did not set. */
+ @GetMapping("/settings")
+ public Map settings() {
+ return new LinkedHashMap<>(this.settings.getSettings());
+ }
+
+ /**
+ * The registered clients, flattened. Note that the client secret is not returned -
+ * it is a hash, and printing it invites people to try to use it as a secret.
+ */
+ @GetMapping("/clients")
+ public List> clients() {
+ List> out = new ArrayList<>();
+ for (String id : List.of("demo-web", "demo-spa", "demo-service")) {
+ RegisteredClient c = this.clients.findByClientId(id);
+ if (c == null) {
+ continue;
+ }
+ Map m = new LinkedHashMap<>();
+ m.put("clientId", c.getClientId());
+ m.put("authenticationMethods", c.getClientAuthenticationMethods().stream()
+ .map(a -> a.getValue()).toList());
+ m.put("grantTypes", c.getAuthorizationGrantTypes().stream()
+ .map(g -> g.getValue()).toList());
+ m.put("redirectUris", c.getRedirectUris());
+ m.put("scopes", c.getScopes());
+ m.put("requireProofKey", c.getClientSettings().isRequireProofKey());
+ m.put("requireAuthorizationConsent",
+ c.getClientSettings().isRequireAuthorizationConsent());
+ m.put("accessTokenFormat",
+ c.getTokenSettings().getAccessTokenFormat().getValue());
+ m.put("accessTokenTtlSeconds",
+ c.getTokenSettings().getAccessTokenTimeToLive().toSeconds());
+ m.put("reuseRefreshTokens", c.getTokenSettings().isReuseRefreshTokens());
+ out.add(m);
+ }
+ return out;
+ }
+
+ /**
+ * The filter chains in the order Spring Security will consult them, with the matcher
+ * each one carries. If the authorization server chain is not first, the token endpoint
+ * is unreachable - and this is where you see that, rather than inferring it from a 302.
+ */
+ @GetMapping("/chains")
+ public List> chains() {
+ List> out = new ArrayList<>();
+ int i = 0;
+ for (SecurityFilterChain chain : this.filterChainProxy.getFilterChains()) {
+ Map m = new LinkedHashMap<>();
+ m.put("position", i++);
+ m.put("matcher", String.valueOf(chain));
+ m.put("filters", chain.getFilters().stream()
+ .map(f -> f.getClass().getSimpleName()).toList());
+ out.add(m);
+ }
+ return out;
+ }
+}
diff --git a/authorization-server/auth-server/src/main/java/com/ankurm/authserver/token/TokenClaimsCustomizer.java b/authorization-server/auth-server/src/main/java/com/ankurm/authserver/token/TokenClaimsCustomizer.java
new file mode 100644
index 0000000..0afeaef
--- /dev/null
+++ b/authorization-server/auth-server/src/main/java/com/ankurm/authserver/token/TokenClaimsCustomizer.java
@@ -0,0 +1,81 @@
+package com.ankurm.authserver.token;
+
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.context.annotation.Profile;
+import org.springframework.security.core.GrantedAuthority;
+import org.springframework.security.oauth2.server.authorization.OAuth2TokenType;
+import org.springframework.security.oauth2.core.oidc.endpoint.OidcParameterNames;
+import org.springframework.security.oauth2.server.authorization.token.JwtEncodingContext;
+import org.springframework.security.oauth2.server.authorization.token.OAuth2TokenCustomizer;
+
+import java.util.List;
+import java.util.Set;
+import java.util.stream.Collectors;
+
+/**
+ * Token customisation — the hook that decides what a downstream service can
+ * authorise on without calling back.
+ *
+ *
One bean of type {@code OAuth2TokenCustomizer} is picked up
+ * automatically by the JWT generator. There is no registration step and no annotation;
+ * if the bean exists with that exact generic type, it runs. Declare it as
+ * {@code OAuth2TokenCustomizer} by mistake — the type used
+ * for *opaque* tokens — and it will be silently ignored, because the JWT generator
+ * resolves the bean by generic type and simply will not find it. Nothing logs. Your
+ * claims are just absent.
+ *
+ *
The {@code noclaims} profile disables this bean, so the difference is a diff of two
+ * decoded tokens rather than a paragraph.
+ *
+ * @see
+ * docs/authorization-server/05-token-customisation.md
+ */
+@Configuration(proxyBeanMethods = false)
+@Profile("!noclaims")
+public class TokenClaimsCustomizer {
+
+ @Bean
+ public OAuth2TokenCustomizer jwtCustomizer() {
+ return context -> {
+ // context.getTokenType() distinguishes the access token, the id_token and the
+ // refresh token. Writing the same claim into all three is a common accident:
+ // an id_token is for the client, an access token is for the API, and putting
+ // authorisation data in the id_token invites the client to make security
+ // decisions it has no business making.
+ if (OAuth2TokenType.ACCESS_TOKEN.equals(context.getTokenType())) {
+ context.getClaims().claim("tenant", "acme");
+
+ // client_credentials has no user: getPrincipal() is the client's own
+ // authentication, and asking it for roles yields nothing useful. Guard on
+ // the grant type or on whether a user is present, or a machine token
+ // silently inherits whatever authorities the client authentication carries.
+ if (context.getPrincipal() != null
+ && context.getAuthorizationGrantType() != null
+ && !"client_credentials".equals(
+ context.getAuthorizationGrantType().getValue())) {
+ Set roles = context.getPrincipal().getAuthorities().stream()
+ .map(GrantedAuthority::getAuthority)
+ .filter(a -> a.startsWith("ROLE_"))
+ .map(a -> a.substring("ROLE_".length()))
+ .collect(Collectors.toCollection(java.util.LinkedHashSet::new));
+ context.getClaims().claim("roles", roles);
+ }
+
+ // The audience is what stops a token minted for one API being replayed
+ // against another. Spring Authorization Server does not populate `aud` on
+ // access tokens by default - there is no per-client audience setting - so
+ // if your resource servers validate audience (they should), this line or
+ // something like it is mandatory.
+ context.getClaims().audience(List.of("orders-api"));
+ }
+
+ if (OidcParameterNames.ID_TOKEN.equals(context.getTokenType().getValue())) {
+ // Profile-ish claims for the relying party to render. Deliberately not
+ // roles: see above.
+ context.getClaims().claim("preferred_username",
+ context.getPrincipal().getName());
+ }
+ };
+ }
+}
diff --git a/authorization-server/auth-server/src/main/java/com/ankurm/authserver/web/ConsentController.java b/authorization-server/auth-server/src/main/java/com/ankurm/authserver/web/ConsentController.java
new file mode 100644
index 0000000..fb235a0
--- /dev/null
+++ b/authorization-server/auth-server/src/main/java/com/ankurm/authserver/web/ConsentController.java
@@ -0,0 +1,104 @@
+package com.ankurm.authserver.web;
+
+import jakarta.servlet.http.HttpServletRequest;
+import org.springframework.security.oauth2.core.endpoint.OAuth2ParameterNames;
+import org.springframework.security.oauth2.core.oidc.OidcScopes;
+import org.springframework.security.oauth2.server.authorization.OAuth2AuthorizationConsent;
+import org.springframework.security.oauth2.server.authorization.OAuth2AuthorizationConsentService;
+import org.springframework.security.oauth2.server.authorization.client.RegisteredClient;
+import org.springframework.security.oauth2.server.authorization.client.RegisteredClientRepository;
+import org.springframework.stereotype.Controller;
+import org.springframework.ui.Model;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+
+import java.security.Principal;
+import java.util.LinkedHashSet;
+import java.util.Set;
+
+/**
+ * The consent page.
+ *
+ *
Wiring a custom one is deceptively small: {@code .consentPage("/oauth2/consent")} on
+ * the authorization endpoint, plus a controller that renders a form. What the
+ * documentation does not spell out is the contract the form has to satisfy, and getting
+ * any part of it wrong produces a redirect loop rather than an error:
+ *
+ *
+ *
the form POSTs back to {@code /oauth2/authorize}, not to the consent path
+ *
it must echo {@code client_id} and {@code state} exactly as received
+ *
each approved scope goes back as a separate {@code scope} parameter
+ *
CSRF token included — this is the browser chain, not the protocol chain
+ *
{@code openid} is not shown as a checkbox: it is requested implicitly and
+ * the server does not require consent for it
+ *
+ *
+ *
Miss the {@code state} parameter and the authorization endpoint cannot correlate the
+ * approval with the pending request, so it starts a new one — which redirects to the
+ * consent page again. The loop looks like a session problem and is not.
+ *
+ * @see
+ * docs/authorization-server/04-consent-page.md
+ */
+@Controller
+public class ConsentController {
+
+ private final RegisteredClientRepository registeredClientRepository;
+ private final OAuth2AuthorizationConsentService authorizationConsentService;
+
+ public ConsentController(RegisteredClientRepository registeredClientRepository,
+ OAuth2AuthorizationConsentService authorizationConsentService) {
+ this.registeredClientRepository = registeredClientRepository;
+ this.authorizationConsentService = authorizationConsentService;
+ }
+
+ @GetMapping("/oauth2/consent")
+ public String consent(Principal principal, Model model,
+ @RequestParam(OAuth2ParameterNames.CLIENT_ID) String clientId,
+ @RequestParam(OAuth2ParameterNames.SCOPE) String scope,
+ @RequestParam(OAuth2ParameterNames.STATE) String state,
+ @RequestParam(name = "user_code", required = false) String userCode,
+ HttpServletRequest request) {
+
+ RegisteredClient registeredClient = this.registeredClientRepository.findByClientId(clientId);
+ if (registeredClient == null) {
+ throw new IllegalArgumentException("unknown client_id: " + clientId);
+ }
+
+ // Scopes the user has already approved in an earlier authorization are pre-ticked
+ // and, in the default flow, would not have brought us here at all - the consent
+ // page only appears for scopes not yet consented to.
+ OAuth2AuthorizationConsent currentConsent =
+ this.authorizationConsentService.findById(registeredClient.getId(), principal.getName());
+ Set alreadyApproved = currentConsent != null
+ ? currentConsent.getScopes()
+ : Set.of();
+
+ Set toApprove = new LinkedHashSet<>();
+ Set previouslyApproved = new LinkedHashSet<>();
+ for (String requested : scope.split(" ")) {
+ // openid is requested implicitly by every OIDC client and the authorization
+ // endpoint never asks for consent on it. Rendering it as a checkbox is
+ // harmless but misleading, and unticking it does nothing.
+ if (OidcScopes.OPENID.equals(requested)) {
+ continue;
+ }
+ if (alreadyApproved.contains(requested)) {
+ previouslyApproved.add(requested);
+ } else {
+ toApprove.add(requested);
+ }
+ }
+
+ model.addAttribute("clientId", clientId);
+ model.addAttribute("clientName", registeredClient.getClientName());
+ model.addAttribute("state", state);
+ model.addAttribute("scopes", toApprove);
+ model.addAttribute("previouslyApprovedScopes", previouslyApproved);
+ model.addAttribute("principalName", principal.getName());
+ model.addAttribute("userCode", userCode);
+ model.addAttribute("requestURI", "/oauth2/authorize");
+ return "consent";
+ }
+
+}
diff --git a/authorization-server/auth-server/src/main/resources/application-acceptall.yaml b/authorization-server/auth-server/src/main/resources/application-acceptall.yaml
new file mode 100644
index 0000000..bb1b362
--- /dev/null
+++ b/authorization-server/auth-server/src/main/resources/application-acceptall.yaml
@@ -0,0 +1,5 @@
+# The entry-point matcher is left as MediaTypeRequestMatcher(TEXT_HTML) with no ignored
+# types. `Accept: */*` then matches text/html and the token endpoint redirects API callers
+# to the HTML login page. See docs/authorization-server/09-entry-point.md.
+demo:
+ ignore-accept-all: false
diff --git a/authorization-server/auth-server/src/main/resources/application-noclaims.yaml b/authorization-server/auth-server/src/main/resources/application-noclaims.yaml
new file mode 100644
index 0000000..dc7c80e
--- /dev/null
+++ b/authorization-server/auth-server/src/main/resources/application-noclaims.yaml
@@ -0,0 +1,3 @@
+# The OAuth2TokenCustomizer bean is not registered (see TokenClaimsCustomizer's @Profile).
+# Diff a token from this profile against a default one to see exactly what the default
+# access token does and does not carry.
diff --git a/authorization-server/auth-server/src/main/resources/application-noconsent.yaml b/authorization-server/auth-server/src/main/resources/application-noconsent.yaml
new file mode 100644
index 0000000..773d5ad
--- /dev/null
+++ b/authorization-server/auth-server/src/main/resources/application-noconsent.yaml
@@ -0,0 +1,4 @@
+# Consent off. The authorization endpoint issues the code immediately after login.
+# Correct for a first-party client you own; wrong the moment a third party registers.
+demo:
+ require-consent: false
diff --git a/authorization-server/auth-server/src/main/resources/application-nopkce.yaml b/authorization-server/auth-server/src/main/resources/application-nopkce.yaml
new file mode 100644
index 0000000..8d5ae7f
--- /dev/null
+++ b/authorization-server/auth-server/src/main/resources/application-nopkce.yaml
@@ -0,0 +1,4 @@
+# The public client no longer requires a code_verifier. The code exchange then succeeds
+# with nothing but the authorization code - which is the whole attack PKCE prevents.
+demo:
+ require-pkce: false
diff --git a/authorization-server/auth-server/src/main/resources/application-opaque.yaml b/authorization-server/auth-server/src/main/resources/application-opaque.yaml
new file mode 100644
index 0000000..0c5959a
--- /dev/null
+++ b/authorization-server/auth-server/src/main/resources/application-opaque.yaml
@@ -0,0 +1,4 @@
+# demo-service gets REFERENCE (opaque) access tokens instead of self-contained JWTs.
+# The string is meaningless to a resource server without a call to /oauth2/introspect.
+demo:
+ service-token-format: reference
diff --git a/authorization-server/auth-server/src/main/resources/application-trace.yaml b/authorization-server/auth-server/src/main/resources/application-trace.yaml
new file mode 100644
index 0000000..5996e4c
--- /dev/null
+++ b/authorization-server/auth-server/src/main/resources/application-trace.yaml
@@ -0,0 +1,5 @@
+logging:
+ level:
+ org.springframework.security: TRACE
+ org.springframework.security.oauth2.server.authorization: TRACE
+ org.springframework.security.web.FilterChainProxy: DEBUG
diff --git a/authorization-server/auth-server/src/main/resources/application.yaml b/authorization-server/auth-server/src/main/resources/application.yaml
new file mode 100644
index 0000000..07cd408
--- /dev/null
+++ b/authorization-server/auth-server/src/main/resources/application.yaml
@@ -0,0 +1,19 @@
+server:
+ port: 9000
+
+spring:
+ application:
+ name: auth-server
+ thymeleaf:
+ cache: false
+
+# Flags the RegisteredClientRepository reads. Every variant profile below flips exactly
+# one of them, so the resulting failure is attributable to one line.
+demo:
+ require-consent: true
+ require-pkce: true
+ service-token-format: jwt
+
+logging:
+ level:
+ org.springframework.security: INFO
diff --git a/authorization-server/auth-server/src/main/resources/templates/consent.html b/authorization-server/auth-server/src/main/resources/templates/consent.html
new file mode 100644
index 0000000..90a06b7
--- /dev/null
+++ b/authorization-server/auth-server/src/main/resources/templates/consent.html
@@ -0,0 +1,71 @@
+
+
+
+
+ Approve access
+
+
+
+
+
Approve access
+
+ Signed in as user.
+ The application client wants to act on your behalf.
+
+
+
+
+
+
+
+
+
diff --git a/authorization-server/auth-server/src/test/java/com/ankurm/authserver/ProviderContractTests.java b/authorization-server/auth-server/src/test/java/com/ankurm/authserver/ProviderContractTests.java
new file mode 100644
index 0000000..4543e0a
--- /dev/null
+++ b/authorization-server/auth-server/src/test/java/com/ankurm/authserver/ProviderContractTests.java
@@ -0,0 +1,102 @@
+package com.ankurm.authserver;
+
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.boot.webmvc.test.autoconfigure.AutoConfigureMockMvc;
+import org.springframework.http.MediaType;
+import org.springframework.security.oauth2.server.authorization.client.RegisteredClient;
+import org.springframework.security.oauth2.server.authorization.client.RegisteredClientRepository;
+import org.springframework.test.web.servlet.MockMvc;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+/**
+ * Contract tests, not happy-path tests. Each one pins a decision that would otherwise be
+ * silently reversible by a config change.
+ */
+@SpringBootTest
+@AutoConfigureMockMvc
+class ProviderContractTests {
+
+ @Autowired MockMvc mvc;
+ @Autowired RegisteredClientRepository clients;
+
+ @Test
+ void discoveryAdvertisesTheConfiguredIssuer() throws Exception {
+ this.mvc.perform(get("/.well-known/openid-configuration"))
+ .andExpect(status().isOk())
+ .andExpect(jsonPath("$.issuer").value("http://localhost:9000"))
+ // Present only because .oidc(...) was switched on.
+ .andExpect(jsonPath("$.userinfo_endpoint").exists());
+ }
+
+ @Test
+ void jwkSetNeverExposesPrivateMaterial() throws Exception {
+ String body = this.mvc.perform(get("/oauth2/jwks"))
+ .andExpect(status().isOk())
+ .andReturn().getResponse().getContentAsString();
+ // "d" is the RSA private exponent. Its presence here would be a full compromise.
+ assertThat(body).doesNotContain("\"d\"").doesNotContain("\"p\"").doesNotContain("\"q\"");
+ }
+
+ @Test
+ void thePublicClientRequiresProofKey() {
+ RegisteredClient spa = this.clients.findByClientId("demo-spa");
+ assertThat(spa).isNotNull();
+ assertThat(spa.getClientSettings().isRequireProofKey())
+ .as("a public client without PKCE can have its authorization code replayed")
+ .isTrue();
+ }
+
+ @Test
+ void requireProofKeyIsOnByDefaultInSevenPointOne() {
+ // demo-service never touches ClientSettings. In Spring Authorization Server 1.5.8
+ // this was false; in 7.1.1 the default flipped to true, which silently makes PKCE
+ // mandatory for every client you did not think about. See
+ // docs/output/as-settings-defaults.txt.
+ RegisteredClient service = this.clients.findByClientId("demo-service");
+ assertThat(service.getClientSettings().isRequireProofKey()).isTrue();
+ }
+
+ @Test
+ void refreshTokensRotate() {
+ RegisteredClient web = this.clients.findByClientId("demo-web");
+ assertThat(web.getTokenSettings().isReuseRefreshTokens())
+ .as("reuse means a stolen refresh token stays valid until it expires")
+ .isFalse();
+ }
+
+ @Test
+ void aFailedTokenRequestFromAnApiClientIsNotAnHtmlRedirect() throws Exception {
+ // Accept: */* is what curl and most HTTP clients send. Without
+ // setIgnoredMediaTypes(ALL) on the entry-point matcher this is a 302 to /login.
+ this.mvc.perform(post("/oauth2/token")
+ .accept(MediaType.ALL)
+ .param("grant_type", "authorization_code")
+ .param("code", "bogus")
+ .param("client_id", "demo-spa"))
+ .andExpect(status().isUnauthorized());
+ }
+
+ @Test
+ void aBrowserStillGetsRedirectedToTheLoginPage() throws Exception {
+ this.mvc.perform(get("/oauth2/authorize")
+ .accept(MediaType.TEXT_HTML)
+ .queryParam("response_type", "code")
+ .queryParam("client_id", "demo-web")
+ .queryParam("redirect_uri", "http://127.0.0.1:8080/login/oauth2/code/demo-web")
+ .queryParam("scope", "openid")
+ // Required even for a confidential client, because requireProofKey
+ // now defaults to true. Omit it and the authorization endpoint
+ // redirects to the client with error=invalid_request rather than
+ // sending the browser to the login page.
+ .queryParam("code_challenge", "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM")
+ .queryParam("code_challenge_method", "S256"))
+ .andExpect(status().is3xxRedirection());
+ }
+}
diff --git a/authorization-server/oidc-client/pom.xml b/authorization-server/oidc-client/pom.xml
new file mode 100644
index 0000000..64ecde1
--- /dev/null
+++ b/authorization-server/oidc-client/pom.xml
@@ -0,0 +1,40 @@
+
+
+ 4.0.0
+
+
+ com.ankurm
+ authorization-server-demo
+ 1.0.0
+
+
+ oidc-client
+ oidc-client
+ A relying party that logs in against auth-server and calls resource-server
+
+
+
+ org.springframework.boot
+ spring-boot-starter-webmvc
+
+
+ org.springframework.boot
+ spring-boot-starter-security-oauth2-client
+
+
+ org.springframework.boot
+ spring-boot-starter-thymeleaf
+
+
+
+
+
+
+ org.springframework.boot
+ spring-boot-maven-plugin
+
+
+
+
diff --git a/authorization-server/oidc-client/src/main/java/com/ankurm/client/ClientApplication.java b/authorization-server/oidc-client/src/main/java/com/ankurm/client/ClientApplication.java
new file mode 100644
index 0000000..46dfcdf
--- /dev/null
+++ b/authorization-server/oidc-client/src/main/java/com/ankurm/client/ClientApplication.java
@@ -0,0 +1,17 @@
+package com.ankurm.client;
+
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+/**
+ * The relying party. Runs on :8080 and is the only piece a human touches.
+ *
+ * @see
+ * docs/authorization-server/08-client.md
+ */
+@SpringBootApplication
+public class ClientApplication {
+ public static void main(String[] args) {
+ SpringApplication.run(ClientApplication.class, args);
+ }
+}
diff --git a/authorization-server/oidc-client/src/main/java/com/ankurm/client/ClientSecurityConfig.java b/authorization-server/oidc-client/src/main/java/com/ankurm/client/ClientSecurityConfig.java
new file mode 100644
index 0000000..551010a
--- /dev/null
+++ b/authorization-server/oidc-client/src/main/java/com/ankurm/client/ClientSecurityConfig.java
@@ -0,0 +1,39 @@
+package com.ankurm.client;
+
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.security.config.Customizer;
+import org.springframework.security.config.annotation.web.builders.HttpSecurity;
+import org.springframework.security.web.SecurityFilterChain;
+
+/**
+ * The whole client side of OIDC, in one method.
+ *
+ *
{@code oauth2Login()} makes this an OIDC relying party: it adds the redirect
+ * endpoint at {@code /login/oauth2/code/{registrationId}}, exchanges the code, validates
+ * the {@code id_token}, and creates a session. {@code oauth2Client()} additionally makes
+ * the access token available to outgoing HTTP calls.
+ *
+ *
The redirect URI is derived from the registration id, and it must match what the
+ * provider has registered byte for byte. This app is reached at
+ * {@code 127.0.0.1:8080} rather than {@code localhost:8080} for a reason: they are
+ * different origins to a browser cookie jar, and running the client on {@code localhost}
+ * next to an authorization server on {@code localhost} means one session cookie can
+ * clobber the other. Using {@code 127.0.0.1} for the client keeps the two sessions
+ * separate, which is the difference between a working demo and a login loop.
+ */
+@Configuration(proxyBeanMethods = false)
+public class ClientSecurityConfig {
+
+ @Bean
+ public SecurityFilterChain chain(HttpSecurity http) throws Exception {
+ http
+ .authorizeHttpRequests(auth -> auth
+ .requestMatchers("/", "/error").permitAll()
+ .anyRequest().authenticated())
+ .oauth2Login(Customizer.withDefaults())
+ .oauth2Client(Customizer.withDefaults())
+ .logout(logout -> logout.logoutSuccessUrl("/"));
+ return http.build();
+ }
+}
diff --git a/authorization-server/oidc-client/src/main/java/com/ankurm/client/HomeController.java b/authorization-server/oidc-client/src/main/java/com/ankurm/client/HomeController.java
new file mode 100644
index 0000000..b3f11c5
--- /dev/null
+++ b/authorization-server/oidc-client/src/main/java/com/ankurm/client/HomeController.java
@@ -0,0 +1,56 @@
+package com.ankurm.client;
+
+import org.springframework.security.core.annotation.AuthenticationPrincipal;
+import org.springframework.security.oauth2.client.OAuth2AuthorizedClient;
+import org.springframework.security.oauth2.client.annotation.RegisteredOAuth2AuthorizedClient;
+import org.springframework.security.oauth2.core.oidc.user.OidcUser;
+import org.springframework.stereotype.Controller;
+import org.springframework.ui.Model;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.client.RestClient;
+
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+/**
+ * Renders what the client received, and calls the resource server with it.
+ *
+ *
{@code @RegisteredOAuth2AuthorizedClient} hands you the access token Spring already
+ * holds for this user and this registration. Reading it out of the {@code OidcUser} would
+ * give you the id_token instead - a mistake that produces a 401 from the resource
+ * server with a token that looks perfectly valid, because it is: it is just the wrong one.
+ */
+@Controller
+public class HomeController {
+
+ private final RestClient restClient = RestClient.create();
+
+ @GetMapping("/")
+ public String home(@AuthenticationPrincipal OidcUser user, Model model) {
+ model.addAttribute("user", user);
+ if (user != null) {
+ model.addAttribute("idTokenClaims", user.getIdToken().getClaims());
+ }
+ return "home";
+ }
+
+ @GetMapping("/orders")
+ public String orders(@RegisteredOAuth2AuthorizedClient("demo-web") OAuth2AuthorizedClient client,
+ Model model) {
+ String token = client.getAccessToken().getTokenValue();
+ Map body;
+ try {
+ body = this.restClient.get()
+ .uri("http://localhost:8090/api/orders")
+ .header("Authorization", "Bearer " + token)
+ .retrieve()
+ .body(Map.class);
+ } catch (Exception ex) {
+ body = new LinkedHashMap<>(Map.of("error", String.valueOf(ex.getMessage())));
+ }
+ model.addAttribute("accessToken", token);
+ model.addAttribute("scopes", client.getAccessToken().getScopes());
+ model.addAttribute("orders", body);
+ return "orders";
+ }
+}
diff --git a/authorization-server/oidc-client/src/main/java/com/ankurm/client/PkceConfig.java b/authorization-server/oidc-client/src/main/java/com/ankurm/client/PkceConfig.java
new file mode 100644
index 0000000..d47244d
--- /dev/null
+++ b/authorization-server/oidc-client/src/main/java/com/ankurm/client/PkceConfig.java
@@ -0,0 +1,82 @@
+package com.ankurm.client;
+
+import org.springframework.beans.BeansException;
+import org.springframework.beans.factory.config.BeanPostProcessor;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.context.annotation.Profile;
+import org.springframework.security.oauth2.client.registration.ClientRegistration;
+import org.springframework.security.oauth2.client.registration.ClientRegistrationRepository;
+import org.springframework.security.oauth2.client.registration.InMemoryClientRegistrationRepository;
+
+/**
+ * Reproduces the pre-7.0 client, so the mismatch can be observed rather than described.
+ *
+ *
What changed, on both sides at once
+ *
+ * Read out of the jars with {@code javap} — see
+ * {@code docs/output/as-settings-defaults.txt}:
+ *
+ *
+ *
previous
current
+ *
Authorization server — {@code ClientSettings.requireProofKey}
Because both moved together, Spring-client-to-Spring-server keeps working. The
+ * combination that breaks is a 7.1 authorization server with anything older or
+ * anything hand-rolled in front of it: a Spring Security 6.x confidential client, a
+ * bespoke server-side integration, a Postman collection someone saved last year. The
+ * server rejects the authorization request before login, and the user sees the client's
+ * error page rather than the provider's:
+ *
+ *
Activating the {@code nopkce} profile rebuilds this client's registration with
+ * {@code requireProofKey(false)}, which is exactly what a 6.x client would have sent.
+ *
+ * @see
+ * docs/authorization-server/08-client.md
+ */
+@Configuration(proxyBeanMethods = false)
+@Profile("nopkce")
+public class PkceConfig {
+
+ /**
+ * Note that {@code DefaultOAuth2AuthorizationRequestResolver} consults
+ * {@code ClientRegistration}'s own {@code ClientSettings}, not the resolver's
+ * customizer — so setting a customizer cannot turn PKCE off. It has to be
+ * turned off on the registration itself.
+ *
+ *
A {@code @Bean} that takes {@code ClientRegistrationRepository} and returns one
+ * is a dependency cycle, and Boot refuses to start
+ * ({@code Relying upon circular references is discouraged and they are prohibited by
+ * default}). Post-processing the bean Boot already built avoids that.
+ */
+ @Bean
+ static BeanPostProcessor downgradeToPreSevenClient() {
+ return new BeanPostProcessor() {
+ @Override
+ public Object postProcessAfterInitialization(Object bean, String name)
+ throws BeansException {
+ if (!(bean instanceof ClientRegistrationRepository repo)) {
+ return bean;
+ }
+ ClientRegistration original = repo.findByRegistrationId("demo-web");
+ if (original == null) {
+ return bean;
+ }
+ return new InMemoryClientRegistrationRepository(
+ ClientRegistration.withClientRegistration(original)
+ .clientSettings(ClientRegistration.ClientSettings.builder()
+ .requireProofKey(false)
+ .build())
+ .build());
+ }
+ };
+ }
+}
diff --git a/authorization-server/oidc-client/src/main/resources/application-nopkce.yaml b/authorization-server/oidc-client/src/main/resources/application-nopkce.yaml
new file mode 100644
index 0000000..f2d7fd1
--- /dev/null
+++ b/authorization-server/oidc-client/src/main/resources/application-nopkce.yaml
@@ -0,0 +1,3 @@
+# PkceConfig is @Profile("nopkce"): it rebuilds the demo-web registration with
+# requireProofKey(false), reproducing what a Spring Security 6.x confidential client
+# sends. See docs/authorization-server/08-client.md.
diff --git a/authorization-server/oidc-client/src/main/resources/application.yaml b/authorization-server/oidc-client/src/main/resources/application.yaml
new file mode 100644
index 0000000..1c02c44
--- /dev/null
+++ b/authorization-server/oidc-client/src/main/resources/application.yaml
@@ -0,0 +1,27 @@
+server:
+ port: 8080
+
+spring:
+ application:
+ name: oidc-client
+ thymeleaf:
+ cache: false
+ security:
+ oauth2:
+ client:
+ # One provider entry. Spring reads
+ # http://localhost:9000/.well-known/openid-configuration at first use and fills in
+ # every endpoint from it - authorization, token, jwks, userinfo, issuer.
+ provider:
+ demo-provider:
+ issuer-uri: http://localhost:9000
+ registration:
+ demo-web:
+ provider: demo-provider
+ client-id: demo-web
+ client-secret: web-secret
+ authorization-grant-type: authorization_code
+ client-authentication-method: client_secret_basic
+ # Must equal the redirect-uri registered on the server, exactly.
+ redirect-uri: "http://127.0.0.1:8080/login/oauth2/code/demo-web"
+ scope: openid,profile,orders.read,orders.write
diff --git a/authorization-server/oidc-client/src/main/resources/templates/home.html b/authorization-server/oidc-client/src/main/resources/templates/home.html
new file mode 100644
index 0000000..95c2784
--- /dev/null
+++ b/authorization-server/oidc-client/src/main/resources/templates/home.html
@@ -0,0 +1,18 @@
+
+
+
OIDC client
+
+
+
Relying party
+
+
Not signed in.
+
Go to /orders — this triggers the authorization code flow.
+
diff --git a/authorization-server/pom.xml b/authorization-server/pom.xml
new file mode 100644
index 0000000..afea21a
--- /dev/null
+++ b/authorization-server/pom.xml
@@ -0,0 +1,44 @@
+
+
+ 4.0.0
+
+
+ org.springframework.boot
+ spring-boot-starter-parent
+ 4.1.1
+
+
+
+ com.ankurm
+ authorization-server-demo
+ 1.0.0
+ pom
+ authorization-server-demo
+ Spring Authorization Server 7.1 on Spring Boot 4.1 - runnable companion for ankurm.com
+
+
+
+ auth-server
+ resource-server
+ oidc-client
+
+
+
+ 25
+ UTF-8
+
+
diff --git a/authorization-server/resource-server/pom.xml b/authorization-server/resource-server/pom.xml
new file mode 100644
index 0000000..1e8832d
--- /dev/null
+++ b/authorization-server/resource-server/pom.xml
@@ -0,0 +1,39 @@
+
+
+ 4.0.0
+
+
+ com.ankurm
+ authorization-server-demo
+ 1.0.0
+
+
+ resource-server
+ resource-server
+ An API that trusts tokens minted by auth-server
+
+
+
+ org.springframework.boot
+ spring-boot-starter-webmvc
+
+
+
+ org.springframework.boot
+ spring-boot-starter-security-oauth2-resource-server
+
+
+
+
+
+
+ org.springframework.boot
+ spring-boot-maven-plugin
+
+
+
+
diff --git a/authorization-server/resource-server/src/main/java/com/ankurm/rs/ApiController.java b/authorization-server/resource-server/src/main/java/com/ankurm/rs/ApiController.java
new file mode 100644
index 0000000..bc00f6d
--- /dev/null
+++ b/authorization-server/resource-server/src/main/java/com/ankurm/rs/ApiController.java
@@ -0,0 +1,63 @@
+package com.ankurm.rs;
+
+import org.springframework.security.core.annotation.AuthenticationPrincipal;
+import org.springframework.security.core.context.SecurityContextHolder;
+import org.springframework.security.oauth2.jwt.Jwt;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+/** Four endpoints, each guarded by a different consequence of the token's contents. */
+@RestController
+public class ApiController {
+
+ @GetMapping("/public")
+ public Map open() {
+ return Map.of("message", "no token required");
+ }
+
+ /** Requires SCOPE_orders.read. */
+ @GetMapping("/api/orders")
+ public Map orders(@AuthenticationPrincipal Jwt jwt) {
+ Map out = new LinkedHashMap<>();
+ out.put("orders", List.of(Map.of("id", 1, "total", "42.00")));
+ out.put("subject", jwt.getSubject());
+ out.put("clientId", jwt.getClaimAsString("azp") != null
+ ? jwt.getClaimAsString("azp") : jwt.getClaimAsString("client_id"));
+ out.put("scopes", jwt.getClaimAsStringList("scope"));
+ out.put("roles", jwt.getClaimAsStringList("roles"));
+ out.put("tenant", jwt.getClaimAsString("tenant"));
+ out.put("audience", jwt.getAudience());
+ return out;
+ }
+
+ /** Requires SCOPE_orders.write. */
+ @PostMapping("/api/orders")
+ public Map create(@AuthenticationPrincipal Jwt jwt) {
+ return Map.of("created", true, "by", jwt.getSubject());
+ }
+
+ /** Requires ROLE_ADMIN, which only exists because of the provider's token customiser. */
+ @GetMapping("/api/admin")
+ public Map admin() {
+ return Map.of(
+ "message", "admin only",
+ "authorities", SecurityContextHolder.getContext().getAuthentication()
+ .getAuthorities().stream().map(Object::toString).toList());
+ }
+
+ /** Whatever the resource server actually decoded. Useful when a 403 makes no sense. */
+ @GetMapping("/whoami")
+ public Map whoami(@AuthenticationPrincipal Jwt jwt) {
+ Map out = new LinkedHashMap<>();
+ out.put("claims", jwt.getClaims());
+ out.put("headers", jwt.getHeaders());
+ out.put("authorities", SecurityContextHolder.getContext().getAuthentication()
+ .getAuthorities().stream().map(Object::toString).toList());
+ return out;
+ }
+}
diff --git a/authorization-server/resource-server/src/main/java/com/ankurm/rs/ResourceServerApplication.java b/authorization-server/resource-server/src/main/java/com/ankurm/rs/ResourceServerApplication.java
new file mode 100644
index 0000000..b741c3d
--- /dev/null
+++ b/authorization-server/resource-server/src/main/java/com/ankurm/rs/ResourceServerApplication.java
@@ -0,0 +1,17 @@
+package com.ankurm.rs;
+
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+/**
+ * The API that trusts what the provider mints. Runs on :8090.
+ *
+ * @see
+ * docs/authorization-server/06-resource-server.md
+ */
+@SpringBootApplication
+public class ResourceServerApplication {
+ public static void main(String[] args) {
+ SpringApplication.run(ResourceServerApplication.class, args);
+ }
+}
diff --git a/authorization-server/resource-server/src/main/java/com/ankurm/rs/SecurityConfig.java b/authorization-server/resource-server/src/main/java/com/ankurm/rs/SecurityConfig.java
new file mode 100644
index 0000000..fa43698
--- /dev/null
+++ b/authorization-server/resource-server/src/main/java/com/ankurm/rs/SecurityConfig.java
@@ -0,0 +1,119 @@
+package com.ankurm.rs;
+
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.security.config.Customizer;
+import org.springframework.security.config.annotation.web.builders.HttpSecurity;
+import org.springframework.security.oauth2.core.OAuth2TokenValidator;
+import org.springframework.security.oauth2.jwt.Jwt;
+import org.springframework.security.oauth2.jwt.JwtClaimNames;
+import org.springframework.security.oauth2.jwt.JwtDecoder;
+import org.springframework.security.oauth2.jwt.JwtDecoders;
+import org.springframework.security.oauth2.jwt.JwtValidators;
+import org.springframework.security.oauth2.jwt.NimbusJwtDecoder;
+import org.springframework.security.oauth2.core.OAuth2Error;
+import org.springframework.security.oauth2.core.OAuth2TokenValidatorResult;
+import org.springframework.security.oauth2.server.resource.authentication.JwtAuthenticationConverter;
+import org.springframework.security.oauth2.server.resource.authentication.JwtGrantedAuthoritiesConverter;
+import org.springframework.security.web.SecurityFilterChain;
+
+import java.util.List;
+
+/**
+ * What a resource server has to do with the provider's tokens, and what it gets for free.
+ *
+ *
{@code spring.security.oauth2.resourceserver.jwt.issuer-uri} alone gives you
+ * signature verification, {@code exp}/{@code nbf}, and an {@code iss} check. It does
+ * not give you an audience check, and it does not map {@code scope} to anything
+ * other than {@code SCOPE_*} authorities. Both of those gaps are filled here.
+ *
+ * @see
+ * docs/authorization-server/06-resource-server.md
+ */
+@Configuration(proxyBeanMethods = false)
+public class SecurityConfig {
+
+ @Bean
+ public SecurityFilterChain api(HttpSecurity http) throws Exception {
+ http
+ .authorizeHttpRequests(auth -> auth
+ .requestMatchers("/public").permitAll()
+ // SCOPE_ is the prefix JwtGrantedAuthoritiesConverter uses for the
+ // `scope` (or `scp`) claim. ROLE_ comes from our own mapping below.
+ .requestMatchers("/api/orders").hasAuthority("SCOPE_orders.read")
+ .requestMatchers("/api/orders/**").hasAuthority("SCOPE_orders.write")
+ .requestMatchers("/api/admin").hasRole("ADMIN")
+ .anyRequest().authenticated())
+ .oauth2ResourceServer(oauth2 -> oauth2.jwt(Customizer.withDefaults()))
+ // No sessions, no CSRF - the token is the entire request context. Leaving CSRF
+ // on for a bearer-token API produces a 403 on every POST with no useful body,
+ // which is the single most-reported false alarm in this space.
+ .csrf(csrf -> csrf.disable())
+ .sessionManagement(s -> s.sessionCreationPolicy(
+ org.springframework.security.config.http.SessionCreationPolicy.STATELESS));
+ return http.build();
+ }
+
+ /**
+ * Built explicitly rather than left to auto-configuration, purely so the audience
+ * validator can be added. {@code JwtValidators.createDefaultWithIssuer} is the same
+ * stack Boot would have installed: timestamp + issuer.
+ */
+ @Bean
+ public JwtDecoder jwtDecoder(
+ @Value("${spring.security.oauth2.resourceserver.jwt.issuer-uri}") String issuer,
+ @Value("${demo.required-audience:orders-api}") String audience,
+ @Value("${demo.validate-audience:true}") boolean validateAudience) {
+
+ NimbusJwtDecoder decoder = (NimbusJwtDecoder) JwtDecoders.fromIssuerLocation(issuer);
+
+ OAuth2TokenValidator withIssuer = JwtValidators.createDefaultWithIssuer(issuer);
+ if (!validateAudience) {
+ decoder.setJwtValidator(withIssuer);
+ return decoder;
+ }
+
+ OAuth2TokenValidator audienceValidator = jwt -> {
+ List aud = jwt.getClaimAsStringList(JwtClaimNames.AUD);
+ if (aud != null && aud.contains(audience)) {
+ return OAuth2TokenValidatorResult.success();
+ }
+ // The error code matters: `invalid_token` is what puts the reason into the
+ // WWW-Authenticate header, which is the only place a client will see it.
+ return OAuth2TokenValidatorResult.failure(new OAuth2Error(
+ "invalid_token",
+ "the required audience " + audience + " is missing",
+ "https://tools.ietf.org/html/rfc6750#section-3.1"));
+ };
+
+ decoder.setJwtValidator(new org.springframework.security.oauth2.core.DelegatingOAuth2TokenValidator<>(
+ withIssuer, audienceValidator));
+ return decoder;
+ }
+
+ /**
+ * Maps the custom {@code roles} claim the provider's token customiser writes onto
+ * {@code ROLE_*} authorities, while keeping the default {@code SCOPE_*} mapping.
+ * Returning a converter that only handles {@code roles} silently deletes every
+ * scope authority, which turns {@code hasAuthority("SCOPE_orders.read")} into a 403
+ * on a perfectly valid token.
+ */
+ @Bean
+ public JwtAuthenticationConverter jwtAuthenticationConverter() {
+ JwtGrantedAuthoritiesConverter scopes = new JwtGrantedAuthoritiesConverter();
+
+ JwtAuthenticationConverter converter = new JwtAuthenticationConverter();
+ converter.setJwtGrantedAuthoritiesConverter(jwt -> {
+ var authorities = new java.util.ArrayList(
+ scopes.convert(jwt));
+ List roles = jwt.getClaimAsStringList("roles");
+ if (roles != null) {
+ roles.forEach(r -> authorities.add(
+ new org.springframework.security.core.authority.SimpleGrantedAuthority("ROLE_" + r)));
+ }
+ return authorities;
+ });
+ return converter;
+ }
+}
diff --git a/authorization-server/resource-server/src/main/resources/application-noaud.yaml b/authorization-server/resource-server/src/main/resources/application-noaud.yaml
new file mode 100644
index 0000000..8d3d818
--- /dev/null
+++ b/authorization-server/resource-server/src/main/resources/application-noaud.yaml
@@ -0,0 +1,4 @@
+# Audience validation off - the default Boot behaviour. A token minted for a different
+# API but signed by the same issuer is now accepted here.
+demo:
+ validate-audience: false
diff --git a/authorization-server/resource-server/src/main/resources/application.yaml b/authorization-server/resource-server/src/main/resources/application.yaml
new file mode 100644
index 0000000..05879e6
--- /dev/null
+++ b/authorization-server/resource-server/src/main/resources/application.yaml
@@ -0,0 +1,18 @@
+server:
+ port: 8090
+
+spring:
+ application:
+ name: resource-server
+ security:
+ oauth2:
+ resourceserver:
+ jwt:
+ # One property. From it Spring fetches /.well-known/openid-configuration at
+ # startup, reads jwks_uri out of it, and builds a decoder. If the auth server
+ # is not up when this one starts, startup fails - by design.
+ issuer-uri: http://localhost:9000
+
+demo:
+ required-audience: orders-api
+ validate-audience: true
diff --git a/authorization-server/scripts/audience.sh b/authorization-server/scripts/audience.sh
new file mode 100755
index 0000000..d0b197a
--- /dev/null
+++ b/authorization-server/scripts/audience.sh
@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# The gap between "the signature is valid" and "this token was meant for me".
+set -u
+cd "$(dirname "$0")/.."
+. scripts/lib.sh
+OUT=../docs/output/as-audience.txt
+mkdir -p ../docs/output
+{
+ section "A token for a DIFFERENT audience, signed by the SAME issuer"
+ echo "demo-service's tokens carry aud=[orders-api] thanks to the token customiser."
+ echo "Here we ask for one and then present it to a resource server configured to"
+ echo "require a different audience - and to one that does not check at all."
+ TOKEN=$(curl -s -u demo-service:service-secret -d grant_type=client_credentials \
+ -d scope=orders.read "$AS/oauth2/token" \
+ | python3 -c 'import sys,json;print(json.load(sys.stdin).get("access_token",""))')
+ echo
+ echo "aud claim in the token:"
+ jwt_payload "$TOKEN" | grep -A3 '"aud"'
+
+ section "Resource server running with demo.validate-audience=false"
+ echo "This is the Spring Boot default: issuer-uri alone validates signature, exp/nbf"
+ echo "and iss. Audience is not checked unless you add a validator."
+ curl -s -o /tmp/b -w 'GET /api/orders -> %{http_code}\n' -H "Authorization: Bearer $TOKEN" "$RS/api/orders"
+ head -c 300 /tmp/b; echo
+
+ section "The same token with a deliberately mangled signature"
+ BAD="${TOKEN%?}X"
+ curl -s -D - -o /dev/null -H "Authorization: Bearer $BAD" "$RS/api/orders" \
+ | sed -n '1p;/^WWW-Authenticate/p'
+
+ section "No token at all"
+ curl -s -D - -o /dev/null "$RS/api/orders" | sed -n '1p;/^WWW-Authenticate/p'
+} > "$OUT" 2>&1
+sed -i 's/[[:space:]]*$//' "$OUT"
+echo "wrote $OUT"
diff --git a/authorization-server/scripts/authcode-pkce.sh b/authorization-server/scripts/authcode-pkce.sh
new file mode 100755
index 0000000..d9ed3d4
--- /dev/null
+++ b/authorization-server/scripts/authcode-pkce.sh
@@ -0,0 +1,256 @@
+#!/usr/bin/env bash
+# The full authorization code flow with PKCE, driven entirely by curl so that every
+# redirect, form and parameter is visible. A browser hides all of this.
+#
+# ./scripts/authcode-pkce.sh [output-name] [client]
+#
+# client defaults to demo-spa (public, PKCE required). Pass demo-web for the confidential
+# client with a secret.
+set -u
+cd "$(dirname "$0")/.."
+. scripts/lib.sh
+
+NAME="${1:-as-authcode-pkce}"
+CLIENT="${2:-demo-spa}"
+# NO_CHALLENGE=1 sends an authorization request with no code_challenge at all. That is a
+# different thing from sending one and then omitting the verifier: the server only demands
+# a verifier if the authorization request carried a challenge, OR if the client is
+# registered with requireProofKey(true).
+NO_CHALLENGE="${NO_CHALLENGE:-0}"
+OUT="../docs/output/${NAME}.txt"
+mkdir -p ../docs/output
+
+if [ "$CLIENT" = "demo-web" ]; then
+ REDIRECT="http://127.0.0.1:8080/login/oauth2/code/demo-web"
+ SCOPE="openid orders.read orders.write"
+else
+ REDIRECT="http://127.0.0.1:8080/authorized"
+ SCOPE="openid orders.read"
+fi
+
+JAR=$(mktemp)
+trap 'rm -f "$JAR" /tmp/as-page.html' EXIT
+
+# --- PKCE parameters. RFC 7636: verifier is 43-128 chars of unreserved characters,
+# --- challenge is BASE64URL(SHA256(verifier)) with the padding stripped.
+read -r VERIFIER CHALLENGE <<<"$(python3 - <<'PY'
+import base64, hashlib, secrets
+v = base64.urlsafe_b64encode(secrets.token_bytes(48)).decode().rstrip('=')
+c = base64.urlsafe_b64encode(hashlib.sha256(v.encode()).digest()).decode().rstrip('=')
+print(v, c)
+PY
+)"
+
+{
+ section "PKCE parameters (RFC 7636)"
+ echo "code_verifier ${VERIFIER} (${#VERIFIER} chars)"
+ echo "code_challenge ${CHALLENGE}"
+ echo "code_challenge_method S256"
+ echo
+ echo "The verifier never leaves the client until the token request. The challenge is"
+ echo "all the authorization request carries, and it is a one-way hash of the verifier."
+
+ section "1. Log in to the authorization server (browser session)"
+ # The login page carries a CSRF token; the form chain has CSRF enabled, as it should.
+ curl -s -c "$JAR" "$AS/login" -o /tmp/as-page.html
+ CSRF=$(form_value /tmp/as-page.html _csrf)
+ echo "\$ curl -c jar -d username=alice -d password=password -d _csrf= $AS/login"
+ curl -s -i -b "$JAR" -c "$JAR" \
+ -d "username=alice" -d "password=password" -d "_csrf=$CSRF" \
+ "$AS/login" | sed -n '1p;/^[Ll]ocation:/p'
+
+ section "2. GET /oauth2/authorize (client=$CLIENT)"
+ PKCE_PARAMS="&code_challenge=$CHALLENGE&code_challenge_method=S256"
+ if [ "$NO_CHALLENGE" = "1" ]; then
+ PKCE_PARAMS=""
+ echo "NO_CHALLENGE=1: the authorization request carries no code_challenge."
+ echo
+ fi
+ AUTHZ="$AS/oauth2/authorize?response_type=code&client_id=$CLIENT&redirect_uri=$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$REDIRECT")&scope=$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1]))" "$SCOPE")&state=xyz123${PKCE_PARAMS}"
+ echo "\$ curl -b jar '$AUTHZ'"
+ LOC=$(curl -s -i -b "$JAR" -c "$JAR" "$AUTHZ" | tr -d '\r' | grep -i '^location:' | head -1 | sed 's/^[Ll]ocation: *//')
+ echo "-> 302 $LOC"
+
+ if [ -z "$LOC" ]; then
+ echo "no redirect - the authorization endpoint rendered a page instead:"
+ curl -s -b "$JAR" "$AUTHZ" | head -30
+ exit 1
+ fi
+
+ case "$LOC" in
+ */oauth2/consent*)
+ section "3. The consent page"
+ echo "The authorization endpoint redirected to OUR page, at the path given to"
+ echo ".consentPage(\"/oauth2/consent\"). Note the query string it hands over:"
+ echo "$LOC" | tr '&' '\n' | sed 's/^/ /'
+ curl -s -b "$JAR" -c "$JAR" "$AS${LOC#*9000}" -o /tmp/as-page.html
+ echo
+ echo "Scopes rendered as checkboxes (openid deliberately not among them):"
+ form_values /tmp/as-page.html scope | sed 's/^/ /'
+ CSRF=$(form_value /tmp/as-page.html _csrf)
+ STATE=$(form_value /tmp/as-page.html state)
+ echo
+ echo "The hidden state the form must echo back: $STATE"
+ echo "(this is NOT the client's state=xyz123 - it is the server's own correlation"
+ echo " handle for the pending authorization request, and sending the client's value"
+ echo " instead is what produces the consent redirect loop)"
+
+ section "4. POST the approval to /oauth2/authorize"
+ ARGS=(-d "client_id=$CLIENT" -d "state=$STATE" -d "_csrf=$CSRF")
+ for s in $(form_values /tmp/as-page.html scope); do
+ ARGS+=(-d "scope=$s")
+ done
+ echo "\$ curl -b jar -X POST ${ARGS[*]} $AS/oauth2/authorize"
+ LOC=$(curl -s -i -b "$JAR" -c "$JAR" "${ARGS[@]}" "$AS/oauth2/authorize" \
+ | tr -d '\r' | grep -i '^location:' | head -1 | sed 's/^[Ll]ocation: *//')
+ echo "-> 302 $LOC"
+ ;;
+ *)
+ section "3. No consent page"
+ echo "The authorization endpoint went straight back to the client. Either consent is"
+ echo "off for this client, or every requested scope was already approved."
+ ;;
+ esac
+
+ CODE=$(echo "$LOC" | sed -n 's/.*[?&]code=\([^&]*\).*/\1/p')
+ RETURNED_STATE=$(echo "$LOC" | sed -n 's/.*[?&]state=\([^&]*\).*/\1/p')
+ section "5. The authorization code"
+ echo "code = $CODE"
+ echo "state = $RETURNED_STATE (the client's own value, returned untouched - compare it)"
+ if [ -z "$CODE" ]; then
+ echo "no code in the redirect. The error was:"
+ echo "$LOC" | tr '&' '\n' | sed 's/^/ /'
+ exit 1
+ fi
+
+ section "6a. Exchange the code WITHOUT the verifier"
+ echo "This is the request an attacker who stole the code can make."
+ AUTH_ARGS=()
+ [ "$CLIENT" = "demo-web" ] && AUTH_ARGS=(-u demo-web:web-secret)
+ NOVERIFIER=$(curl -s -w '\n<>' "${AUTH_ARGS[@]}" \
+ -d grant_type=authorization_code -d "code=$CODE" \
+ -d "redirect_uri=$REDIRECT" -d "client_id=$CLIENT" \
+ "$AS/oauth2/token")
+ echo "$NOVERIFIER" | sed -n 's/^<>$/HTTP \1/p'
+ BODY=${NOVERIFIER%%$'\n'</dev/null || echo "$BODY"
+ else
+ echo "(empty response body)"
+ fi
+ echo
+ case "$NOVERIFIER" in
+ *access_token*)
+ echo ">>> A TOKEN WAS ISSUED. The code alone was sufficient. This is what"
+ echo ">>> requireProofKey(false) on a public client means in practice."
+ ;;
+ *)
+ echo ">>> Rejected. invalid_grant is deliberately vague: the server will not tell"
+ echo ">>> a caller whether the code was wrong, expired, already used, or missing a"
+ echo ">>> verifier, because each of those is information an attacker can use."
+ ;;
+ esac
+ echo "Note: this consumed the code. Authorization codes are single-use, so the"
+ echo "successful exchange below needs a fresh one."
+
+ section "6b. A fresh code, exchanged properly"
+ LOC=$(curl -s -i -b "$JAR" -c "$JAR" "$AUTHZ" | tr -d '\r' | grep -i '^location:' | head -1 | sed 's/^[Ll]ocation: *//')
+ case "$LOC" in
+ */oauth2/consent*)
+ curl -s -b "$JAR" -c "$JAR" "$AS${LOC#*9000}" -o /tmp/as-page.html
+ CSRF=$(form_value /tmp/as-page.html _csrf)
+ STATE=$(form_value /tmp/as-page.html state)
+ ARGS=(-d "client_id=$CLIENT" -d "state=$STATE" -d "_csrf=$CSRF")
+ for s in $(form_values /tmp/as-page.html scope); do
+ ARGS+=(-d "scope=$s")
+ done
+ LOC=$(curl -s -i -b "$JAR" -c "$JAR" "${ARGS[@]}" "$AS/oauth2/authorize" \
+ | tr -d '\r' | grep -i '^location:' | head -1 | sed 's/^[Ll]ocation: *//')
+ ;;
+ esac
+ CODE=$(echo "$LOC" | sed -n 's/.*[?&]code=\([^&]*\).*/\1/p')
+ echo "fresh code = $CODE"
+ echo
+ if [ "$NO_CHALLENGE" = "1" ]; then
+ echo "\$ curl -d grant_type=authorization_code -d code=... $AS/oauth2/token"
+ echo " (no code_verifier - there was no challenge to verify against)"
+ else
+ echo "\$ curl -d grant_type=authorization_code -d code=... -d code_verifier=... $AS/oauth2/token"
+ fi
+ VERIFIER_ARG=(-d "code_verifier=$VERIFIER")
+ [ "$NO_CHALLENGE" = "1" ] && VERIFIER_ARG=()
+ HTTPCODE=$(curl -s -o /tmp/as-tok.json -w '%{http_code}' "${AUTH_ARGS[@]}" \
+ -d grant_type=authorization_code -d "code=$CODE" \
+ -d "redirect_uri=$REDIRECT" -d "client_id=$CLIENT" \
+ "${VERIFIER_ARG[@]}" \
+ "$AS/oauth2/token")
+ RESP=$(cat /tmp/as-tok.json)
+ echo "HTTP $HTTPCODE"
+ if [ -s /tmp/as-tok.json ]; then
+ python3 -m json.tool < /tmp/as-tok.json 2>/dev/null || cat /tmp/as-tok.json
+ else
+ echo "(empty response body)"
+ fi
+ if [ "$HTTPCODE" != "200" ] && [ "$NO_CHALLENGE" = "1" ]; then
+ echo
+ echo ">>> No token, even though the client is registered with requireProofKey(false)"
+ echo ">>> and the authorization request carried no challenge. The reason is that a"
+ echo ">>> public client has no other way to authenticate at the token endpoint:"
+ echo ">>> PublicClientAuthenticationProvider delegates entirely to"
+ echo ">>> CodeVerifierAuthenticator, and raises invalid_client when there is nothing"
+ echo ">>> to verify. requireProofKey(false) relaxes the AUTHORIZATION endpoint only."
+ fi
+
+ read_claim() { python3 -c 'import sys,json
+try: print(json.load(sys.stdin).get(sys.argv[1],""))
+except Exception: print("")' "$1" < /tmp/as-tok.json; }
+ AT=$(read_claim access_token)
+ IDT=$(read_claim id_token)
+ RT=$(read_claim refresh_token)
+
+ if [ -n "$AT" ]; then
+ section "7. The access token"
+ jwt_header "$AT"
+ jwt_payload "$AT"
+ fi
+ if [ -n "$IDT" ]; then
+ section "8. The id_token - a different token, for a different audience"
+ jwt_payload "$IDT"
+ echo
+ echo "aud is the CLIENT here, not the API. Sending this to a resource server is the"
+ echo "classic mix-up: it verifies (same issuer, same key) and then fails the audience"
+ echo "check, or worse, passes it if nobody checks audience."
+ fi
+
+ if [ -n "$AT" ]; then
+ section "9. Calling the resource server"
+ for path in /api/orders /api/admin; do
+ CODE_HTTP=$(curl -s -o /tmp/rsbody -w '%{http_code}' -H "Authorization: Bearer $AT" "$RS$path")
+ echo "GET $path -> $CODE_HTTP"
+ head -c 500 /tmp/rsbody; echo
+ done
+
+ section "10. Sending the id_token instead"
+ if [ -n "$IDT" ]; then
+ curl -s -i -H "Authorization: Bearer $IDT" "$RS/api/orders" \
+ | sed -n '1p;/^WWW-Authenticate/p'
+ fi
+ fi
+
+ if [ -n "$RT" ]; then
+ section "11. Refresh, with rotation"
+ echo "old refresh token: ${RT:0:24}..."
+ R2=$(curl -s "${AUTH_ARGS[@]}" -d grant_type=refresh_token -d "refresh_token=$RT" \
+ -d "client_id=$CLIENT" "$AS/oauth2/token")
+ NEW=$(echo "$R2" | python3 -c 'import sys,json;print(json.load(sys.stdin).get("refresh_token",""))')
+ echo "new refresh token: ${NEW:0:24}..."
+ [ "$RT" = "$NEW" ] && echo "SAME - reuseRefreshTokens(true)" || echo "DIFFERENT - reuseRefreshTokens(false), the old one is now dead"
+ echo
+ echo "Replaying the old one:"
+ curl -s "${AUTH_ARGS[@]}" -d grant_type=refresh_token -d "refresh_token=$RT" \
+ -d "client_id=$CLIENT" "$AS/oauth2/token"
+ echo
+ fi
+} > "$OUT" 2>&1
+sed -i 's/[[:space:]]*$//' "$OUT"
+echo "wrote $OUT"; tail -5 "$OUT"
diff --git a/authorization-server/scripts/client-credentials.sh b/authorization-server/scripts/client-credentials.sh
new file mode 100755
index 0000000..a4b8da0
--- /dev/null
+++ b/authorization-server/scripts/client-credentials.sh
@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# The simplest grant, and what the token customiser does and does not add to it.
+set -u
+cd "$(dirname "$0")/.."
+. scripts/lib.sh
+OUT="../docs/output/${1:-as-client-credentials}.txt"
+mkdir -p ../docs/output
+{
+ section "POST /oauth2/token grant_type=client_credentials"
+ echo "\$ curl -su demo-service:service-secret -d grant_type=client_credentials \\"
+ echo " -d scope=orders.read $AS/oauth2/token"
+ RESP=$(curl -s -u demo-service:service-secret \
+ -d grant_type=client_credentials -d scope=orders.read \
+ "$AS/oauth2/token")
+ echo "$RESP" | python3 -m json.tool
+
+ TOKEN=$(echo "$RESP" | python3 -c 'import sys,json;print(json.load(sys.stdin).get("access_token",""))')
+ if [ -z "$TOKEN" ]; then echo "no access token - stopping"; exit 1; fi
+
+ case "$TOKEN" in
+ *.*.*)
+ section "JOSE header"
+ jwt_header "$TOKEN"
+ section "Claims"
+ jwt_payload "$TOKEN"
+ ;;
+ *)
+ section "Not a JWT"
+ echo "The access token is an opaque reference: $TOKEN"
+ echo "Length ${#TOKEN}. It carries no claims; the resource server must introspect it."
+ section "POST /oauth2/introspect"
+ curl -s -u demo-service:service-secret -d "token=$TOKEN" \
+ "$AS/oauth2/introspect" | python3 -m json.tool
+ ;;
+ esac
+
+ section "Wrong secret"
+ echo "\$ curl -si -u demo-service:WRONG -d grant_type=client_credentials $AS/oauth2/token"
+ curl -s -i -u demo-service:WRONG -d grant_type=client_credentials \
+ "$AS/oauth2/token" | sed -n '1p;/^WWW-Authenticate/p;/^{/p'
+
+ section "A grant the client is not registered for"
+ echo "\$ curl -si -u demo-service:service-secret -d grant_type=authorization_code -d code=x $AS/oauth2/token"
+ curl -s -i -u demo-service:service-secret -d grant_type=authorization_code -d code=x \
+ "$AS/oauth2/token" | sed -n '1p;/^{/p'
+
+ section "A scope the client is not registered for"
+ echo "\$ curl -s -u demo-service:service-secret -d grant_type=client_credentials -d scope=orders.write $AS/oauth2/token"
+ curl -s -u demo-service:service-secret -d grant_type=client_credentials -d scope=orders.write \
+ "$AS/oauth2/token"
+ echo
+
+ section "Calling the resource server with the token"
+ for path in /public /api/orders /api/admin; do
+ CODE=$(curl -s -o /tmp/rsbody -w '%{http_code}' -H "Authorization: Bearer $TOKEN" "$RS$path")
+ WWW=$(curl -s -D - -o /dev/null -H "Authorization: Bearer $TOKEN" "$RS$path" | grep -i '^WWW-Authenticate' || true)
+ echo "GET $path -> $CODE"
+ [ -n "$WWW" ] && echo " $WWW"
+ head -c 400 /tmp/rsbody; echo
+ done
+} > "$OUT" 2>&1
+sed -i 's/[[:space:]]*$//' "$OUT"
+echo "wrote $OUT"
diff --git a/authorization-server/scripts/client-flow.sh b/authorization-server/scripts/client-flow.sh
new file mode 100755
index 0000000..e7a56ec
--- /dev/null
+++ b/authorization-server/scripts/client-flow.sh
@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+# Drives the real Spring OAuth2 client through a real browser flow with curl, so the
+# behaviour is the client's own and not this script's.
+#
+# ./scripts/client-flow.sh