[java-idp-plugin-webauthn] 02/03: Improve Javadoc
Phil Smart
philip.smart at jisc.ac.uk
Fri Mar 15 10:25:25 UTC 2024
This is an automated email from the git hooks/post-receive script.
philsmart pushed a commit to branch main
in repository java-idp-plugin-webauthn.
View the commit online:
http://git.shibboleth.net/view/?p=java-idp-plugin-webauthn.git;a=commit;h=f093f5780c6cb16596c8ed5c59220b5d83e8fd2e
commit f093f5780c6cb16596c8ed5c59220b5d83e8fd2e
Author: Phil Smart <philip.smart at jisc.ac.uk>
AuthorDate: Tue Mar 12 12:26:30 2024 +0000
Improve Javadoc
---
.../webauthn/impl/AbstractWebAuthnBaseAction.java | 4 ++--
.../impl/AddUserVerificationRequirement.java | 5 ++++-
.../CreatePublicKeyCredentialRequestOptions.java | 6 ++++--
.../impl/EnsureAllowedCredentialsIsEmpty.java | 4 +++-
...tractAuthenticatorAssertionFromFormRequest.java | 9 ++++++---
.../webauthn/impl/ExtractUsernameFromForm.java | 4 ++++
.../webauthn/impl/GenerateServerChallenge.java | 2 +-
.../webauthn/impl/LookupRegisteredCredentials.java | 9 ++++++---
.../PopulateWebAuthnAuthenticationContext.java | 23 ++++++++++++----------
...ameFromAuthenticationContextLookupStrategy.java | 3 ++-
.../webauthn/impl/ValidateWebAuthnAssertion.java | 6 +++++-
11 files changed, 50 insertions(+), 25 deletions(-)
diff --git a/webauthn-impl/src/main/java/net/shibboleth/idp/plugin/authn/webauthn/impl/AbstractWebAuthnBaseAction.java b/webauthn-impl/src/main/java/net/shibboleth/idp/plugin/authn/webauthn/impl/AbstractWebAuthnBaseAction.java
index 884cb34..44bbe39 100644
--- a/webauthn-impl/src/main/java/net/shibboleth/idp/plugin/authn/webauthn/impl/AbstractWebAuthnBaseAction.java
+++ b/webauthn-impl/src/main/java/net/shibboleth/idp/plugin/authn/webauthn/impl/AbstractWebAuthnBaseAction.java
@@ -45,12 +45,12 @@ import net.shibboleth.shared.primitive.LoggerFactory;
* <p>In addition to the work performed by {@link AbstractProfileAction}, this action also looks up
* and makes available the {@link BaseWebAuthnContext}.</p>
*
- * <p>WebAuthn registration action implementations should override the
+ * <p>WebAuthn action implementations should override the
* {@link #doExecute(ProfileRequestContext, BaseWebAuthnContext)} method.</p>
*
* @event {@link EventIds#INVALID_PROFILE_CTX}
* @pre <pre>ProfileRequestContext.getSubcontext(ProfileRequestContext.class) != null</pre>
- * @post <pre>AuthenticationContext.getSubcontext(WebAuthnRegistrationContext.class) != null</pre>
+ * @post <pre>AuthenticationContext.getSubcontext(BaseWebAuthnContext.class) != null</pre>
*/
//TODO a few abstract action types, remove overlap
public abstract class AbstractWebAuthnBaseAction extends AbstractProfileAction {
diff --git a/webauthn-impl/src/main/java/net/shibboleth/idp/plugin/authn/webauthn/impl/AddUserVerificationRequirement.java b/webauthn-impl/src/main/java/net/shibboleth/idp/plugin/authn/webauthn/impl/AddUserVerificationRequirement.java
index 01e09ad..4538d9e 100644
--- a/webauthn-impl/src/main/java/net/shibboleth/idp/plugin/authn/webauthn/impl/AddUserVerificationRequirement.java
+++ b/webauthn-impl/src/main/java/net/shibboleth/idp/plugin/authn/webauthn/impl/AddUserVerificationRequirement.java
@@ -31,7 +31,10 @@ import net.shibboleth.shared.logic.ConstraintViolationException;
import net.shibboleth.shared.primitive.LoggerFactory;
/**
- * Add a UserVerification requirement to the {@link WebAuthnAuthenticationContext context}.
+ * Add a UserVerification requirement to the {@link WebAuthnAuthenticationContext context}. Default is 'preferred'.
+ *
+ * @pre <pre>ProfileRequestContext.getSubcontext(BaseWebAuthnContext.class) != null</pre>
+ * @post <pre>WebAuthnRegistrationContext.getUserVerificationRequirement() != null</pre>
*/
public class AddUserVerificationRequirement extends AbstractWebAuthnBaseAction {
diff --git a/webauthn-impl/src/main/java/net/shibboleth/idp/plugin/authn/webauthn/impl/CreatePublicKeyCredentialRequestOptions.java b/webauthn-impl/src/main/java/net/shibboleth/idp/plugin/authn/webauthn/impl/CreatePublicKeyCredentialRequestOptions.java
index 189a7ed..e98a9e9 100644
--- a/webauthn-impl/src/main/java/net/shibboleth/idp/plugin/authn/webauthn/impl/CreatePublicKeyCredentialRequestOptions.java
+++ b/webauthn-impl/src/main/java/net/shibboleth/idp/plugin/authn/webauthn/impl/CreatePublicKeyCredentialRequestOptions.java
@@ -48,6 +48,9 @@ import net.shibboleth.shared.primitive.LoggerFactory;
/**
* Action to create a CreatePublicKeyCredentialRequestOptions from the parameters in the WebAuthn context using the
* supplied {@link WebAuthnAuthenticationClient client}.
+ *
+ * @pre <pre>ProfileRequestContext.getSubcontext(WebAuthnAuthenticationContext.class) != null</pre>
+ * @post A PublicKeyCredentialRequestOptions is added to the authentication context
*/
public class CreatePublicKeyCredentialRequestOptions extends AbstractWebAuthnAuthenticationAction {
@@ -125,8 +128,7 @@ public class CreatePublicKeyCredentialRequestOptions extends AbstractWebAuthnAut
log.error("{} Unable to generate PublicKeyCredentialRequestOptions",getLogPrefix(), e);
ActionSupport.buildEvent(profileRequestContext, AuthnEventIds.AUTHN_EXCEPTION);
return;
- }
-
+ }
}
diff --git a/webauthn-impl/src/main/java/net/shibboleth/idp/plugin/authn/webauthn/impl/EnsureAllowedCredentialsIsEmpty.java b/webauthn-impl/src/main/java/net/shibboleth/idp/plugin/authn/webauthn/impl/EnsureAllowedCredentialsIsEmpty.java
index 909c86a..4dadac5 100644
--- a/webauthn-impl/src/main/java/net/shibboleth/idp/plugin/authn/webauthn/impl/EnsureAllowedCredentialsIsEmpty.java
+++ b/webauthn-impl/src/main/java/net/shibboleth/idp/plugin/authn/webauthn/impl/EnsureAllowedCredentialsIsEmpty.java
@@ -25,8 +25,10 @@ import net.shibboleth.shared.primitive.LoggerFactory;
/**
* An action that blanks any existing registered credentials in the WebAuthn context.
+ *
+ * @pre <pre>ProfileRequestContext.getSubcontext(WebAuthnAuthenticationContext.class) != null</pre>
+ * @post <pre>WebAuthnRegistrationContext.getExistingCredentials() == null</pre>
*/
-//TODO should never be necessary given the flow, but just to make it explicit?
public class EnsureAllowedCredentialsIsEmpty extends AbstractWebAuthnAuthenticationAction {
/** Class logger. */
diff --git a/webauthn-impl/src/main/java/net/shibboleth/idp/plugin/authn/webauthn/impl/ExtractAuthenticatorAssertionFromFormRequest.java b/webauthn-impl/src/main/java/net/shibboleth/idp/plugin/authn/webauthn/impl/ExtractAuthenticatorAssertionFromFormRequest.java
index a04da01..1f6f276 100644
--- a/webauthn-impl/src/main/java/net/shibboleth/idp/plugin/authn/webauthn/impl/ExtractAuthenticatorAssertionFromFormRequest.java
+++ b/webauthn-impl/src/main/java/net/shibboleth/idp/plugin/authn/webauthn/impl/ExtractAuthenticatorAssertionFromFormRequest.java
@@ -45,6 +45,10 @@ import net.shibboleth.shared.primitive.StringSupport;
/**
* An action that extracts the AuthenticatorAssertionResponse from the incoming HTTP request.
+ *
+ * @event {@link AuthnEventIds#NO_CREDENTIALS}
+ * @pre <pre>ProfileRequestContext.getSubcontext(WebAuthnAuthenticationContext.class) != null</pre>
+ * @post <pre>WebAuthnAuthenticationContext.getAuthenticatorAssertionResponse() == null</pre>
*/
public class ExtractAuthenticatorAssertionFromFormRequest extends AbstractWebAuthnAuthenticationAction {
@@ -85,7 +89,7 @@ public class ExtractAuthenticatorAssertionFromFormRequest extends AbstractWebAut
}
/**
- * Set the name of the parameter to examine.
+ * Set the name of the assertion parameter to examine.
*
* @param field field name
*/
@@ -124,8 +128,7 @@ public class ExtractAuthenticatorAssertionFromFormRequest extends AbstractWebAut
log.debug("{} Authenticator assertion could not be converted to the correct type",getLogPrefix(), e);
ActionSupport.buildEvent(profileRequestContext, AuthnEventIds.NO_CREDENTIALS);
return;
- }
-
+ }
}
diff --git a/webauthn-impl/src/main/java/net/shibboleth/idp/plugin/authn/webauthn/impl/ExtractUsernameFromForm.java b/webauthn-impl/src/main/java/net/shibboleth/idp/plugin/authn/webauthn/impl/ExtractUsernameFromForm.java
index 10f42d1..9f49786 100644
--- a/webauthn-impl/src/main/java/net/shibboleth/idp/plugin/authn/webauthn/impl/ExtractUsernameFromForm.java
+++ b/webauthn-impl/src/main/java/net/shibboleth/idp/plugin/authn/webauthn/impl/ExtractUsernameFromForm.java
@@ -39,6 +39,10 @@ import net.shibboleth.shared.primitive.StringSupport;
* An action to populate a username into the {@link WebAuthnAuthenticationContext}.
*
* TODO FINISH. Really maybe should be similar to CheckPasswordlessEnrollment from Duo
+ *
+ * @event {@link AuthnEventIds#UNKNOWN_USERNAME}
+ * @pre <pre>ProfileRequestContext.getSubcontext(AuthenticationContext.class) != null</pre>
+ * @post <pre>WebAuthnAuthenticationContext.getUsername() == null</pre>
*/
public class ExtractUsernameFromForm extends AbstractExtractionAction {
diff --git a/webauthn-impl/src/main/java/net/shibboleth/idp/plugin/authn/webauthn/impl/GenerateServerChallenge.java b/webauthn-impl/src/main/java/net/shibboleth/idp/plugin/authn/webauthn/impl/GenerateServerChallenge.java
index 597c18c..c97f11d 100644
--- a/webauthn-impl/src/main/java/net/shibboleth/idp/plugin/authn/webauthn/impl/GenerateServerChallenge.java
+++ b/webauthn-impl/src/main/java/net/shibboleth/idp/plugin/authn/webauthn/impl/GenerateServerChallenge.java
@@ -39,7 +39,7 @@ import net.shibboleth.shared.primitive.LoggerFactory;
*
* @event {@link org.opensaml.profile.action.EventIds#PROCEED_EVENT_ID}
* @event {@link org.opensaml.profile.action.EventIds#INVALID_PROFILE_CTX}
- * @post a byte challenge is added to the base context
+ * @post a byte challenge is added to the {@link BaseWebAuthnContext base context}
*/
public class GenerateServerChallenge extends AbstractWebAuthnBaseAction {
diff --git a/webauthn-impl/src/main/java/net/shibboleth/idp/plugin/authn/webauthn/impl/LookupRegisteredCredentials.java b/webauthn-impl/src/main/java/net/shibboleth/idp/plugin/authn/webauthn/impl/LookupRegisteredCredentials.java
index 3126b7a..7506ce2 100644
--- a/webauthn-impl/src/main/java/net/shibboleth/idp/plugin/authn/webauthn/impl/LookupRegisteredCredentials.java
+++ b/webauthn-impl/src/main/java/net/shibboleth/idp/plugin/authn/webauthn/impl/LookupRegisteredCredentials.java
@@ -28,7 +28,11 @@ import net.shibboleth.idp.plugin.authn.webauthn.storage.CredentialRegistration;
import net.shibboleth.shared.primitive.LoggerFactory;
/**
- * An action that lookups existing registered credentials and sets them onto the WebAuthn context.
+ * An action that lookups existing registered credentials and sets them onto the base WebAuthn context.
+ *
+ * @event {@link AuthnEventIds#INVALID_AUTHN_CTX}
+ * @post BaseWebAuthnContext.setExistingCredentials() is either null if no existing credentials are found, or contains
+ * the credentials from the credential repository
*/
public class LookupRegisteredCredentials extends AbstractWebAuthnBaseAction {
@@ -50,8 +54,7 @@ public class LookupRegisteredCredentials extends AbstractWebAuthnBaseAction {
final Collection<CredentialRegistration> credentials =
getCredentialRepository().getRegistrationsByUsername(username);
- log.debug("{} Found '{}' registered credentials for '{}'", getLogPrefix(),
- credentials != null ? credentials.size() : "0", username);
+ log.debug("{} Found '{}' registered credentials for '{}'", getLogPrefix(), credentials.size(), username);
context.setExistingCredentials(credentials);
}
diff --git a/webauthn-impl/src/main/java/net/shibboleth/idp/plugin/authn/webauthn/impl/PopulateWebAuthnAuthenticationContext.java b/webauthn-impl/src/main/java/net/shibboleth/idp/plugin/authn/webauthn/impl/PopulateWebAuthnAuthenticationContext.java
index 5a4f215..b4a0538 100644
--- a/webauthn-impl/src/main/java/net/shibboleth/idp/plugin/authn/webauthn/impl/PopulateWebAuthnAuthenticationContext.java
+++ b/webauthn-impl/src/main/java/net/shibboleth/idp/plugin/authn/webauthn/impl/PopulateWebAuthnAuthenticationContext.java
@@ -35,13 +35,12 @@ import net.shibboleth.shared.logic.PredicateSupport;
import net.shibboleth.shared.primitive.LoggerFactory;
/**
- * An action to create (or lookup) and populate the {@link WebAuthnAuthenticationContext}
- * with the ... FIXME appropriate for this request.
+ * An action to create (or lookup) the {@link WebAuthnAuthenticationContext} and populate
+ * with the username found from the username lookup strategy. The username can be <code>null</code> if
+ * <code>usernameRequiredPredicate</code> is false.
*
* @event {@link org.opensaml.profile.action.EventIds#PROCEED_EVENT_ID}
* @event {@link org.opensaml.profile.action.EventIds#INVALID_PROFILE_CTX}
- * @event {@link net.shibboleth.idp.authn.AuthnEventIds#NO_CREDENTIALS}
- * @event {@link net.shibboleth.idp.authn.AuthnEventIds#AUTHN_EXCEPTION}
* @post See above.
*/
public class PopulateWebAuthnAuthenticationContext extends AbstractAuthenticationAction {
@@ -53,10 +52,10 @@ public class PopulateWebAuthnAuthenticationContext extends AbstractAuthenticatio
@Nonnull
private final Function<ProfileRequestContext,WebAuthnAuthenticationContext> webauthnAuthContextCreationStrategy;
- /** Lookup strategy for username. */
+ /** Lookup strategy for the username. */
@Nonnull private Function<ProfileRequestContext, String> usernameLookupStrategy;
- /** Is the username required?*/
+ /** Is the username required? */
private Predicate<ProfileRequestContext> usernameRequiredPredicate;
@@ -73,7 +72,9 @@ public class PopulateWebAuthnAuthenticationContext extends AbstractAuthenticatio
}
/**
- * @param flag The usernameRequired to set.
+ * Set a flag to determine if the username is required or not.
+ *
+ * @param flag is the username required?
*/
public void setUsernameRequired(final boolean flag) {
checkSetterPreconditions();
@@ -81,7 +82,9 @@ public class PopulateWebAuthnAuthenticationContext extends AbstractAuthenticatio
}
/**
- * @param usernameRequiredPredicate The usernameRequiredPredicate to set.
+ * Set a strategy to determine if the username is required or not.
+ *
+ * @param predicate the predicate to set.
*/
public void setUsernameRequiredPredicate(@Nonnull final Predicate<ProfileRequestContext> predicate){
checkSetterPreconditions();
@@ -89,7 +92,7 @@ public class PopulateWebAuthnAuthenticationContext extends AbstractAuthenticatio
}
/**
- * Set the lookup strategy to use for the username to match against Duo identity.
+ * Set the username lookup strategy.
*
* @param strategy lookup strategy
*/
@@ -112,7 +115,7 @@ public class PopulateWebAuthnAuthenticationContext extends AbstractAuthenticatio
ActionSupport.buildEvent(profileRequestContext, EventIds.INVALID_PROFILE_CTX);
return;
}
- // Username can be null, but if required record exception if it is
+
final String username = usernameLookupStrategy.apply(profileRequestContext);
if (usernameRequiredPredicate.test(profileRequestContext) && username == null) {
log.error("{} Error creating WebauthnAuthenticationContext, no username found", getLogPrefix());
diff --git a/webauthn-impl/src/main/java/net/shibboleth/idp/plugin/authn/webauthn/impl/UsernameFromAuthenticationContextLookupStrategy.java b/webauthn-impl/src/main/java/net/shibboleth/idp/plugin/authn/webauthn/impl/UsernameFromAuthenticationContextLookupStrategy.java
index 417473c..97d77a7 100644
--- a/webauthn-impl/src/main/java/net/shibboleth/idp/plugin/authn/webauthn/impl/UsernameFromAuthenticationContextLookupStrategy.java
+++ b/webauthn-impl/src/main/java/net/shibboleth/idp/plugin/authn/webauthn/impl/UsernameFromAuthenticationContextLookupStrategy.java
@@ -27,7 +27,8 @@ import net.shibboleth.idp.authn.context.AuthenticationContext;
import net.shibboleth.idp.authn.principal.UsernamePrincipal;
/**
- * Take the UsernamePrincipal from the authentication context iff there is only one. Return {@code null} otherwise.
+ * A strategy that takes the UsernamePrincipal from the authentication context iff there is only one.
+ * Returning {@code null} otherwise.
*/
public class UsernameFromAuthenticationContextLookupStrategy implements Function<ProfileRequestContext, String> {
diff --git a/webauthn-impl/src/main/java/net/shibboleth/idp/plugin/authn/webauthn/impl/ValidateWebAuthnAssertion.java b/webauthn-impl/src/main/java/net/shibboleth/idp/plugin/authn/webauthn/impl/ValidateWebAuthnAssertion.java
index 25312b9..fddc8f0 100644
--- a/webauthn-impl/src/main/java/net/shibboleth/idp/plugin/authn/webauthn/impl/ValidateWebAuthnAssertion.java
+++ b/webauthn-impl/src/main/java/net/shibboleth/idp/plugin/authn/webauthn/impl/ValidateWebAuthnAssertion.java
@@ -30,7 +30,11 @@ import net.shibboleth.shared.logic.Constraint;
import net.shibboleth.shared.primitive.LoggerFactory;
/**
- * An action that validates a WebAuthn Authenticator Assertion that results from a call to 'get' (authentication).
+ * An action that validates a WebAuthn Authenticator Assertion that results from a call to 'get' (authentication). If
+ * succesful populates the Subject with a {@link UsernamePrincipal}.
+ *
+ * @event {@link AuthnEventIds#INVALID_CREDENTIALS}
+ * @event {@link AuthnEventIds#INVALID_AUTHN_CTX}
*/
public class ValidateWebAuthnAssertion extends AbstractValidationAction {
--
To stop receiving notification emails like this one, please contact
the administrator of this repository.
More information about the commits
mailing list