org.apereo.cas.authentication

Interface AuthenticationHandler

All Superinterfaces:

org.springframework.core.Ordered

All Known Subinterfaces:

PrePostAuthenticationHandler

public interface AuthenticationHandler
extends org.springframework.core.Ordered

An authentication handler authenticates a single credential. In many cases credentials are authenticated by comparison with data in a system of record such as LDAP directory or database.

Since:

4.0.0

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	SUCCESSFUL_AUTHENTICATION_HANDLERS Attribute name containing collection of handler names that successfully authenticated credential.

Fields inherited from interface org.springframework.core.Ordered

HIGHEST_PRECEDENCE, LOWEST_PRECEDENCE

Method Summary

Modifier and Type	Method and Description
HandlerResult	authenticate(Credential credential) Authenticates the given credential.
java.lang.String	getName() Gets a unique name for this authentication handler within the Spring context that contains it.
boolean	supports(Credential credential) Determines whether the handler has the capability to authenticate the given credential.

Methods inherited from interface org.springframework.core.Ordered

getOrder

Field Detail

SUCCESSFUL_AUTHENTICATION_HANDLERS

static final java.lang.String SUCCESSFUL_AUTHENTICATION_HANDLERS

Attribute name containing collection of handler names that successfully authenticated credential.

See Also:

Constant Field Values

Method Detail

authenticate

HandlerResult authenticate(Credential credential)
                    throws java.security.GeneralSecurityException,
                           PreventedException

Authenticates the given credential. There are three possible outcomes of this process, and implementers MUST adhere to the following contract:

1. Success -- return HandlerResult
2. Failure -- throw GeneralSecurityException
3. Indeterminate -- throw PreventedException

Parameters:

credential - The credential to authenticate.

Returns:

A result object containing metadata about a successful authentication event that includes at a minimum the name of the handler that authenticated the credential and some credential metadata. The following data is optional:

• Principal
• Messages issued by the handler about the credential (e.g. impending password expiration warning)

Throws:

java.security.GeneralSecurityException - On authentication failures where the root cause is security related, e.g. invalid credential. Implementing classes SHOULD be as specific as possible in communicating the reason for authentication failure. Recommendations for common cases:

• Bad password: javax.security.auth.login.FailedLoginException
• Expired password: javax.security.auth.login.CredentialExpiredException
• User account expired: javax.security.auth.login.AccountExpiredException
• User account locked: javax.security.auth.login.AccountLockedException
• User account not found: javax.security.auth.login.AccountNotFoundException
• Time of authentication not allowed: org.apereo.cas.authentication.InvalidLoginTimeException
• Location of authentication not allowed: org.apereo.cas.authentication.InvalidLoginLocationException
• Expired X.509 certificate: java.security.cert.CertificateExpiredException

PreventedException - On errors that prevented authentication from occurring. Implementing classes SHOULD take care to populate the cause, where applicable, with the error that prevented authentication.

supports

boolean supports(Credential credential)

Determines whether the handler has the capability to authenticate the given credential. In practical terms, the authenticate(Credential) method MUST be capable of processing a given credential if supports returns true on the same credential.

Parameters:

credential - The credential to check.

Returns:

True if the handler supports the Credential, false otherwise.

getName

java.lang.String getName()

Gets a unique name for this authentication handler within the Spring context that contains it. For implementations that allow setting a unique name, deployers MUST take care to ensure that every handler instance has a unique name.

Returns:

Unique name within a Spring context.