Package org.apache.juneau.rest.server.auth.oidc.rp

Class OidcRelyingParty

java.lang.Object
org.apache.juneau.rest.server.auth.oidc.rp.OidcRelyingParty
public class OidcRelyingParty extends Object
Facade orchestrating an OpenID Connect Authorization-Code-with-PKCE Relying Party login flow on top of the juneau-rest-server-auth-oauth building blocks.

A single instance wires the login / callback / logout endpoints plus the session SPI for one IdP. The application mounts the three endpoints as explicit @RestGet methods that delegate to this facade — there are no auto-mounted servlet routes (URL ownership stays with the app):

@Rest(path="/auth") public class LoginResource extends BasicRestServlet { private final OidcRelyingParty rp = OidcRelyingParty.create() .issuer(URI.create("https://accounts.google.com")) .clientId("web-app") .clientSecret(env("OIDC_CLIENT_SECRET")) .redirectUri(URI.create("https://app.example.com/auth/callback")) .scope("openid", "profile", "email") .sessionStore(SignedCookieSessionStore.create().signingKey(env("SESSION_KEY")).build()) .build(); @RestGet(path="/login") public void login(RestRequest req, RestResponse res) throws Exception { rp.startLogin(req, res); } @RestGet(path="/callback") public void callback(RestRequest req, RestResponse res) throws Exception { rp.completeLogin(req, res); } @RestGet(path="/logout") public void logout(RestRequest req, RestResponse res) throws Exception { rp.logout(req, res); } }

Register authFilter() in the servlet filter chain (or AuthFilterChain) so each request resolves the session cookie into a ClaimsPrincipal for RoleBasedRestGuard / @Auth Principal.

Security
  • state and nonce are single-use and TTL-bounded (default 5 min); a missing / replayed value fails the callback.
  • PKCE S256 is enforced end-to-end.
  • The ID token is validated for signature, iss, aud/azp, exp, and nonce (see IdTokenValidatorAdapter).
  • The session id is freshly generated on login (no pre-auth fixation).
  • Auth responses set Cache-Control: no-store; tokens are never logged.
  • The session cookie is HttpOnly + Secure + SameSite by default.
