From 5773d87d65cfa756610bab04bbd5565ed5b66c9d Mon Sep 17 00:00:00 2001 From: ch4mpy Date: Fri, 24 Jan 2025 16:51:00 -1000 Subject: [PATCH] Improve spring-addons oidc client properties documentation --- .../SpringAddonsOidcClientProperties.java | 33 ++++++++++++------- 1 file changed, 22 insertions(+), 11 deletions(-) diff --git a/spring-addons-starter-oidc/src/main/java/com/c4_soft/springaddons/security/oidc/starter/properties/SpringAddonsOidcClientProperties.java b/spring-addons-starter-oidc/src/main/java/com/c4_soft/springaddons/security/oidc/starter/properties/SpringAddonsOidcClientProperties.java index adabeeefa..3c473e626 100644 --- a/spring-addons-starter-oidc/src/main/java/com/c4_soft/springaddons/security/oidc/starter/properties/SpringAddonsOidcClientProperties.java +++ b/spring-addons-starter-oidc/src/main/java/com/c4_soft/springaddons/security/oidc/starter/properties/SpringAddonsOidcClientProperties.java @@ -53,13 +53,13 @@ public class SpringAddonsOidcClientProperties { private List securityMatchers = List.of(); /** - * Fully qualified URI of the configured OAuth2 client. + * Fully qualified public URI of the configured OAuth2 client (through reverse proxy if any used). */ private URI clientUri = URI.create("/"); /** * URI at which a login can be performed. If left empty, ${client-uri}/login is used. Can be - * changed to the URI on a SPA or a mobile application deep-link + * changed to route for login in a SPA or a mobile application deep-link */ private Optional loginUri = Optional.empty(); @@ -80,8 +80,8 @@ public class SpringAddonsOidcClientProperties { private Optional loginErrorRedirectPath = Optional.empty(); /** - * Handling of invalid servlet sessions. The default behavior is to create a new - * (anonymous) session and to redirect to the same URI for a retry. + * Handling of invalid servlet sessions. The default behavior is to redirect to the same + * URI for a retry with a fresh (anonymous) session and cookie. */ private InvalidSessionProperties invalidSession = new InvalidSessionProperties(); @@ -325,29 +325,40 @@ public static class InvalidSessionProperties { @Data public static class OAuth2RedirectionProperties { /** - * Defines {@link AuthenticationEntryPoint} or {@link ServerAuthenticationEntryPoint} behavior + * Status of the response in the case where a request is made to a protected resource without a + * session cookie (or with a cookie for an anonymous session). This configures the + * {@link AuthenticationEntryPoint} or {@link ServerAuthenticationEntryPoint}. On a REST API (or + * a Gateway routing to a REST API), this should be configured to UNAUTHORIZED. */ private HttpStatus authenticationEntryPoint = HttpStatus.FOUND; /** - * Status for the 1st response in authorization code flow, with location to get authorization - * code from authorization server + * Status for the 1st response in authorization code flow, with a Location header containing an + * URI pointing to the authorization server "authorization" endpoint. When using Javascript on + * the frontend, this should be changed to something in the 2xx range for the frontend to + * "observe" this response and initiate a plain navigation (set window.location.href) instead of + * letting the browser follow with a cross-origin request. */ private HttpStatus preAuthorizationCode = HttpStatus.FOUND; /** - * Status for the response after authorization code, with location to the UI + * Status for the response after authorization code is exchanged for tokens. The Location header + * should point to the UI. The default value should be fine in most cases. */ private HttpStatus postAuthorizationCode = HttpStatus.FOUND; /** - * Status for the response after an authorization failure + * Status for the response after an authorization failure. The default value should be fine in + * most cases. */ private HttpStatus postAuthorizationFailure = HttpStatus.FOUND; /** - * Status for the response after BFF logout, with location to authorization server logout - * endpoint + * Status for the response after BFF logout, with Location header pointing to authorization + * server's "end_session_endpoint". When using Javascript on the frontend, this should be + * changed to something in the 2xx range for the frontend to "observe" this response and + * initiate a plain navigation (set window.location.href) instead of letting the browser follow + * with a cross-origin request. */ private HttpStatus rpInitiatedLogout = HttpStatus.FOUND; }