This is an automated email from the ASF dual-hosted git repository. rombert pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/sling-whiteboard.git
commit 0e07a1d083dd370dbbecb9129359ed967feb4b2a Author: Robert Munteanu <[email protected]> AuthorDate: Thu Jul 6 19:08:29 2023 +0300 oidc-rp: document the OidcClient --- org.apache.sling.servlets.oidc-rp/README.md | 1 + .../apache/sling/servlets/oidc_rp/OidcClient.java | 40 +++++++++++++++++++++- 2 files changed, 40 insertions(+), 1 deletion(-) diff --git a/org.apache.sling.servlets.oidc-rp/README.md b/org.apache.sling.servlets.oidc-rp/README.md index 9b5b9991..8b4cf0f7 100644 --- a/org.apache.sling.servlets.oidc-rp/README.md +++ b/org.apache.sling.servlets.oidc-rp/README.md @@ -17,6 +17,7 @@ objective is to simplify access to user and access tokens in a secure manner. - document usage for the supported OIDC providers; make sure to explain this is _not_ an authentication handler - provide a sample content package and instructions how to use - review security best practices +- investigate whether the OIDC entry point servlet is really needed ## Prerequisites diff --git a/org.apache.sling.servlets.oidc-rp/src/main/java/org/apache/sling/servlets/oidc_rp/OidcClient.java b/org.apache.sling.servlets.oidc-rp/src/main/java/org/apache/sling/servlets/oidc_rp/OidcClient.java index c7aef319..47967b00 100644 --- a/org.apache.sling.servlets.oidc-rp/src/main/java/org/apache/sling/servlets/oidc_rp/OidcClient.java +++ b/org.apache.sling.servlets.oidc-rp/src/main/java/org/apache/sling/servlets/oidc_rp/OidcClient.java @@ -20,13 +20,51 @@ import java.net.URI; import org.apache.sling.api.SlingHttpServletRequest; +/** + * A client for dealing with over-the-network OIDC concerns + * + * <p>This client is able to generate URLs and make network calls related to OIDC.</p> + * + */ public interface OidcClient { + /** + * Generates a local URI to the OIDC entry point servlet + * + * <p>The URI can be used as-is to send a redirect to the user and start the OIDC flow.</p> + * + * @param connection The connection to start the OIDC flow for + * @param request The current request + * @param redirectPath The local redirect path to use after completing the OIDC flow + * @return a local URI + * @throws OidcException in case anything goes wrong + */ URI getOidcEntryPointUri(OidcConnection connection, SlingHttpServletRequest request, String redirectPath) throws OidcException; + /** + * Generates a URI to the OIDC provider's authorization endpoint + * + * <p>The URI can be used as-is to start the OIDC flow directly on the identity provider's side.</p> + * + * @param connection The connection to start the OIDC flow for + * @param request The current request + * @param redirectUri The redirect path to use after completing the OIDC flow + * @return a remote URI + * @throws OidcException in case anything goes wrong + */ URI getAuthenticationRequestUri(OidcConnection connection, SlingHttpServletRequest request, URI redirectUri) throws OidcException; - // void /* TODO OIDCTokens */ getOidcTokens(OidcConnection connection, String authenticationCode) throws OidcException; + // OidcTokens getOidcTokens(OidcConnection connection, String authenticationCode) throws OidcException; + /** + * Refreshes the OIDC tokens based on the supplied refresh token + * + * <p>It is the responsibility of the invoker to persist the returned tokens.</p> + * + * @param connection The connection to start the OIDC flow for + * @param refreshToken An existing refresh token + * @return OIDC tokens + * @throws OidcException in case anything goes wrong + */ OidcTokens refreshTokens(OidcConnection connection, String refreshToken) throws OidcException; }
