adapting documentation

cuioss · Aug 23, 2024 · 2c58006 · 2c58006
1 parent 9aeb8ae
commit 2c58006
Show file tree

Hide file tree

Showing 17 changed files with 159 additions and 127 deletions.
diff --git a/README.adoc b/README.adoc
@@ -1,4 +1,5 @@
 = cui-portal-core
+:toc:
 
 == Status
 

diff --git a/modules/authentication/README.adoc b/modules/authentication/README.adoc
@@ -2,14 +2,33 @@
 
 == What is it?
 
-Groups all modules providing authorization for the cuioss-portal.
+Groups all modules providing authentication and authorization for the cuioss-portal.
 
-== Features / Modules
+Within your code, you usually interact with types from link:portal-authentication-api/[portal-authentication-api].
 
-link:portal-authentication-api/[portal-authentication-api]
+It is assumed that at least one of the runtime modules is available:
 
-link:portal-authentication-dummy/[portal-authentication-dummy]
+* link:portal-authentication-oauth/[portal-authentication-oauth]: Default implementation for integrating against oauth2 / OICD.
 
-link:portal-authentication-mock/[portal-authentication-mock]
+* link:portal-authentication-dummy/[portal-authentication-dummy]:
+Implementation for cases where it is only needed technically.
+The implementation will always return a not-authenticated UserInfo.
+In contrast to 'link:portal-authentication-mock/[portal-authentication-mock]' this module can be used in production environments.
 
