Defaults are the generic spelling, not any one provider's. A source that knows better — + * {@code flash-ext-auth-oidc} defaults roles to Keycloak's {@code realm_access.roles} — builds + * its own {@code AuthConfig} with the paths its provider actually uses. + */ +public final class AuthConfig { + + private final String rolesClaimPath; + private final String scopeClaimPaths; + + private AuthConfig(Builder b) { + this.rolesClaimPath = b.rolesClaimPath; + this.scopeClaimPaths = b.scopeClaimPaths; + } + + /** Dot-separated path to the roles list in the claims (default: {@code roles}). */ + public String rolesClaimPath() { return rolesClaimPath; } + + /** Comma-separated claim paths scopes are read from, in order (default: {@code scope,scp}). */ + public String scopeClaimPaths() { return scopeClaimPaths; } + + public static Builder builder() { return new Builder(); } + + public static final class Builder { + private String rolesClaimPath = "roles"; + private String scopeClaimPaths = "scope,scp"; + + private Builder() {} + + /** Dot-separated path to the roles list — e.g. {@code realm_access.roles}, {@code groups}. */ + public Builder rolesClaimPath(String path) { this.rolesClaimPath = path; return this; } + /** Comma-separated claim paths scopes are read from, tried in order. */ + public Builder scopeClaimPaths(String paths) { this.scopeClaimPaths = paths; return this; } + + public AuthConfig build() { return new AuthConfig(this); } + } +} diff --git a/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/AuthMiddleware.java b/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/AuthMiddleware.java new file mode 100644 index 0000000..30c7a4d --- /dev/null +++ b/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/AuthMiddleware.java @@ -0,0 +1,280 @@ +package dev.relism.flash.ext.auth; + +import dev.relism.flash.exceptions.HttpException; +import dev.relism.flash.extension.FlashContext; +import dev.relism.flash.models.Request; +import dev.relism.flash.models.Response; +import dev.relism.flash.routing.Middleware; + +import java.util.ArrayList; +import java.util.List; +import java.util.Map; + +/** + * Turns claims into a yes or a no. Exposed in the {@link FlashContext} for manual use on lambda + * routes, and injected automatically for handlers annotated with {@link Authenticated}, + * {@link RolesAllowed} or {@link ScopesAllowed}. + * + *
It knows nothing about how the caller proved who they are — that is the + * {@link CredentialSource} it is built with. What lives here is the half that is the same for + * every mechanism: publish the claims for the request, match roles and scopes against them, clear + * up afterwards. + * + *
{@code
+ * AuthMiddleware auth = app.ctx().require(AuthMiddleware.class);
+ * app.get("/api/me", (req, res) -> ClaimsHolder.claim("sub"), auth.protect());
+ * app.delete("/admin/users/{id}", handler, auth.requireRole("admin"));
+ * }
+ */
+public class AuthMiddleware {
+
+ private final AuthConfig config;
+ private final CredentialSource source;
+ private final String[] roleClaimPathParts;
+ private final String[][] scopeClaimPathParts;
+
+ public AuthMiddleware(AuthConfig config, CredentialSource source) {
+ this.config = config;
+ this.source = source;
+ this.roleClaimPathParts = splitClaimPath(config.rolesClaimPath());
+ this.scopeClaimPathParts = splitClaimPaths(config.scopeClaimPaths());
+ }
+
+ // -- Public API -----------------------------------------------------------
+
+ /** The single configured claim path used by every transport for role checks. */
+ public String rolesClaimPath() { return config.rolesClaimPath(); }
+
+ /** The source this middleware authenticates with. */
+ public CredentialSource source() { return source; }
+
+ /**
+ * The same authorization rules against a different credential source. Used where one route
+ * needs a variant of an installed source — {@code flash-ext-mcp} protects {@code /mcp} with an
+ * OIDC source whose challenges carry RFC 9728 resource metadata, while every other route keeps
+ * the plain one.
+ */
+ public AuthMiddleware withSource(CredentialSource source) {
+ return new AuthMiddleware(config, source);
+ }
+
+ /**
+ * Rejects the request unless the caller is authenticated. How it is rejected — a 401 with a
+ * challenge, a redirect into a sign-in flow — is the source's decision, not this one's.
+ */
+ public Middleware protect() {
+ return next -> (req, res) -> {
+ Map{@code
+ * app.get("/", handler, auth.optional());
+ * // Inside handler: ClaimsHolder.current() is non-null iff the caller is signed in.
+ * }
+ */
+ public Middleware optional() {
+ return next -> (req, res) -> {
+ MapFor role-based access use {@link RolesAllowed} instead (it implies authentication). * - *
Set {@code optional = true} on public routes that personalise their response when - * the user happens to be logged in but should remain accessible to guests. The middleware - * will populate {@link ClaimsHolder} if credentials are present and silently skip it - * otherwise — the request is never rejected. + *
Set {@code optional = true} on public routes that personalise their response when the caller + * happens to be signed in but should remain reachable by guests. The middleware populates + * {@link ClaimsHolder} when a credential is present and silently skips it otherwise — the request + * is never rejected. * *
{@code
- * // Hard auth — redirects / 401 when unauthenticated:
+ * // Hard auth — 401 or a redirect when unauthenticated:
* @Route(method = HttpMethod.GET, path = "/api/profile")
* @Authenticated
* public class GetProfile extends JacksonHandler { ... }
*
- * // Soft auth — guest-friendly, ClaimsHolder populated only when logged in:
+ * // Soft auth — guest-friendly, ClaimsHolder populated only when signed in:
* @Route(method = HttpMethod.GET, path = "/")
* @Authenticated(optional = true)
* public class HomePage extends HtmlHandler { ... }
diff --git a/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/flash/ext/oidc/OidcUser.java b/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/Claims.java
similarity index 85%
rename from flash-extensions/flash-ext-oidc/src/main/java/dev/relism/flash/ext/oidc/OidcUser.java
rename to flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/Claims.java
index d54f7f4..bc71286 100644
--- a/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/flash/ext/oidc/OidcUser.java
+++ b/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/Claims.java
@@ -1,43 +1,36 @@
-package dev.relism.flash.ext.oidc;
+package dev.relism.flash.ext.auth;
import java.util.List;
import java.util.Map;
import java.util.ArrayList;
/**
- * Type-safe view over the JWT claims stored in {@link ClaimsHolder}.
+ * A typed view over one request's claims — whatever the {@link CredentialSource} that
+ * authenticated it produced. Obtained from {@link ClaimsHolder#current()}.
*
- * Obtainable from any protected context via {@link ClaimsHolder#user()}.
- * Class-based handlers that extend the {@code SessionHandler} hierarchy already
- * have a provisioned DB user in {@code currentUser}; {@code OidcUser} complements
- * that by giving access to the raw OIDC claims when needed, and is the primary
- * API for lambda routes.
+ *
The accessors name claim keys, not a protocol: {@code sub} is RFC 7519, and
+ * {@code email}, {@code name} and {@code preferred_username} are spelled the same way by every
+ * token issuer worth integrating. A source that uses different keys exposes them through
+ * {@link #claim(String)} or {@link #roles(String)}.
*
*
{@code
- * // Lambda route (OidcMiddleware injected):
* app.get("/api/whoami", (req, res) -> {
- * OidcUser u = ClaimsHolder.user();
- * return Map.of("sub", u.sub(), "email", u.email(), "roles", u.roles("realm_access.roles"), "scopes", u.scopes());
- * }, oidcMw.protect());
- *
- * // Class-based handler (currentUser is the DB entity; oidcUser() for raw claims):
- * protected Object handleAuthenticated(Request req, Response res) throws Exception {
- * OidcUser u = oidcUser(); // same as ClaimsHolder.user()
- * return json(res, currentUser); // DB entity — provisioned from OIDC sub
- * }
+ * Claims c = ClaimsHolder.current();
+ * return Map.of("sub", c.sub(), "email", c.email(), "roles", c.roles("realm_access.roles"));
+ * }, auth.protect());
* }
*/
-public final class OidcUser {
+public final class Claims {
private final Map claims;
- OidcUser(Map claims) {
+ Claims(Map claims) {
this.claims = claims;
}
- // ── Common OIDC standard claims ───────────────────────────────────────────
+ // ── Common claims ─────────────────────────────────────────────────────────
- /** Subject identifier — unique, stable user ID issued by the provider. */
+ /** Subject identifier — the stable, unique id of the caller. */
public String sub() { return str("sub"); }
/** User's email address ({@code email} claim). */
@@ -84,7 +77,7 @@ public final class OidcUser {
// -- Scopes ---------------------------------------------------------------
/**
- * Resolves OAuth2 scopes from standard OIDC/OAuth claims using fallback order:
+ * Resolves scopes using the conventional fallback order:
* {@code scope} then {@code scp}. Supports both space-separated string and list forms.
*/
public List scopes() {
diff --git a/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/ClaimsHolder.java b/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/ClaimsHolder.java
new file mode 100644
index 0000000..a8cf400
--- /dev/null
+++ b/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/ClaimsHolder.java
@@ -0,0 +1,64 @@
+package dev.relism.flash.ext.auth;
+
+import java.util.Map;
+
+/**
+ * The current request's claims, published by {@link AuthMiddleware} before the handler runs and
+ * cleared in a {@code finally} afterwards.
+ *
+ * Safe with virtual threads: each request gets its own, so a {@link ThreadLocal} is naturally
+ * isolated per request.
+ *
+ *
Writing is deliberately not public. A {@link CredentialSource} returns claims and the
+ * middleware publishes them, so no code outside this module can put claims on a request that did
+ * not carry them.
+ *
+ *
{@code
+ * // Inside any handler behind @Authenticated or @RolesAllowed:
+ * Claims caller = ClaimsHolder.current();
+ * String email = caller.email();
+ * List roles = caller.roles("realm_access.roles");
+ *
+ * // Raw escape hatch:
+ * Map all = ClaimsHolder.map();
+ * }
+ */
+public final class ClaimsHolder {
+
+ private static final ThreadLocal> HOLDER = new ThreadLocal<>();
+
+ private ClaimsHolder() {}
+
+ /** Called by {@link AuthMiddleware} once a source has authenticated the request. */
+ static void set(Map claims) {
+ HOLDER.set(claims);
+ }
+
+ /** Called by {@link AuthMiddleware} in the {@code finally} block. */
+ static void clear() {
+ HOLDER.remove();
+ }
+
+ /**
+ * A typed view of the current request's claims, or {@code null} when the route carries no
+ * authentication middleware or the caller is anonymous under
+ * {@link Authenticated}{@code (optional = true)}.
+ */
+ public static Claims current() {
+ Map claims = HOLDER.get();
+ return claims != null ? new Claims(claims) : null;
+ }
+
+ /** The raw claims map for the current request, or {@code null}. @see #current() */
+ public static Map map() {
+ return HOLDER.get();
+ }
+
+ /** A single claim as a String, or {@code null} when absent or the caller is anonymous. */
+ public static String claim(String key) {
+ Map claims = HOLDER.get();
+ if (claims == null) return null;
+ Object v = claims.get(key);
+ return v != null ? v.toString() : null;
+ }
+}
diff --git a/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/CredentialSource.java b/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/CredentialSource.java
new file mode 100644
index 0000000..4ceb2f5
--- /dev/null
+++ b/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/CredentialSource.java
@@ -0,0 +1,48 @@
+package dev.relism.flash.ext.auth;
+
+import dev.relism.flash.exceptions.HttpException;
+import dev.relism.flash.models.Request;
+import dev.relism.flash.models.Response;
+
+import java.util.Map;
+
+/**
+ * Turns whatever a request carries — a bearer token, a session cookie, an API key — into the
+ * claims authorization runs on. One is installed per authentication mechanism;
+ * {@code flash-ext-auth-oidc} contributes the OpenID Connect one.
+ *
+ * Implementations never touch {@link ClaimsHolder}: they produce claims and {@link
+ * AuthMiddleware} publishes them for the duration of the request. Nothing outside this module can
+ * inject claims into a request, which is the point.
+ */
+public interface CredentialSource {
+
+ /**
+ * Resolves the caller's claims, rejecting the request when it cannot.
+ *
+ *
Three outcomes, and the difference between the last two matters:
+ *
+ * - claims — the caller presented a valid credential;
+ * - {@code null} — no credential was presented and this source has already answered the
+ * request itself (typically a redirect into a sign-in flow). The middleware stops and
+ * writes nothing more;
+ * - {@link HttpException} — a credential was presented and is invalid. The source
+ * sets any challenge header it owes the caller before throwing.
+ *
+ */
+ Map authenticate(Request req, Response res);
+
+ /**
+ * Resolves claims without ever rejecting: {@code null} when no valid credential is present.
+ * Backs {@link Authenticated}{@code (optional = true)}, where an anonymous caller is a normal
+ * outcome rather than a failure.
+ */
+ Map peek(Request req);
+
+ /**
+ * The {@code WWW-Authenticate} value to send with a 403 caused by missing scopes, or
+ * {@code null} when this source has no such concept. Only consulted after authentication has
+ * already succeeded.
+ */
+ default String insufficientScopeChallenge(String[] requiredScopes) { return null; }
+}
diff --git a/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/flash/ext/oidc/RolesAllowed.java b/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/RolesAllowed.java
similarity index 56%
rename from flash-extensions/flash-ext-oidc/src/main/java/dev/relism/flash/ext/oidc/RolesAllowed.java
rename to flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/RolesAllowed.java
index 1009f14..b37020d 100644
--- a/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/flash/ext/oidc/RolesAllowed.java
+++ b/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/RolesAllowed.java
@@ -1,4 +1,4 @@
-package dev.relism.flash.ext.oidc;
+package dev.relism.flash.ext.auth;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
@@ -6,20 +6,19 @@ import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
- * Restricts a handler to callers whose JWT contains at least one of the
- * specified roles. Authentication is implicitly required — no need to combine
- * with {@link Authenticated}.
+ * Restricts a handler to callers holding at least one of the named roles. Authentication is
+ * implied — there is no need to combine it with {@link Authenticated}.
*
- * Roles are read from the claim configured in {@link OidcConfig#rolesClaimPath()}
- * (default: {@code "roles"}). Nested paths like {@code "realm_access.roles"} are
- * supported with dot notation.
+ *
Roles are read from the claim path the installed credential source is configured with
+ * (Keycloak's is {@code realm_access.roles}; many providers use a flat {@code roles} or
+ * {@code groups}). Nested paths use dot notation.
*
*
{@code
* @Route(method = HttpMethod.DELETE, path = "/api/admin/blogs/{id}")
* @RolesAllowed("admin")
* public class DeleteBlog extends JacksonHandler { ... }
*
- * // Multiple accepted roles (OR semantics — any one role is sufficient):
+ * // Multiple accepted roles (OR semantics — any one is sufficient):
* @RolesAllowed({"admin", "editor"})
* public class UpdateBlog extends JacksonHandler { ... }
* }
diff --git a/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/flash/ext/oidc/ScopesAllowed.java b/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/ScopesAllowed.java
similarity index 87%
rename from flash-extensions/flash-ext-oidc/src/main/java/dev/relism/flash/ext/oidc/ScopesAllowed.java
rename to flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/ScopesAllowed.java
index a5ba66f..40cd8c5 100644
--- a/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/flash/ext/oidc/ScopesAllowed.java
+++ b/flash-extensions/flash-ext-auth-core/src/main/java/dev/relism/flash/ext/auth/ScopesAllowed.java
@@ -1,4 +1,4 @@
-package dev.relism.flash.ext.oidc;
+package dev.relism.flash.ext.auth;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
@@ -6,11 +6,11 @@ import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
- * Restricts a handler to callers whose token carries the required OAuth2 scopes.
+ * Restricts a handler to callers whose credential carries the required scopes.
* Authentication is implicitly required.
*
* Scopes are resolved from the configured claim paths in
- * {@link OidcConfig#scopeClaimPaths()} (default: {@code "scope,scp"}) and support
+ * {@link AuthConfig#scopeClaimPaths()} (default: {@code "scope,scp"}) and support
* both standard formats:
*
* - {@code scope}: space-separated string
diff --git a/flash-extensions/flash-ext-oidc/src/test/java/dev/relism/flash/ext/oidc/OidcAuthPolicyTest.java b/flash-extensions/flash-ext-auth-core/src/test/java/dev/relism/flash/ext/auth/AuthPolicyTest.java
similarity index 74%
rename from flash-extensions/flash-ext-oidc/src/test/java/dev/relism/flash/ext/oidc/OidcAuthPolicyTest.java
rename to flash-extensions/flash-ext-auth-core/src/test/java/dev/relism/flash/ext/auth/AuthPolicyTest.java
index e1677a5..a2e8139 100644
--- a/flash-extensions/flash-ext-oidc/src/test/java/dev/relism/flash/ext/oidc/OidcAuthPolicyTest.java
+++ b/flash-extensions/flash-ext-auth-core/src/test/java/dev/relism/flash/ext/auth/AuthPolicyTest.java
@@ -1,4 +1,4 @@
-package dev.relism.flash.ext.oidc;
+package dev.relism.flash.ext.auth;
import org.junit.jupiter.api.Test;
@@ -6,7 +6,7 @@ import java.util.List;
import static org.junit.jupiter.api.Assertions.*;
-class OidcAuthPolicyTest {
+class AuthPolicyTest {
static class PlainHandler {}
@@ -33,12 +33,12 @@ class OidcAuthPolicyTest {
@Test
void compileFromAnnotations_noSecurityAnnotations_returnsNull() {
- assertNull(OidcAuthPolicy.compileFromAnnotations(PlainHandler.class));
+ assertNull(AuthPolicy.compileFromAnnotations(PlainHandler.class));
}
@Test
void compileFromAnnotations_authenticated_createsRequiredAuthPolicy() {
- OidcAuthPolicy policy = OidcAuthPolicy.compileFromAnnotations(AuthenticatedHandler.class);
+ AuthPolicy policy = AuthPolicy.compileFromAnnotations(AuthenticatedHandler.class);
assertNotNull(policy);
assertFalse(policy.optionalAuth());
assertEquals(0, policy.requiredRoles().length);
@@ -47,14 +47,14 @@ class OidcAuthPolicyTest {
@Test
void compileFromAnnotations_optionalAuth_createsOptionalPolicy() {
- OidcAuthPolicy policy = OidcAuthPolicy.compileFromAnnotations(OptionalHandler.class);
+ AuthPolicy policy = AuthPolicy.compileFromAnnotations(OptionalHandler.class);
assertNotNull(policy);
assertTrue(policy.optionalAuth());
}
@Test
void compileFromAnnotations_rolesAndScopes_areNormalizedAndMerged() {
- OidcAuthPolicy policy = OidcAuthPolicy.compileFromAnnotations(CombinedHandler.class);
+ AuthPolicy policy = AuthPolicy.compileFromAnnotations(CombinedHandler.class);
assertNotNull(policy);
assertFalse(policy.optionalAuth());
assertArrayEquals(new String[]{"admin"}, policy.requiredRoles());
@@ -64,7 +64,7 @@ class OidcAuthPolicyTest {
@Test
void compileFromAnnotations_scopesAny_preservesMatchModeAndDedupes() {
- OidcAuthPolicy policy = OidcAuthPolicy.compileFromAnnotations(ScopesHandler.class);
+ AuthPolicy policy = AuthPolicy.compileFromAnnotations(ScopesHandler.class);
assertNotNull(policy);
assertArrayEquals(new String[]{"orders:write", "payments:write"}, policy.requiredScopes());
assertEquals(ScopesAllowed.Match.ANY, policy.scopeMatch());
@@ -73,22 +73,22 @@ class OidcAuthPolicyTest {
@Test
void compileFromAnnotations_optionalCannotBeCombinedWithConstraints() {
assertThrows(IllegalStateException.class,
- () -> OidcAuthPolicy.compileFromAnnotations(InvalidOptionalHandler.class));
+ () -> AuthPolicy.compileFromAnnotations(InvalidOptionalHandler.class));
}
@Test
void openApiScopesFor_returnsScopesWhenPresent() {
assertEquals(List.of("orders:write", "payments:write"),
- OidcAuthPolicy.openApiScopesFor(ScopesHandler.class));
+ AuthPolicy.openApiScopesFor(ScopesHandler.class));
}
@Test
void openApiScopesFor_rolesOnly_returnsEmptyList() {
- assertEquals(List.of(), OidcAuthPolicy.openApiScopesFor(RolesHandler.class));
+ assertEquals(List.of(), AuthPolicy.openApiScopesFor(RolesHandler.class));
}
@Test
void openApiScopesFor_noSecurity_returnsNull() {
- assertNull(OidcAuthPolicy.openApiScopesFor(PlainHandler.class));
+ assertNull(AuthPolicy.openApiScopesFor(PlainHandler.class));
}
}
diff --git a/flash-extensions/flash-ext-oidc/src/test/java/dev/relism/flash/ext/oidc/ClaimMatchingTest.java b/flash-extensions/flash-ext-auth-core/src/test/java/dev/relism/flash/ext/auth/ClaimMatchingTest.java
similarity index 94%
rename from flash-extensions/flash-ext-oidc/src/test/java/dev/relism/flash/ext/oidc/ClaimMatchingTest.java
rename to flash-extensions/flash-ext-auth-core/src/test/java/dev/relism/flash/ext/auth/ClaimMatchingTest.java
index 82132b2..f74f63f 100644
--- a/flash-extensions/flash-ext-oidc/src/test/java/dev/relism/flash/ext/oidc/ClaimMatchingTest.java
+++ b/flash-extensions/flash-ext-auth-core/src/test/java/dev/relism/flash/ext/auth/ClaimMatchingTest.java
@@ -1,4 +1,4 @@
-package dev.relism.flash.ext.oidc;
+package dev.relism.flash.ext.auth;
import org.junit.jupiter.api.Test;
@@ -23,15 +23,15 @@ import static org.junit.jupiter.api.Assertions.assertTrue;
*/
class ClaimMatchingTest {
- private static OidcMiddleware middleware(String rolesPath, String scopePaths) {
- return new OidcMiddleware(null, OidcConfig
- .builder("https://idp.example.com", "client", "secret", "/auth/callback")
+ /** No credential source: every assertion here is about claims that are already resolved. */
+ private static AuthMiddleware middleware(String rolesPath, String scopePaths) {
+ return new AuthMiddleware(AuthConfig.builder()
.rolesClaimPath(rolesPath)
.scopeClaimPaths(scopePaths)
- .build(), null, null);
+ .build(), null);
}
- private static OidcMiddleware middleware() {
+ private static AuthMiddleware middleware() {
return middleware("realm_access.roles", "scope,scp");
}
@@ -182,7 +182,7 @@ class ClaimMatchingTest {
@Test
void scopesAreLookedForInEveryConfiguredPathUntilOneMatches() {
- OidcMiddleware mw = middleware("roles", "scope, scp , permissions.scopes");
+ AuthMiddleware mw = middleware("roles", "scope, scp , permissions.scopes");
Map claims = Map.of(
"scp", List.of("payments:write"),
"permissions", Map.of("scopes", "orders:approve"));
@@ -196,14 +196,14 @@ class ClaimMatchingTest {
@Test
void blankScopePathsFallBackToScopeAndScp() {
- OidcMiddleware mw = middleware("roles", " ");
+ AuthMiddleware mw = middleware("roles", " ");
assertTrue(mw.scopesAllowed(Map.of("scope", "a"), new String[]{"a"}, ScopesAllowed.Match.ALL));
assertTrue(mw.scopesAllowed(Map.of("scp", "b"), new String[]{"b"}, ScopesAllowed.Match.ALL));
}
@Test
void aScopePathListOfOnlySeparatorsFallsBackToScopeAndScp() {
- OidcMiddleware mw = middleware("roles", " , , ");
+ AuthMiddleware mw = middleware("roles", " , , ");
assertTrue(mw.scopesAllowed(Map.of("scp", "b"), new String[]{"b"}, ScopesAllowed.Match.ALL));
}
}
diff --git a/flash-extensions/flash-ext-oidc/src/test/java/dev/relism/flash/ext/oidc/OidcUserScopesTest.java b/flash-extensions/flash-ext-auth-core/src/test/java/dev/relism/flash/ext/auth/ClaimsScopesTest.java
similarity index 74%
rename from flash-extensions/flash-ext-oidc/src/test/java/dev/relism/flash/ext/oidc/OidcUserScopesTest.java
rename to flash-extensions/flash-ext-auth-core/src/test/java/dev/relism/flash/ext/auth/ClaimsScopesTest.java
index 4fbcc67..6e6fe1e 100644
--- a/flash-extensions/flash-ext-oidc/src/test/java/dev/relism/flash/ext/oidc/OidcUserScopesTest.java
+++ b/flash-extensions/flash-ext-auth-core/src/test/java/dev/relism/flash/ext/auth/ClaimsScopesTest.java
@@ -1,4 +1,4 @@
-package dev.relism.flash.ext.oidc;
+package dev.relism.flash.ext.auth;
import org.junit.jupiter.api.Test;
@@ -7,11 +7,11 @@ import java.util.Map;
import static org.junit.jupiter.api.Assertions.*;
-class OidcUserScopesTest {
+class ClaimsScopesTest {
@Test
void scopes_readsStandardScopeString() {
- OidcUser user = new OidcUser(Map.of("scope", "openid profile orders:read"));
+ Claims user = new Claims(Map.of("scope", "openid profile orders:read"));
assertEquals(List.of("openid", "profile", "orders:read"), user.scopes());
assertTrue(user.hasScope("orders:read"));
@@ -20,7 +20,7 @@ class OidcUserScopesTest {
@Test
void scopes_fallsBackToScpArray() {
- OidcUser user = new OidcUser(Map.of("scp", List.of("orders:write", "payments:write")));
+ Claims user = new Claims(Map.of("scp", List.of("orders:write", "payments:write")));
assertEquals(List.of("orders:write", "payments:write"), user.scopes());
assertTrue(user.hasScope("payments:write"));
@@ -28,7 +28,7 @@ class OidcUserScopesTest {
@Test
void scopes_supportsCustomClaimPaths() {
- OidcUser user = new OidcUser(Map.of("permissions", Map.of("scopes", List.of("a", "b"))));
+ Claims user = new Claims(Map.of("permissions", Map.of("scopes", List.of("a", "b"))));
assertEquals(List.of("a", "b"), user.scopes("permissions.scopes"));
assertTrue(user.hasScope("permissions.scopes", "a"));
@@ -37,7 +37,7 @@ class OidcUserScopesTest {
@Test
void scopes_combinesMultipleClaimPathsInOrder() {
- OidcUser user = new OidcUser(Map.of(
+ Claims user = new Claims(Map.of(
"scope", "openid",
"scp", List.of("profile", "orders:read")
));
diff --git a/flash-extensions/flash-ext-mcp/src/main/java/dev/relism/flash/ext/mcp/McpOidcIntegration.java b/flash-extensions/flash-ext-mcp/src/main/java/dev/relism/flash/ext/mcp/McpOidcIntegration.java
index 80eae76..c971968 100644
--- a/flash-extensions/flash-ext-mcp/src/main/java/dev/relism/flash/ext/mcp/McpOidcIntegration.java
+++ b/flash-extensions/flash-ext-mcp/src/main/java/dev/relism/flash/ext/mcp/McpOidcIntegration.java
@@ -1,11 +1,12 @@
package dev.relism.flash.ext.mcp;
-import dev.relism.flash.ext.oidc.Authenticated;
-import dev.relism.flash.ext.oidc.ClaimsHolder;
-import dev.relism.flash.ext.oidc.OidcMiddleware;
-import dev.relism.flash.ext.oidc.OidcUser;
-import dev.relism.flash.ext.oidc.RolesAllowed;
-import dev.relism.flash.ext.oidc.ScopesAllowed;
+import dev.relism.flash.ext.auth.AuthMiddleware;
+import dev.relism.flash.ext.auth.Authenticated;
+import dev.relism.flash.ext.auth.Claims;
+import dev.relism.flash.ext.auth.ClaimsHolder;
+import dev.relism.flash.ext.auth.RolesAllowed;
+import dev.relism.flash.ext.auth.ScopesAllowed;
+import dev.relism.flash.ext.oidc.OidcCredentialSource;
import dev.relism.flash.exceptions.HttpException;
import dev.relism.flash.extension.FlashContext;
import dev.relism.flash.models.Request;
@@ -19,7 +20,7 @@ import java.util.function.Function;
import java.util.function.Supplier;
/**
- * Lazy, isolated bridge to {@code flash-ext-oidc}.
+ * Lazy, isolated bridge to {@code flash-ext-oidc} and {@code flash-ext-auth-core}.
*
* References to OIDC types only ever resolve when {@link #resolve}/{@link #compileToolPolicy}
* are actually invoked — never at {@link McpExtension} class-load time — because they live in
@@ -34,7 +35,7 @@ import java.util.function.Supplier;
*
Zero-config by design: when {@code flash-ext-oidc} is installed, everything an MCP OAuth2
* resource server needs — issuer, canonical resource identifier, RFC 8707 audience binding, and
* a spec-compliant {@code WWW-Authenticate} challenge (RFC 9728 §5.1) — is derived straight from
- * the installed {@link OidcMiddleware}, with no additional {@link McpConfig} calls.
+ * the installed {@link OidcCredentialSource}, with no additional {@link McpConfig} calls.
* {@link McpConfig#resourceIdentifier(String)}/{@link McpConfig#authorizationServerIssuer(String)}
* remain as explicit overrides for the rare case where that guess is wrong.
*/
@@ -51,20 +52,25 @@ final class McpOidcIntegration {
/** Returns the resolved security bundle, or {@code null} if oidc is not installed. */
static Resolved resolve(FlashContext ctx, McpConfig config) {
- Optional oidc = ctx.find(OidcMiddleware.class);
- if (oidc.isEmpty()) return null;
+ // Deliberately keyed on the OIDC source and not on AuthMiddleware: McpSecurity means
+ // "a real OAuth2 authorization server is protecting this endpoint", and an app that
+ // authenticates some other way must not satisfy REQUIRED by accident.
+ Optional oidc = ctx.find(OidcCredentialSource.class);
+ Optional auth = ctx.find(AuthMiddleware.class);
+ if (oidc.isEmpty() || auth.isEmpty()) return null;
- OidcMiddleware oidcMw = oidc.get();
+ OidcCredentialSource source = oidc.get();
+ AuthMiddleware authMw = auth.get();
String resourceMetadataPath = "/.well-known/oauth-protected-resource" + config.rootPath();
String issuer = config.authorizationServerIssuer() != null
- ? config.authorizationServerIssuer() : oidcMw.issuer();
+ ? config.authorizationServerIssuer() : source.issuer();
Function resourceId = req -> config.resourceIdentifier() != null
? config.resourceIdentifier()
- : OidcMiddleware.selfOrigin(req, oidcMw.selfScheme()) + config.rootPath();
+ : OidcCredentialSource.selfOrigin(req, source.selfScheme()) + config.rootPath();
- Middleware protect = oidcMw.protect(resourceMetadataPath);
+ Middleware protect = authMw.withSource(source.withResourceMetadata(resourceMetadataPath)).protect();
Middleware secured = Middleware.of(protect, audienceGuard(resourceId));
- return new Resolved(secured, issuer, oidcMw.rolesClaimPath(), resourceId);
+ return new Resolved(secured, issuer, authMw.rolesClaimPath(), resourceId);
}
/**
@@ -73,7 +79,7 @@ final class McpOidcIntegration {
*/
private static Middleware audienceGuard(Function resourceIdentifier) {
return next -> (req, res) -> {
- Map claims = ClaimsHolder.get();
+ Map claims = ClaimsHolder.map();
String expected = resourceIdentifier.apply(req);
if (claims != null && !audienceMatches(claims.get("aud"), expected)) {
log.warn("[flash-ext-mcp] Rejecting token (RFC 8707): aud={} does not include expected " +
@@ -100,7 +106,7 @@ final class McpOidcIntegration {
* annotations. Called once per tool at boot ({@link McpRegistry#scan}), never on the
* request hot path — the {@link Supplier} it returns is what runs per {@code tools/call},
* closing over the already-normalized role/scope arrays so the hot path itself allocates
- * nothing beyond what {@link OidcUser#hasRole}/{@link OidcUser#hasScope} already do.
+ * nothing beyond what {@link Claims#hasRole}/{@link Claims#hasScope} already do.
*
* Fails fast at boot, not silently at request time, for the two ways this can be
* misconfigured: the annotation present without OAuth2 actually protecting this MCP server
@@ -136,7 +142,7 @@ final class McpOidcIntegration {
ScopesAllowed.Match scopeMatch = scopes != null ? scopes.match() : ScopesAllowed.Match.ALL;
Supplier check = () -> {
- OidcUser user = ClaimsHolder.user();
+ Claims user = ClaimsHolder.current();
if (user == null) return "not authenticated";
if (requiredRoles.length > 0 && !hasAnyRole(user, rolesClaimPath, requiredRoles))
return "missing required role (any of: " + String.join(", ", requiredRoles) + ")";
@@ -147,12 +153,12 @@ final class McpOidcIntegration {
return new McpAuthPolicy(check);
}
- private static boolean hasAnyRole(OidcUser user, String claimPath, String[] roles) {
+ private static boolean hasAnyRole(Claims user, String claimPath, String[] roles) {
for (String role : roles) if (user.hasRole(claimPath, role)) return true;
return false;
}
- private static boolean hasScopes(OidcUser user, String[] scopes, ScopesAllowed.Match match) {
+ private static boolean hasScopes(Claims user, String[] scopes, ScopesAllowed.Match match) {
if (match == ScopesAllowed.Match.ALL) {
for (String scope : scopes) if (!user.hasScope(scope)) return false;
return true;
diff --git a/flash-extensions/flash-ext-mcp/src/test/java/dev/relism/flash/ext/mcp/FakeOidcProvider.java b/flash-extensions/flash-ext-mcp/src/test/java/dev/relism/flash/ext/mcp/FakeOidcProvider.java
index 8f0bc37..8eb5f29 100644
--- a/flash-extensions/flash-ext-mcp/src/test/java/dev/relism/flash/ext/mcp/FakeOidcProvider.java
+++ b/flash-extensions/flash-ext-mcp/src/test/java/dev/relism/flash/ext/mcp/FakeOidcProvider.java
@@ -63,7 +63,7 @@ final class FakeOidcProvider implements AutoCloseable {
/**
* Same as {@link #signToken(String, String)}, plus a {@code scope} claim (space-delimited,
- * matching {@link dev.relism.flash.ext.oidc.OidcUser#hasScope}'s default claim path) and a
+ * matching {@link dev.relism.flash.ext.auth.Claims#hasScope}'s default claim path) and a
* Keycloak-shaped {@code realm_access.roles} claim (matching {@code McpConfig}'s default
* {@code rolesClaimPath}) when {@code roles} is non-empty.
*/
diff --git a/flash-extensions/flash-ext-mcp/src/test/java/dev/relism/flash/ext/mcp/authfixtures/authenticatedonly/PointlessAuthTool.java b/flash-extensions/flash-ext-mcp/src/test/java/dev/relism/flash/ext/mcp/authfixtures/authenticatedonly/PointlessAuthTool.java
index 9d9a622..71934d9 100644
--- a/flash-extensions/flash-ext-mcp/src/test/java/dev/relism/flash/ext/mcp/authfixtures/authenticatedonly/PointlessAuthTool.java
+++ b/flash-extensions/flash-ext-mcp/src/test/java/dev/relism/flash/ext/mcp/authfixtures/authenticatedonly/PointlessAuthTool.java
@@ -5,7 +5,7 @@ import dev.relism.flash.ext.mcp.TextContent;
import dev.relism.flash.ext.mcp.Tool;
import dev.relism.flash.ext.mcp.ToolArguments;
import dev.relism.flash.ext.mcp.ToolResponse;
-import dev.relism.flash.ext.oidc.Authenticated;
+import dev.relism.flash.ext.auth.Authenticated;
/** Deliberately misconfigured fixture: bare @Authenticated has no effect on an McpTool — see
* McpOidcIntegration#compileToolPolicy. Boot must fail with a clear message, not silently no-op. */
diff --git a/flash-extensions/flash-ext-mcp/src/test/java/dev/relism/flash/ext/mcp/authfixtures/secured/AdminOnlyTool.java b/flash-extensions/flash-ext-mcp/src/test/java/dev/relism/flash/ext/mcp/authfixtures/secured/AdminOnlyTool.java
index 1bd96f5..9da014e 100644
--- a/flash-extensions/flash-ext-mcp/src/test/java/dev/relism/flash/ext/mcp/authfixtures/secured/AdminOnlyTool.java
+++ b/flash-extensions/flash-ext-mcp/src/test/java/dev/relism/flash/ext/mcp/authfixtures/secured/AdminOnlyTool.java
@@ -5,7 +5,7 @@ import dev.relism.flash.ext.mcp.TextContent;
import dev.relism.flash.ext.mcp.Tool;
import dev.relism.flash.ext.mcp.ToolArguments;
import dev.relism.flash.ext.mcp.ToolResponse;
-import dev.relism.flash.ext.oidc.RolesAllowed;
+import dev.relism.flash.ext.auth.RolesAllowed;
@Tool(name = "admin_only", description = "Only callable with the admin role")
@RolesAllowed("admin")
diff --git a/flash-extensions/flash-ext-mcp/src/test/java/dev/relism/flash/ext/mcp/authfixtures/secured/WriteScopeTool.java b/flash-extensions/flash-ext-mcp/src/test/java/dev/relism/flash/ext/mcp/authfixtures/secured/WriteScopeTool.java
index 14b390f..aa4a3c0 100644
--- a/flash-extensions/flash-ext-mcp/src/test/java/dev/relism/flash/ext/mcp/authfixtures/secured/WriteScopeTool.java
+++ b/flash-extensions/flash-ext-mcp/src/test/java/dev/relism/flash/ext/mcp/authfixtures/secured/WriteScopeTool.java
@@ -5,7 +5,7 @@ import dev.relism.flash.ext.mcp.TextContent;
import dev.relism.flash.ext.mcp.Tool;
import dev.relism.flash.ext.mcp.ToolArguments;
import dev.relism.flash.ext.mcp.ToolResponse;
-import dev.relism.flash.ext.oidc.ScopesAllowed;
+import dev.relism.flash.ext.auth.ScopesAllowed;
@Tool(name = "write_only", description = "Only callable with the write scope")
@ScopesAllowed("write")
diff --git a/flash-extensions/flash-ext-oidc/pom.xml b/flash-extensions/flash-ext-oidc/pom.xml
index 374d708..9967473 100644
--- a/flash-extensions/flash-ext-oidc/pom.xml
+++ b/flash-extensions/flash-ext-oidc/pom.xml
@@ -13,6 +13,10 @@
flash-ext-oidc
+
+ dev.relism
+ flash-ext-auth-core
+
dev.relism
flash
diff --git a/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/flash/ext/oidc/ClaimsHolder.java b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/flash/ext/oidc/ClaimsHolder.java
deleted file mode 100644
index 490147a..0000000
--- a/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/flash/ext/oidc/ClaimsHolder.java
+++ /dev/null
@@ -1,71 +0,0 @@
-package dev.relism.flash.ext.oidc;
-
-import java.util.Map;
-
-/**
- * Thread-local store for JWT claims, populated by the OIDC middleware before
- * the handler runs and cleared in the {@code finally} block afterward.
- *
- * Safe with virtual threads: each request gets its own virtual thread, so
- * {@link ThreadLocal} values are naturally isolated per request.
- *
- *
{@code
- * // Inside any handler protected by @Authenticated or @RolesAllowed:
- *
- * // Preferred — typed wrapper:
- * OidcUser user = ClaimsHolder.user();
- * String email = user.email();
- * List roles = user.roles("realm_access.roles");
- *
- * // Raw escape hatch:
- * Map all = ClaimsHolder.get();
- * }
- */
-public final class ClaimsHolder {
-
- private static final ThreadLocal> HOLDER = new ThreadLocal<>();
-
- private ClaimsHolder() {}
-
- /** Called by the OIDC middleware after successful token validation. */
- static void set(Map claims) {
- HOLDER.set(claims);
- }
-
- /** Called by the OIDC middleware in the {@code finally} block. */
- static void clear() {
- HOLDER.remove();
- }
-
- /**
- * Returns a type-safe {@link OidcUser} view of the current request's claims,
- * or {@code null} if the route is not protected by OIDC middleware.
- *
- * This is the preferred entry point for both lambda and class-based handlers.
- */
- public static OidcUser user() {
- Map claims = HOLDER.get();
- return claims != null ? new OidcUser(claims) : null;
- }
-
- /**
- * Returns the raw claims map for the current request, or {@code null} if
- * the route is not protected by OIDC middleware.
- *
- * @see #user() for the preferred type-safe accessor
- */
- public static Map get() {
- return HOLDER.get();
- }
-
- /**
- * Returns the value of a single claim as a String, or {@code null} if
- * the claim is absent or the request is not authenticated.
- */
- public static String claim(String key) {
- Map claims = HOLDER.get();
- if (claims == null) return null;
- Object v = claims.get(key);
- return v != null ? v.toString() : null;
- }
-}
diff --git a/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/flash/ext/oidc/OidcCredentialSource.java b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/flash/ext/oidc/OidcCredentialSource.java
new file mode 100644
index 0000000..36f6adf
--- /dev/null
+++ b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/flash/ext/oidc/OidcCredentialSource.java
@@ -0,0 +1,316 @@
+package dev.relism.flash.ext.oidc;
+
+import dev.relism.flash.exceptions.HttpException;
+import dev.relism.flash.ext.auth.CredentialSource;
+import dev.relism.flash.models.Response;
+import dev.relism.flash.models.Request;
+
+import java.net.URLEncoder;
+import java.nio.charset.StandardCharsets;
+import java.time.Instant;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Optional;
+
+/**
+ * The OpenID Connect {@link CredentialSource}: it turns what a request carries into claims, and
+ * rejects it the way OAuth2 says to when it cannot. Authorization on those claims is
+ * {@code flash-ext-auth-core}'s job, not this class's.
+ *
+ * Resolution order on each request:
+ *
+ * - {@code Authorization: Bearer ...} header — validated via JWKS ({@link JwtValidator}).
+ * - {@code oidc_session} cookie — looked up in {@link OidcSessionStore}; transparently
+ * refreshed if the access token is expired.
+ * - Browser clients (no {@code Accept: application/json}) → redirect to
+ * {@code {routePrefix}/login?redirect={path}}.
+ * - API clients → 401 with a {@code WWW-Authenticate: Bearer} challenge.
+ *
+ */
+public final class OidcCredentialSource implements CredentialSource {
+
+ private static final String BEARER = "Bearer";
+
+ private final JwtValidator validator;
+ private final OidcConfig config;
+ private final OidcProviderMetadata meta;
+ private final TokenClient tokenClient;
+ private final String resourceMetadataPath;
+
+ OidcCredentialSource(JwtValidator validator, OidcConfig config,
+ OidcProviderMetadata meta, TokenClient tokenClient) {
+ this(validator, config, meta, tokenClient, null);
+ }
+
+ private OidcCredentialSource(JwtValidator validator, OidcConfig config,
+ OidcProviderMetadata meta, TokenClient tokenClient,
+ String resourceMetadataPath) {
+ this.validator = validator;
+ this.config = config;
+ this.meta = meta;
+ this.tokenClient = tokenClient;
+ this.resourceMetadataPath = resourceMetadataPath;
+ }
+
+ // -- CredentialSource -----------------------------------------------------
+
+ /** OIDC issuer this source validates tokens against — the {@code iss} claim it enforces. */
+ public String issuer() { return config.issuer(); }
+
+ /** Scheme used to build this app's own absolute URLs — see {@link OidcConfig#selfScheme()}. */
+ public String selfScheme() { return config.selfScheme(); }
+
+ /**
+ * A copy of this source whose 401 challenges also carry {@code resource_metadata}
+ * (RFC 9728 §5.1), resolved against the request's own scheme and host exactly like
+ * {@link OidcExtension}'s redirect URIs. {@code path} is absolute, e.g.
+ * {@code "/.well-known/oauth-protected-resource/mcp"}.
+ *
+ * Used by {@code flash-ext-mcp} to make its Protected Resource Metadata document
+ * discoverable straight from the {@code WWW-Authenticate} header, per the MCP Authorization
+ * spec.
+ */
+ public OidcCredentialSource withResourceMetadata(String path) {
+ return new OidcCredentialSource(validator, config, meta, tokenClient, path);
+ }
+
+ @Override
+ public Map authenticate(Request req, Response res) {
+ return resolve(req, res, resourceMetadataPath);
+ }
+
+ @Override
+ public Map peek(Request req) {
+ return resolveQuiet(req);
+ }
+
+ @Override
+ public String insufficientScopeChallenge(String[] requiredScopes) {
+ return bearerChallenge() + ", error=\"insufficient_scope\", scope=\""
+ + quoted(spaceDelimited(requiredScopes)) + "\"";
+ }
+
+ // -- Internals ------------------------------------------------------------
+
+ /**
+ * Like {@link #resolve} but never redirects or throws — returns {@code null} silently
+ * when no valid credentials are present. Used by {@link #optional()}.
+ */
+ private Map resolveQuiet(Request req) {
+ String bearerToken = extractBearerToken(req.header("Authorization"));
+ if (bearerToken != null) {
+ try {
+ return validator.validate(bearerToken);
+ } catch (Exception ignored) {
+ return null;
+ }
+ }
+
+ String sessionId = cookieValue(req, "oidc_session");
+ if (sessionId != null) {
+ Optional found = config.sessionStore().find(sessionId);
+ if (found.isPresent()) {
+ OidcSession session = found.get();
+ if (!session.isAccessTokenExpired())
+ return session.claims();
+ if (session.refreshToken() != null) {
+ try {
+ OidcSession refreshed = doRefresh(session);
+ config.sessionStore().save(refreshed);
+ return refreshed.claims();
+ } catch (Exception ignored) { }
+ }
+ config.sessionStore().delete(sessionId);
+ }
+ }
+ return null;
+ }
+
+ /**
+ * Returns claims on success, or {@code null} if a redirect was already written to
+ * {@code res}. Throws {@link HttpException} 401/403 for API clients.
+ */
+ private Map resolve(Request req, Response res) {
+ return resolve(req, res, null);
+ }
+
+ private Map resolve(Request req, Response res, String resourceMetadataPath) {
+ // 1. Bearer token
+ String bearerToken = extractBearerToken(req.header("Authorization"));
+ if (bearerToken != null) {
+ try {
+ return validator.validate(bearerToken);
+ } catch (HttpException e) {
+ res.header("WWW-Authenticate", invalidTokenChallenge(req, resourceMetadataPath));
+ throw e;
+ }
+ }
+
+ // 2. Session cookie
+ String sessionId = cookieValue(req, "oidc_session");
+ if (sessionId != null) {
+ Optional found = config.sessionStore().find(sessionId);
+ if (found.isPresent()) {
+ OidcSession session = found.get();
+
+ if (!session.isAccessTokenExpired())
+ return session.claims();
+
+ // Access token expired — try silent refresh
+ if (session.refreshToken() != null) {
+ try {
+ OidcSession refreshed = doRefresh(session);
+ config.sessionStore().save(refreshed);
+ return refreshed.claims();
+ } catch (Exception ignored) {
+ // Refresh failed — fall through to re-authenticate
+ }
+ }
+ config.sessionStore().delete(sessionId);
+ }
+ }
+
+ // 3. No valid credentials
+ String accept = req.header("Accept");
+ if (accept != null && accept.contains("application/json")) {
+ res.header("WWW-Authenticate", bearerChallenge(req, resourceMetadataPath));
+ throw HttpException.unauthorized();
+ }
+
+ // Browser — redirect to login, preserving the original URL in state
+ String loginUrl = config.routePrefix() + "/login?redirect="
+ + URLEncoder.encode(req.path(), StandardCharsets.UTF_8);
+ res.redirect(loginUrl);
+ return null;
+ }
+
+ private OidcSession doRefresh(OidcSession old) throws Exception {
+ OidcTokenResponse tokens = tokenClient.refresh(
+ meta.tokenEndpoint(), old.refreshToken());
+
+ Map claims = mergeRefreshedClaims(tokens, old);
+
+ return new OidcSession(
+ old.id(),
+ tokens.accessToken(),
+ tokens.idToken() != null ? tokens.idToken() : old.idToken(),
+ tokens.refreshToken() != null ? tokens.refreshToken() : old.refreshToken(),
+ Instant.now().plusSeconds(tokens.expiresIn()),
+ claims
+ );
+ }
+
+ static String extractBearerToken(String authorizationHeader) {
+ if (authorizationHeader == null) return null;
+ int len = authorizationHeader.length();
+ int start = 0;
+ while (start < len && Character.isWhitespace(authorizationHeader.charAt(start))) start++;
+ int schemeEnd = start + BEARER.length();
+ if (schemeEnd > len || !authorizationHeader.regionMatches(true, start, BEARER, 0, BEARER.length())) {
+ return null;
+ }
+ if (schemeEnd == len || !Character.isWhitespace(authorizationHeader.charAt(schemeEnd))) {
+ return null;
+ }
+ int tokenStart = schemeEnd;
+ while (tokenStart < len && Character.isWhitespace(authorizationHeader.charAt(tokenStart))) tokenStart++;
+ if (tokenStart >= len) return null;
+ int tokenEnd = len;
+ while (tokenEnd > tokenStart && Character.isWhitespace(authorizationHeader.charAt(tokenEnd - 1))) tokenEnd--;
+ return tokenEnd > tokenStart ? authorizationHeader.substring(tokenStart, tokenEnd) : null;
+ }
+
+ String bearerChallenge() {
+ return bearerChallenge(null, null);
+ }
+
+ private String bearerChallenge(Request req, String resourceMetadataPath) {
+ String base = BEARER + " realm=\"" + quoted(config.schemeName()) + "\"";
+ if (resourceMetadataPath == null) return base;
+ return base + ", resource_metadata=\"" + quoted(absoluteSelf(req, resourceMetadataPath)) + "\"";
+ }
+
+ String invalidTokenChallenge() {
+ return invalidTokenChallenge(null, null);
+ }
+
+ private String invalidTokenChallenge(Request req, String resourceMetadataPath) {
+ return bearerChallenge(req, resourceMetadataPath) + ", error=\"invalid_token\"";
+ }
+
+ private String absoluteSelf(Request req, String path) {
+ if (!path.startsWith("/")) return path;
+ return selfOrigin(req, config.selfScheme()) + path;
+ }
+
+ /**
+ * {@code scheme://host} clients actually reach this app on — the basis for every absolute
+ * URL it publishes about itself (OAuth2 {@code redirect_uri}, the RFC 9728 resource
+ * identifier and the {@code resource_metadata} challenge). Behind a reverse proxy the
+ * request's own {@code Host} is the upstream address the proxy dialled, so
+ * {@code X-Forwarded-Host}/{@code -Proto} win whenever present: without them the app would
+ * name an address no client can resolve, and OAuth2 discovery fails with no error anyone
+ * can trace back to here. Trusted unconditionally — a caller able to reach this app without
+ * passing the proxy can do worse than spoof a self URL.
+ */
+ public static String selfOrigin(Request req, String fallbackScheme) {
+ String forwardedHost = req.header("X-Forwarded-Host");
+ if (forwardedHost == null) return fallbackScheme + "://" + req.header("Host");
+ String forwardedProto = req.header("X-Forwarded-Proto");
+ return (forwardedProto != null ? forwardedProto : fallbackScheme) + "://" + forwardedHost;
+ }
+
+ private static String spaceDelimited(String[] values) {
+ if (values == null || values.length == 0) return "";
+ StringBuilder sb = new StringBuilder();
+ for (int i = 0; i < values.length; i++) {
+ if (i > 0) sb.append(' ');
+ sb.append(values[i]);
+ }
+ return sb.toString();
+ }
+
+ private static String quoted(String value) {
+ StringBuilder out = new StringBuilder(value.length() + 8);
+ for (int i = 0; i < value.length(); i++) {
+ char c = value.charAt(i);
+ if (c == '"' || c == '\\') out.append('\\');
+ out.append(c);
+ }
+ return out.toString();
+ }
+
+ private static Map mergeRefreshedClaims(OidcTokenResponse tokens, OidcSession old) {
+ Map merged = new HashMap<>();
+ // Fall back to old claims first, then overlay fresh token claims
+ merged.putAll(old.claims());
+ if (tokens.accessToken() != null)
+ merged.putAll(JwtUtils.parseClaims(tokens.accessToken()));
+ if (tokens.idToken() != null)
+ merged.putAll(JwtUtils.parseClaims(tokens.idToken()));
+ return Map.copyOf(merged);
+ }
+
+ // -- Shared cookie utility (also used by OidcExtension) -------------------
+
+ static String cookieValue(Request req, String name) {
+ String header = req.header("Cookie");
+ if (header == null || header.isBlank()) return null;
+ int len = header.length();
+ int start = 0;
+ while (start < len) {
+ int semi = header.indexOf(';', start);
+ int end = semi < 0 ? len : semi;
+ int eq = header.indexOf('=', start);
+ if (eq > start && eq < end) {
+ int ns = start, ne = eq;
+ while (ns < ne && header.charAt(ns) == ' ') ns++;
+ while (ne > ns && header.charAt(ne-1) == ' ') ne--;
+ if (ne - ns == name.length() && header.regionMatches(ns, name, 0, name.length()))
+ return header.substring(eq + 1, end).strip();
+ }
+ start = end + 1;
+ }
+ return null;
+ }
+}
diff --git a/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/flash/ext/oidc/OidcExtension.java b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/flash/ext/oidc/OidcExtension.java
index 10502f7..133c152 100644
--- a/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/flash/ext/oidc/OidcExtension.java
+++ b/flash-extensions/flash-ext-oidc/src/main/java/dev/relism/flash/ext/oidc/OidcExtension.java
@@ -4,6 +4,12 @@ import dev.relism.flash.ext.openapi.OpenApiContributor;
import dev.relism.flash.ext.openapi.OpenApiContributorRegistry;
import dev.relism.flash.ext.openapi.OpenApiOperationContribution;
import dev.relism.flash.ext.openapi.OpenApiResponseContribution;
+import dev.relism.flash.ext.auth.AuthConfig;
+import dev.relism.flash.ext.auth.AuthMiddleware;
+import dev.relism.flash.ext.auth.AuthPolicy;
+import dev.relism.flash.ext.auth.Authenticated;
+import dev.relism.flash.ext.auth.RolesAllowed;
+import dev.relism.flash.ext.auth.ScopesAllowed;
import dev.relism.flash.extension.FlashContext;
import dev.relism.flash.extension.FlashExtension;
import dev.relism.flash.extension.FlashRegistrar;
@@ -28,7 +34,8 @@ import java.util.*;
* At {@link #provide}, the extension:
*
* - Fetches the provider discovery document — fail-fast at startup.
- * - Provides {@link OidcMiddleware} and {@link JwtValidator} in the context.
+ * - Provides {@link AuthMiddleware}, {@link OidcCredentialSource} and {@link JwtValidator}
+ * in the context.
* - Registers annotation processors for {@link Authenticated}, {@link RolesAllowed}
* and {@link ScopesAllowed}.
*
@@ -56,7 +63,7 @@ import java.util.*;
* }
*/
public class OidcExtension implements FlashExtension {
- private static final MiddlewareKey POLICY = MiddlewareKey.of("flash.oidc.policy");
+ private static final MiddlewareKey POLICY = MiddlewareKey.of("flash.auth.policy");
private final OidcConfig config;
@@ -65,7 +72,8 @@ public class OidcExtension implements FlashExtension {
private OidcStateStore stateStore;
private TokenClient tokenClient;
private JwtValidator validator;
- private OidcMiddleware oidcMw;
+ private OidcCredentialSource source;
+ private AuthMiddleware authMw;
public OidcExtension(OidcConfig config) {
this.config = config;
@@ -87,14 +95,19 @@ public class OidcExtension implements FlashExtension {
validator = new JwtValidator(meta.jwksUri(), config.issuer(), config.clientId(), config.algorithm(), http);
stateStore = new OidcStateStore();
tokenClient = new TokenClient(http, config);
- oidcMw = new OidcMiddleware(validator, config, meta, tokenClient);
+ source = new OidcCredentialSource(validator, config, meta, tokenClient);
+ authMw = new AuthMiddleware(AuthConfig.builder()
+ .rolesClaimPath(config.rolesClaimPath())
+ .scopeClaimPaths(config.scopeClaimPaths())
+ .build(), source);
- ctx.provide(OidcMiddleware.class, oidcMw);
- ctx.provide(JwtValidator.class, validator);
+ ctx.provide(AuthMiddleware.class, authMw);
+ ctx.provide(OidcCredentialSource.class, source);
+ ctx.provide(JwtValidator.class, validator);
ctx.addAnnotationProcessor(handlerClass -> {
- OidcAuthPolicy policy = OidcAuthPolicy.compileFromAnnotations(handlerClass);
- return policy != null ? List.of(MiddlewareNode.of(POLICY, oidcMw.policyMiddleware(policy))) : List.of();
+ AuthPolicy policy = AuthPolicy.compileFromAnnotations(handlerClass);
+ return policy != null ? List.of(MiddlewareNode.of(POLICY, authMw.authorize(policy))) : List.of();
});
ctx.onReady(() -> registerRoutes(app, ctx));
}
@@ -178,7 +191,7 @@ public class OidcExtension implements FlashExtension {
// ── POST {prefix}/logout ──────────────────────────────────────────────
// Invalidates the local session and redirects to end_session_endpoint.
app.post(prefix + "/logout", (req, res) -> {
- String sessionId = OidcMiddleware.cookieValue(req, "oidc_session");
+ String sessionId = OidcCredentialSource.cookieValue(req, "oidc_session");
String idTokenHint = null;
if (sessionId != null) {
@@ -253,7 +266,7 @@ public class OidcExtension implements FlashExtension {
private String absoluteSelf(Request req, String uri) {
if (!uri.startsWith("/")) return uri;
- return OidcMiddleware.selfOrigin(req, config.selfScheme()) + uri;
+ return OidcCredentialSource.selfOrigin(req, config.selfScheme()) + uri;
}
private static String enc(String v) {
@@ -299,12 +312,12 @@ public class OidcExtension implements FlashExtension {
OpenApiOperationContribution.Builder out =
OpenApiOperationContribution.builder();
- ListResolution order on each request: - *
{@code
- * // Manual use on a lambda route:
- * OidcMiddleware oidc = app.ctx().require(OidcMiddleware.class);
- * app.get("/api/me", (req, res) -> ClaimsHolder.claim("sub"), oidc.protect());
- * app.delete("/admin/users/{id}", handler, oidc.requireRole("admin"));
- * }
- */
-public class OidcMiddleware {
-
- private static final String BEARER = "Bearer";
-
- private final JwtValidator validator;
- private final OidcConfig config;
- private final OidcProviderMetadata meta;
- private final TokenClient tokenClient;
- private final String[] roleClaimPathParts;
- private final String[][] scopeClaimPathParts;
-
- OidcMiddleware(JwtValidator validator, OidcConfig config,
- OidcProviderMetadata meta, TokenClient tokenClient) {
- this.validator = validator;
- this.config = config;
- this.meta = meta;
- this.tokenClient = tokenClient;
- this.roleClaimPathParts = splitClaimPath(config.rolesClaimPath());
- this.scopeClaimPathParts = splitClaimPaths(config.scopeClaimPaths());
- }
-
- // -- Public API -----------------------------------------------------------
-
- /** The single configured claim path used by every transport for role checks. */
- public String rolesClaimPath() { return config.rolesClaimPath(); }
-
- /**
- * Validates the bearer token or session cookie. Browser clients are redirected
- * to the login page on failure; API clients receive 401.
- */
- public Middleware protect() {
- return protect(null);
- }
-
- /**
- * Like {@link #protect()}, but a 401 challenge also carries {@code resource_metadata}
- * (RFC 9728 §5.1), resolved against this request's own scheme/host exactly like
- * {@link OidcExtension}'s redirect URIs. {@code resourceMetadataPath} is an absolute path
- * (e.g. {@code "/.well-known/oauth-protected-resource/mcp"}); pass {@code null} for plain
- * challenges. Used by {@code flash-ext-mcp} to make its Protected Resource Metadata
- * document discoverable straight from the {@code WWW-Authenticate} header, per the MCP
- * Authorization spec.
- */
- public Middleware protect(String resourceMetadataPath) {
- return next -> (req, res) -> {
- Map{@code
- * app.get("/", handler, oidc.optional());
- * // Inside handler: ClaimsHolder.user() is non-null iff the user is logged in.
- * }
- */
- public Middleware optional() {
- return next -> (req, res) -> {
- Map