From be69598a48f453fb85bae8da26faa7f76dba7d3e Mon Sep 17 00:00:00 2001
From: Lachlan Roberts <lachlan@webtide.com>
Date: Mon, 9 Sep 2019 14:57:35 +1000
Subject: [PATCH] add javadoc

Signed-off-by: Lachlan Roberts <lachlan@webtide.com>
---
 .../security/openid/OpenIdConfiguration.java  | 12 ++++++++++
 .../security/openid/OpenIdCredentials.java    | 10 ++++++++
 .../security/openid/OpenIdLoginService.java   | 23 +++++++++++++++++++
 3 files changed, 45 insertions(+)

diff --git a/jetty-openid/src/main/java/org/eclipse/jetty/security/openid/OpenIdConfiguration.java b/jetty-openid/src/main/java/org/eclipse/jetty/security/openid/OpenIdConfiguration.java
index 8284bb286ee..d68c862b731 100644
--- a/jetty-openid/src/main/java/org/eclipse/jetty/security/openid/OpenIdConfiguration.java
+++ b/jetty-openid/src/main/java/org/eclipse/jetty/security/openid/OpenIdConfiguration.java
@@ -29,6 +29,12 @@ import org.eclipse.jetty.util.ajax.JSON;
 import org.eclipse.jetty.util.log.Log;
 import org.eclipse.jetty.util.log.Logger;
 
+/**
+ * Holds the configuration for an OpenID Connect service.
+ *
+ * This uses the OpenID Provider URL with the path {@link #CONFIG_PATH} to discover
+ * the required information about the OIDC service.
+ */
 public class OpenIdConfiguration
 {
     private static final Logger LOG = Log.getLogger(OpenIdConfiguration.class);
@@ -44,6 +50,12 @@ public class OpenIdConfiguration
 
     private List<String> scopes = new ArrayList<>();
 
+    /**
+     * Create an OpenID configuration for a specific OIDC provider.
+     * @param provider The URL of the OpenID provider.
+     * @param clientId OAuth 2.0 Client Identifier valid at the Authorization Server.
+     * @param clientSecret The client secret known only by the Client and the Authorization Server.
+     */
     public OpenIdConfiguration(String provider, String clientId, String clientSecret)
     {
         this.openIdProvider = provider;
diff --git a/jetty-openid/src/main/java/org/eclipse/jetty/security/openid/OpenIdCredentials.java b/jetty-openid/src/main/java/org/eclipse/jetty/security/openid/OpenIdCredentials.java
index 7b787482ea3..5dbc406ce11 100644
--- a/jetty-openid/src/main/java/org/eclipse/jetty/security/openid/OpenIdCredentials.java
+++ b/jetty-openid/src/main/java/org/eclipse/jetty/security/openid/OpenIdCredentials.java
@@ -32,6 +32,16 @@ import org.eclipse.jetty.util.ajax.JSON;
 import org.eclipse.jetty.util.log.Log;
 import org.eclipse.jetty.util.log.Logger;
 
+/**
+ * <p>The credentials of an user to be authenticated with OpenID Connect. This will contain
+ * the OpenID ID Token and the OAuth 2.0 Access Token.</p>
+ *
+ * <p>
+ * This is constructed with an authorization code from the authentication request. This authorization code
+ * is then exchanged using {@link #redeemAuthCode()} for a response containing the ID Token and Access Token.
+ * The response is then validated against the {@link OpenIdConfiguration}.
+ * </p>
+ */
 public class OpenIdCredentials
 {
     private static final Logger LOG = Log.getLogger(OpenIdCredentials.class);
diff --git a/jetty-openid/src/main/java/org/eclipse/jetty/security/openid/OpenIdLoginService.java b/jetty-openid/src/main/java/org/eclipse/jetty/security/openid/OpenIdLoginService.java
index 0b80fe8d735..c2df0b02115 100644
--- a/jetty-openid/src/main/java/org/eclipse/jetty/security/openid/OpenIdLoginService.java
+++ b/jetty-openid/src/main/java/org/eclipse/jetty/security/openid/OpenIdLoginService.java
@@ -29,6 +29,13 @@ import org.eclipse.jetty.util.component.ContainerLifeCycle;
 import org.eclipse.jetty.util.log.Log;
 import org.eclipse.jetty.util.log.Logger;
 
+/**
+ * The implementation of {@link LoginService} required to use OpenID Connect.
+ *
+ * <p>
+ * Can contain an optional wrapped {@link LoginService} which is used to store role information about users.
+ * </p>
+ */
 public class OpenIdLoginService extends ContainerLifeCycle implements LoginService
 {
     private static final Logger LOG = Log.getLogger(OpenIdLoginService.class);
@@ -43,6 +50,13 @@ public class OpenIdLoginService extends ContainerLifeCycle implements LoginServi
         this(configuration, null);
     }
 
+    /**
+     * Use a wrapped {@link LoginService} to store information about user roles.
+     * Users in the wrapped loginService must be stored with their username as
+     * the value of the sub (subject) Claim, and a credentials value of the empty string.
+     * @param configuration the OpenID configuration to use.
+     * @param loginService the wrapped LoginService to defer to for user roles.
+     */
     public OpenIdLoginService(OpenIdConfiguration configuration, LoginService loginService)
     {
         _configuration = configuration;
@@ -101,6 +115,15 @@ public class OpenIdLoginService extends ContainerLifeCycle implements LoginServi
         return identityService.newUserIdentity(subject, userPrincipal, new String[0]);
     }
 
+    /**
+     * This setting is only meaningful if a wrapped {@link LoginService} has been set.
+     * <p>
+     * If set to true, any users not found by the wrapped {@link LoginService} will still
+     * be authenticated but with no roles, if set to false users will not be
+     * authenticated unless they are discovered by the wrapped {@link LoginService}.
+     * </p>
+     * @param authenticateNewUsers
+     */
     public void authenticateNewUsers(boolean authenticateNewUsers)
     {
         this.authenticateNewUsers = authenticateNewUsers;