-link:portal-authentication-oauth/[portal-authentication-oauth]
+* link:portal-authentication-mock/[portal-authentication-mock]:
+Implementation for cases where it is only needed technically or for documentation purpose.
+In contrast to 'portal-authentication-dummy' this module must never be used in production environments.
+
+== Usage
+
+The central object ist the `@Dependent`-scoped `AuthenticatedUserInfo`
+that has a number of methods interacting with the logged-in user.
+
+[source,java]
+----
+    @Inject
+    private AuthenticatedUserInfo userProvider;
+
+----
+
+See link:portal-authentication-api/[portal-authentication-api] for more details
diff --git a/modules/authentication/portal-authentication-api/README.adoc b/modules/authentication/portal-authentication-api/README.adoc
@@ -0,0 +1,28 @@
+= portal-authentication-api
+
+== What is it?
+Provides types for handling authentication and authorization related information within the cui-portal.
+It is meant as an abstraction over different ways of authentication and authorization,
+see link:../[portal-authentication] for the different runtimes.
+
+== Maven Coordinates
+
+[source, xml]
+----
+    <dependency>
+        <groupId>de.cuioss.portal.authentication</groupId>
+        <artifactId>portal-authentication-api</artifactId>
+    </dependency>
+----
+
+== Usage
+
+The central object ist the `@Dependent`-scoped `AuthenticatedUserInfo`
+that has a number of methods interacting with the logged-in user.
+
+[source,java]
+----
+    @Inject
+    private AuthenticatedUserInfo userProvider;
+
+----
diff --git a/...thentication-api/src/main/java/de/cuioss/portal/authentication/AuthenticatedUserInfo.java b/...thentication-api/src/main/java/de/cuioss/portal/authentication/AuthenticatedUserInfo.java
@@ -31,14 +31,6 @@
 // (coherence).
 public interface AuthenticatedUserInfo extends Serializable {
 
-    /**
-     * Bean name for looking up instances.
-     *
-     * @deprecated owolff: Should solely be used with types
-     */
-    @Deprecated(forRemoval = true)
-    String BEAN_NAME = "authenticatedUserInfoBean";
-
     /**
      * Returns <code>true</code> in case of user is authenticated already and
      * <code>false</code> otherwise.

diff --git a/...n/portal-authentication-api/src/main/java/de/cuioss/portal/authentication/LoginEvent.java b/...n/portal-authentication-api/src/main/java/de/cuioss/portal/authentication/LoginEvent.java
@@ -15,16 +15,15 @@
  */
 package de.cuioss.portal.authentication;
 
-import java.io.Serial;
-import java.io.Serializable;
-
 import lombok.Builder;
 import lombok.NonNull;
 import lombok.Value;
 
+import java.io.Serial;
+import java.io.Serializable;
+
 /**
- * To signal successful / failed login and logout events (e.g. to the atna
- * logger).
+ * To signal successful / failed login and logout events (e.g., to the audit-logger).
  */
 @Value
 @Builder
@@ -37,18 +36,24 @@ public class LoginEvent implements Serializable {
      * Identifies the concrete action that was executed
      */
     public enum Action {
-        /** Login was successful. */
+        /**
+         * Login was successful.
+         */
         LOGIN_SUCCESS,
 
-        /** Login failed. */
+        /**
+         * Login failed.
+         */
         LOGIN_FAILED,
-        /** User logged out. */
+        /**
+         * User logged out.
+         */
         LOGOUT
     }
 
     // Only needed for LOGIN_FAILED
-    private String username;
+    String username;
 
     @NonNull
-    private Action action;
+    Action action;
 }
diff --git a/...al-authentication-api/src/main/java/de/cuioss/portal/authentication/PortalLoginEvent.java b/...al-authentication-api/src/main/java/de/cuioss/portal/authentication/PortalLoginEvent.java
@@ -15,26 +15,23 @@
  */
 package de.cuioss.portal.authentication;
 
-import static java.lang.annotation.ElementType.FIELD;
-import static java.lang.annotation.ElementType.METHOD;
-import static java.lang.annotation.ElementType.PARAMETER;
-import static java.lang.annotation.ElementType.TYPE;
-import static java.lang.annotation.RetentionPolicy.RUNTIME;
+import jakarta.inject.Qualifier;
 
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
-import jakarta.inject.Qualifier;
+import static java.lang.annotation.ElementType.*;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Defines events that will be fired at login attempt. The payload is
- * {@link LoginEvent}.
+ * Defines events that will be fired at a login attempt.
+ * The payload is {@link LoginEvent}.
  *
  * @author Matthias Walliczek
  */
 @Qualifier
 @Retention(RUNTIME)
-@Target({ TYPE, METHOD, FIELD, PARAMETER })
+@Target({TYPE, METHOD, FIELD, PARAMETER})
 public @interface PortalLoginEvent {
 
 }
diff --git a/...-authentication-api/src/main/java/de/cuioss/portal/authentication/PortalUserEnricher.java b/...-authentication-api/src/main/java/de/cuioss/portal/authentication/PortalUserEnricher.java
@@ -15,16 +15,14 @@
  */
 package de.cuioss.portal.authentication;
 
-import java.util.function.Function;
-
-import jakarta.servlet.http.HttpServletRequest;
-
 import de.cuioss.portal.authentication.facade.AuthenticationFacade;
 import de.cuioss.portal.common.priority.PortalPriorities;
+import jakarta.servlet.http.HttpServletRequest;
+
+import java.util.function.Function;
 
 /**
- * To enrich an {@link AuthenticatedUserInfo} created by the
- * {@link AuthenticationFacade}.
+ * To enrich an {@link AuthenticatedUserInfo} created by the {@link AuthenticationFacade}.
  * <p>
  * Implementations of this interface will be called as part of
  * {@link AuthenticationFacade#retrieveCurrentAuthenticationContext(HttpServletRequest)}.
@@ -34,7 +32,7 @@
  * <p>
  * The highest priority is called last.
  * <p>
- * The enriched {@linkplain AuthenticatedUserInfo} should be returned as result.
+ * The enriched {@linkplain AuthenticatedUserInfo} should be returned as a result.
  * <p>
  * If no enrichment is done, the same object should be returned, but never null.
  */

diff --git a/...tal-authentication-api/src/main/java/de/cuioss/portal/authentication/UserChangeEvent.java b/...tal-authentication-api/src/main/java/de/cuioss/portal/authentication/UserChangeEvent.java
@@ -15,16 +15,13 @@
  */
 package de.cuioss.portal.authentication;
 
-import static java.lang.annotation.ElementType.FIELD;
-import static java.lang.annotation.ElementType.METHOD;
-import static java.lang.annotation.ElementType.PARAMETER;
-import static java.lang.annotation.ElementType.TYPE;
-import static java.lang.annotation.RetentionPolicy.RUNTIME;
+import jakarta.inject.Qualifier;
 
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
-import jakarta.inject.Qualifier;
+import static java.lang.annotation.ElementType.*;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
  * Defines events that will be fired on changes on user-credentials. The payload
@@ -34,7 +31,7 @@
  */
 @Qualifier
 @Retention(RUNTIME)
-@Target({ TYPE, METHOD, FIELD, PARAMETER })
+@Target({TYPE, METHOD, FIELD, PARAMETER})
 public @interface UserChangeEvent {
 
 }
diff --git a/...cation-api/src/main/java/de/cuioss/portal/authentication/facade/AuthenticationFacade.java b/...cation-api/src/main/java/de/cuioss/portal/authentication/facade/AuthenticationFacade.java
@@ -20,8 +20,8 @@
 import de.cuioss.portal.authentication.AuthenticatedUserInfo;
 
 /**
- * Basic interface for cui-portals authentication mechanism. This variant is
- * used by sso logins
+ * Basic interface for the cui-portals authentication mechanism.
+ * This variant is used by sso logins
  *
  * @author Matthias Walliczek
  *
@@ -33,7 +33,7 @@ public interface AuthenticationFacade {
      *
      * @param servletRequest The servlet request.
      * @return Returns <code>null</code> in case no authentication has taken place.
-     *         In case of a existing authentication a populated
+     *         In case of an existing authentication a populated
      *         {@link AuthenticatedUserInfo} instance is returned.
      */
     AuthenticatedUserInfo retrieveCurrentAuthenticationContext(HttpServletRequest servletRequest);

diff --git a/...ation-api/src/main/java/de/cuioss/portal/authentication/facade/AuthenticationResults.java b/...ation-api/src/main/java/de/cuioss/portal/authentication/facade/AuthenticationResults.java
@@ -26,22 +26,22 @@
 
 /**
  * Provides constants for all authentication-modules as there are
- * {@link AuthenticatedUserInfo} for not logged in user and keys for the
+ * {@link AuthenticatedUserInfo} for not logged-in user and keys for the
  * resource bundles, defined at cdi-portal-core-impl module
  *
  * @author Oliver Wolff
  */
 @UtilityClass
 public class AuthenticationResults {
 
-    private static final String NOT_LOGGED_IN2 = "Not logged in";
+    private static final String NOT_LOGGED_IN_MESSAGE = "Not logged in";
 
     /**
      * An {@link AuthenticatedUserInfo} with
      * {@link AuthenticatedUserInfo#isAuthenticated()} returning false
      */
     public static final AuthenticatedUserInfo NOT_LOGGED_IN = BaseAuthenticatedUserInfo.builder()
-            .displayName(NOT_LOGGED_IN2).authenticated(false).build();
+            .displayName(NOT_LOGGED_IN_MESSAGE).authenticated(false).build();
 
     /**
      * The key for the message "The credentials you provided are not complete".
@@ -55,13 +55,13 @@ public class AuthenticationResults {
     public static final String KEY_INVALID_CONFIGURATION = "portal.authentication.error.invalid_configuration";
 
     /**
-     * The key for the message "Cannot login with the supplied user details. Please
+     * The key for the message "Cannot log in with the supplied user details. Please
      * check your inputs".
      */
     public static final String KEY_INVALID_CREDENTIALS = "page.login.message.loginFailure";
 
     /**
-     * The key for the general Can not login message.
+     * The key for the general Cannot log in message.
      */
     public static final String KEY_UNABLE_TO_LOGIN = "portal.authentication.error.unable_to_login";
 
@@ -83,36 +83,36 @@ public class AuthenticationResults {
 
     /**
      * @param reason   the text to be displayed as reason.
-     * @param username the username entered by the user (e.g. to be added to the
+     * @param username the username entered by the user (e.g., to be added to the
      *                 atna event)
      * @param cause    the optional throwable to be wrapped
      *
      * @return {@link ResultObject} with {@link ResultObject#getState()} is
      *         {@code RequestResultState#ERROR}, the given reason as message and the
      *         default result {@link #NOT_LOGGED_IN}
      */
-    public static final ResultObject<AuthenticatedUserInfo> invalidResult(final String reason, final String username,
-            final Throwable cause) {
+    public static ResultObject<AuthenticatedUserInfo> invalidResult(final String reason, final String username,
+                                                                    final Throwable cause) {
         return new ResultObject.Builder<AuthenticatedUserInfo>()
-                .validDefaultResult(BaseAuthenticatedUserInfo.builder().displayName(NOT_LOGGED_IN2).identifier(username)
+                .validDefaultResult(BaseAuthenticatedUserInfo.builder().displayName(NOT_LOGGED_IN_MESSAGE).identifier(username)
                         .authenticated(false).build())
                 .state(ResultState.ERROR).resultDetail(new ResultDetail(new DisplayName(reason), cause)).build();
     }
 
     /**
      * @param reasonKey the key for resolving the reason text.
-     * @param username  the username entered by the user (e.g. to be added to the
+     * @param username  the username entered by the user (e.g., to be added to the
      *                  atna event)
      * @param cause     the optional throwable to be wrapped
      *
      * @return {@link ResultObject} with {@link ResultObject#getState()} is
      *         {@code RequestResultState#ERROR}, the given reason as message and the
      *         default result {@link #NOT_LOGGED_IN}
      */
-    public static final ResultObject<AuthenticatedUserInfo> invalidResultKey(final String reasonKey,
-            final String username, final Throwable cause) {
+    public static ResultObject<AuthenticatedUserInfo> invalidResultKey(final String reasonKey,
+                                                                       final String username, final Throwable cause) {
         return new ResultObject.Builder<AuthenticatedUserInfo>()
-                .validDefaultResult(BaseAuthenticatedUserInfo.builder().displayName(NOT_LOGGED_IN2).identifier(username)
+                .validDefaultResult(BaseAuthenticatedUserInfo.builder().displayName(NOT_LOGGED_IN_MESSAGE).identifier(username)
                         .authenticated(false).build())
                 .state(ResultState.ERROR).resultDetail(new ResultDetail(new LabeledKey(reasonKey), cause)).build();
     }
@@ -124,7 +124,7 @@ public static final ResultObject<AuthenticatedUserInfo> invalidResultKey(final S
      *         {@code RequestResultState#VALID}, the given reason userInfo as
      *         payload
      */
-    public static final ResultObject<AuthenticatedUserInfo> validResult(final AuthenticatedUserInfo userInfo) {
+    public static ResultObject<AuthenticatedUserInfo> validResult(final AuthenticatedUserInfo userInfo) {
         return new ResultObject.Builder<AuthenticatedUserInfo>().result(userInfo).state(ResultState.VALID).build();
     }
 }
diff --git a/...on-api/src/main/java/de/cuioss/portal/authentication/facade/BaseAuthenticationFacade.java b/...on-api/src/main/java/de/cuioss/portal/authentication/facade/BaseAuthenticationFacade.java
@@ -15,16 +15,15 @@
  */
 package de.cuioss.portal.authentication.facade;
 
-import static de.cuioss.tools.collect.CollectionLiterals.mutableList;
-
-import java.util.List;
-
-import jakarta.enterprise.inject.Instance;
-import jakarta.inject.Inject;
-
 import de.cuioss.portal.authentication.AuthenticatedUserInfo;
 import de.cuioss.portal.authentication.PortalUserEnricher;
 import de.cuioss.portal.common.priority.PortalPriorities;
+import jakarta.enterprise.inject.Instance;
+import jakarta.inject.Inject;
+
+import java.util.List;
+
+import static de.cuioss.tools.collect.CollectionLiterals.mutableList;
 
 /**
  * Abstract implementation to handle {@link PortalUserEnricher}s.
@@ -36,13 +35,13 @@ public abstract class BaseAuthenticationFacade implements AuthenticationFacade {
 
     /**
      * Enriches the given {@link AuthenticatedUserInfo} using the available
-     * {@link PortalUserEnricher} implemenentations that are part of the
+     * {@link PortalUserEnricher} implementations that are part of the
      * cdi-context.
      * <p>
      * The {@linkplain PortalUserEnricher} are sorted via {@link PortalPriorities}
      * if multiple instances are found.
      * <p>
-     * The enriched {@linkplain AuthenticatedUserInfo} is returned as result.
+     * The enriched {@linkplain AuthenticatedUserInfo} is returned as a result.
      *
      * @param authenticatedUserInfo the instance to enrich
      * @return the enriched instance