See Also:
Since:
10.0.0

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    OidcRelyingParty.Builder
    Builder.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    OidcRelyingParty(OidcRelyingParty.Builder b)
    Constructor.

  • Method Summary

    Modifier and Type
    Method
    Description
    OidcSessionAuthFilter
    authFilter()
    Returns a request-time AuthFilter that resolves this RP's session cookie into a ClaimsPrincipal.
    int
    backChannelLogout(String logoutToken)
    Processes an IdP-pushed OpenID Connect back-channel logout token, invalidating the matching server-side session(s).
    void
    completeLogin(jakarta.servlet.http.HttpServletRequest req, jakarta.servlet.http.HttpServletResponse res)
    Completes the login flow: parses the callback, verifies + consumes state, exchanges the code (PKCE), validates the ID token (signature / iss / aud / exp / nonce), creates a session, sets the session cookie, and redirects to the application.
    String
    cookieName()
    Returns the session cookie name.
    static OidcRelyingParty.Builder
    create()
    Static creator.
    void
    logout(jakarta.servlet.http.HttpServletRequest req, jakarta.servlet.http.HttpServletResponse res)
    Logs the user out: invalidates the session, clears the session cookie, and (when the IdP advertises an end-session endpoint) redirects through it; otherwise redirects to the post-logout target.
    Optional<OidcSession>
    refresh(jakarta.servlet.http.HttpServletRequest req, jakarta.servlet.http.HttpServletResponse res)
    Refreshes the current session's access token using the rotating-refresh-token grant.
    SessionStore
    sessionStore()
    Returns the configured session store.
    void
    startLogin(jakarta.servlet.http.HttpServletRequest req, jakarta.servlet.http.HttpServletResponse res)
    Begins the login flow: generates state + nonce + PKCE verifier, stores them single-use, and redirects the user-agent to the IdP authorization endpoint.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

  • Method Details

    • create

      public static OidcRelyingParty.Builder create()
      Static creator.
      Returns:
      A new builder.

    • startLogin

      public void startLogin(jakarta.servlet.http.HttpServletRequest req, jakarta.servlet.http.HttpServletResponse res) throws IOException
      Begins the login flow: generates state + nonce + PKCE verifier, stores them single-use, and redirects the user-agent to the IdP authorization endpoint.
      Parameters:
      req - The HTTP request. An optional redirect query parameter (a safe relative path) is remembered as the post-login target.
      res - The HTTP response.
      Throws:
      IOException - If the redirect cannot be written.

    • completeLogin

      public void completeLogin(jakarta.servlet.http.HttpServletRequest req, jakarta.servlet.http.HttpServletResponse res) throws IOException, AuthenticationException
      Completes the login flow: parses the callback, verifies + consumes state, exchanges the code (PKCE), validates the ID token (signature / iss / aud / exp / nonce), creates a session, sets the session cookie, and redirects to the application.
      Parameters:
      req - The callback HTTP request (carrying code + state).
      res - The HTTP response.
      Throws:
      IOException - If the redirect cannot be written.
      AuthenticationException - If the callback is an error, the state is missing / replayed, or ID-token validation fails.

    • logout

      public void logout(jakarta.servlet.http.HttpServletRequest req, jakarta.servlet.http.HttpServletResponse res) throws IOException
      Logs the user out: invalidates the session, clears the session cookie, and (when the IdP advertises an end-session endpoint) redirects through it; otherwise redirects to the post-logout target.
      Parameters:
      req - The HTTP request.
      res - The HTTP response.
      Throws:
      IOException - If the redirect cannot be written.

    • refresh

      public Optional<OidcSession> refresh(jakarta.servlet.http.HttpServletRequest req, jakarta.servlet.http.HttpServletResponse res)
      Refreshes the current session's access token using the rotating-refresh-token grant.

      Replaces the stored refresh token with the one the IdP returns; if the IdP rejects the refresh (e.g. a rotated token was reused / revoked), the session is invalidated. Only applies to stores that retain tokens (server-side); SignedCookieSessionStore sessions carry no tokens and yield Optional.empty().

      Parameters:
      req - The HTTP request.
      res - The HTTP response (a refreshed session resets the cookie).
      Returns:
      The refreshed session, or Optional.empty() if there was nothing to refresh.

    • backChannelLogout

      public int backChannelLogout(String logoutToken) throws AuthenticationException
      Processes an IdP-pushed OpenID Connect back-channel logout token, invalidating the matching server-side session(s).

      The logout token is validated via Nimbus's LogoutTokenValidator (signature against the JWKS, iss, aud, the back-channel events claim, and the sub / sid presence rule). Sessions are then revoked by sid (preferred, single-session) or sub (all of a subject's sessions).

      Requires a server-side-revocable store — the default SignedCookieSessionStore cannot satisfy back-channel logout because a stateless cookie is not server-revocable.

      Parameters:
      logoutToken - The raw logout_token JWT pushed by the IdP. Must not be null or blank.
      Returns:
      The number of sessions invalidated.
      Throws:
      AuthenticationException - If the logout token fails validation.
      IllegalStateException - If the configured session store does not support server-side revocation.

    • authFilter

      public OidcSessionAuthFilter authFilter()
      Returns a request-time AuthFilter that resolves this RP's session cookie into a ClaimsPrincipal.
      Returns:
      A new OidcSessionAuthFilter bound to this RP's session store + cookie name.

    • sessionStore

      public SessionStore sessionStore()
      Returns the configured session store.
      Returns:
      The session store.

    • cookieName

      public String cookieName()
      Returns the session cookie name.
      Returns:
      The cookie name.