org.wildfly.security.auth.server

Class ServerAuthenticationContext

java.lang.Object

org.wildfly.security.auth.server.ServerAuthenticationContext

All Implemented Interfaces:

AutoCloseable

public final class ServerAuthenticationContext
extends Object
implements AutoCloseable

Server-side authentication context. Instances of this class are used to perform all authentication and re-authorization operations that involve the usage of an identity in a security domain.

There are various effective states, described as follows:

• The inactive state.
• The unassigned states:
  • Initial
  • Realm-assigned
• The assigned state
• The authorized states:
  • Anonymous-authorized
  • Authorized
  • Authorized-authenticated
• The terminal states:
  • Complete
  • Failed

When an instance of this class is first constructed, it is in the inactive state. In this state, the context retains a captured identity and contains a reference to a MechanismConfigurationSelector. The captured identity may be used for various context-sensitive authorization decisions. Additional mechanism information can be supplied to this state so that when authentication begins an appropriate MechanismConfiguration can be selected.

Once authentication commences the state will automatically transition to the initial state. In this state, the context retains an captured identity and a mechanism configuration which was resolved from the information supplied to the inactive state. The captured identity may be used for various context-sensitive authorization decisions. The mechanism configuration is used to associate an authentication mechanism-specific configuration, including rewriters, mechanism realms, server credential factories, and more.

When an authentication mechanism is "realm-aware" (that is, it has a notion of realms that is specific to that particular authentication mechanism, e.g. the DIGEST-MD5 SASL mechanism), it is necessary for the mechanism to relay the realm selection. This is done by way of the setMechanismRealmName() method. Calling this method in the initial state causes a transition to the realm-assigned state, in which the method may be reinvoked idempotently as long as it is called with the same name (calling the method with a different name will result in an exception).

The realm-assigned state is nearly identical to the initial state, except that from this state, the mechanism realm-specific configuration is applied to all subsequent operation.

From these unassigned states, several possible actions may be taken, depending on the necessary progression of the authentication:

• A name may be assigned by way of the setAuthenticationName(String) method. The name is rewritten and mapped to a realm according to the domain settings, the mechanism configuration, and/or the mechanism realm configuration. The realm that is the resultant target of the mapping is queried for a realm identity. The realm identity may or may not be existent; this status will affect the outcome of certain operations in subsequent states (as described below). After the realm identity is selected, any final rewrite operations which are configured are applied, and the resultant name is transformed into a NamePrincipal, and associated as the authentication principal which may subsequently be queried.
• A principal may be assigned using the setAuthenticationPrincipal(Principal) method. The principal is decoded according to the configuration of the security domain (see the method documentation for input requirements and failure conditions). Once a name is decoded from the principal, it is assigned as described above.
• A unit of evidence may be verified. This is mostly described below in the context of the assigned state, but with the important distinction the evidence is first examined to locate the corresponding evidence, in the following steps:
  • Firstly, the evidence is examined to determine whether it contains a principal. If so, the principal name is first established using the procedure described above, and then the normal evidence verification procedure described below commences.
  • Secondly, the evidence is socialized to each realm in turn, to see if a realm can recognize and locate an identity based on the evidence. If so, the realm identity is queried for an authentication principal, which is then decoded and established as described above. Once this is done successfully, the evidence verification procedure described below commences.
  • Finally, if none of these steps succeeds, the verification fails and no state transition occurs.
• An identity may be imported. In this process, a SecurityIdentity instance is examined to determine whether it can be used to complete an implicit authentication operation which would yield an authorized identity. The SecurityIdentity may be from the same domain or from a different one.

  If the identity being imported is from the same security domain as this context, then the identity is implicitly authorized for usage, entering the authorized state described below.

  If the identity being imported is not from the same security domain, then the principal is extracted from the identity and used to assign a realm identity in the same manner as setAuthenticationPrincipal(Principal). The domain is then queried to determine whether the target identity's source domain is trusted. If so, a normal authorization is carried out as described below for the assigned state, resulting in an authorized-authenticated state. If not, then the realm of the realm identity is compared against the realm of the identity being imported. If they are the same, the identity is imported and a normal authorization is carried out as described below.

• An anonymous authorization may be carried out by way of the authorizeAnonymous() method. If the anonymous identity has the LoginPermission granted to it, the context will transition into the anonymous-authorized state; otherwise no state transition occurs.
• An external authorization may be carried out using the authorize() method. The captured identity (which may be anonymous) is queried for the presence of the LoginPermission; if present, the context will transition into the authorized or anonymous-authorized state (depending on whether the captured identity is anonymous); otherwise no state transition occurs.
• An external run-as authorization may be carried out using the authorize(String) method. First, the given name is rewritten in the same manner as the setAuthenticationName(String) method. Then, the captured identity (which may be anonymous) is queried for the presence of a RunAsPrincipalPermission for the target name. If present, the authentication name is assigned as described above, and the resultant realm identity is queried for LoginPermission. If present, the context will transition to the authorized-authenticated state. If any step fails, no state transition occurs.
• The authentication may be failed by way of the fail() method. This method will dispose of all authentication resources and transition to the failed state.

In the name-assigned (or, for brevity, assigned) state, the following actions may be performed:

• A name or principal may be assigned as above, however the resultant decoded and rewritten name and realm identity must be identical to the previously selected name and identity.
• Evidence may be verified. The realm identity is queried directly and no state transitions will occur. Evidence verification will fail if the evidence has an evidence principal which does not result in the same realm identity as the current one after decoding and rewriting.
• An authorization may be performed via the authorize() method. If the selected realm identity possesses the LoginPermission, then the context transitions to the authorized-authenticated state, otherwise no state transition occurs.
• A run-as authorization may be performed via the authorize(String) method. First, the given name is rewritten in the same manner as the setAuthenticationName(String) method. The current identity is then authorized as described above, and then the authorized identity is tested for a RunAsPrincipalPermission for the rewritten target name. If authorized, the context transitions to the authorized state for the realm identity corresponding to the rewritten name; otherwise no state transition occurs.
• The authentication may be failed by way of the fail() method. This method will dispose of all authentication resources and transition to the failed state.

There are three states related to authorization: the anonymous-authorized state, the authorized state, and the authorized-authenticated state. In all three states, the following actions may be taken:

• As above, a name or principal may be assigned so long as it matches the existing identity. In particular, for the anonymous-authorized state, all names are rejected, and only the anonymous principal is accepted.
• An authorization may be performed via the authorize() method. Since the identity is always authorized, this is generally a no-op.
• A run-as authorization may be performed via the authorize(String) method. The given name is rewritten as previously described, and then the authorized identity is tested for a RunAsPrincipalPermission for the rewritten target name. If authorized, the context transitions to the authorized state for the realm identity corresponding to the rewritten name; otherwise no state transition occurs.
• The authentication may be completed by way of the succeed() method. This method will dispose of all authentication resources and transition to the complete state.
• The authentication may be failed by way of the fail() method. This method will dispose of all authentication resources and transition to the failed state.

The authorized-authenticated state has the additional capability of verifying credentials as described above for the assigned state.

The complete state has only one capability: the retrieval of the final authorized identity by way of the getAuthorizedIdentity() method.

The failed state has no capabilities and retains no reference to any identities or objects used during authentication.

Author:

David M. Lloyd, Darran Lofthouse

Method Summary

Modifier and Type	Method and Description
void	addPrivateCredential(Credential credential) Add a private credential to the identity being authenticated.
void	addPublicCredential(Credential credential) Add a public credential to the identity being authenticated.
<C extends Credential,R> R	applyToCredential(Class<C> credentialType, Function<C,R> function) Apply the given function to the acquired credential, if it is set and of the given type.
<C extends Credential,R> R	applyToCredential(Class<C> credentialType, String algorithmName, AlgorithmParameterSpec parameterSpec, Function<C,R> function) Apply the given function to the acquired credential, if it is set and of the given type and algorithm.
<C extends Credential,R> R	applyToCredential(Class<C> credentialType, String algorithmName, Function<C,R> function) Apply the given function to the acquired credential, if it is set and of the given type and algorithm.
boolean	authorize() Attempt to authorize an authentication attempt.
boolean	authorize(Principal principal) Attempt to authorize a change to a new user (possibly including an authentication attempt).
boolean	authorize(String name) Attempt to authorize a change to a new user (possibly including an authentication attempt).
boolean	authorizeAnonymous() Set the authentication to anonymous, completing the authentication process.
boolean	authorizeAnonymous(boolean requireLoginPermission) Set the authentication to anonymous, completing the authentication process.
void	close() Close the server authentication context, failing any in-progress authentication and releasing any associated resources.
boolean	exists() Determine if the current authentication identity actually exists in the realm.
void	fail() Mark this authentication as "failed".
Principal	getAuthenticationPrincipal() Get the principal associated with the current authentication name.
SecurityIdentity	getAuthorizedIdentity() Get the authorized identity result of this authentication.
<C extends Credential> C	getCredential(Class<C> credentialType) Acquire a credential of the given type.
<C extends Credential> C	getCredential(Class<C> credentialType, String algorithmName) Acquire a credential of the given type.
<C extends Credential> C	getCredential(Class<C> credentialType, String algorithmName, AlgorithmParameterSpec parameterSpec) Acquire a credential of the given type.
SupportLevel	getCredentialAcquireSupport(Class<? extends Credential> credentialType) Determine whether a given credential is definitely obtainable, possibly obtainable, or definitely not obtainable.
SupportLevel	getCredentialAcquireSupport(Class<? extends Credential> credentialType, String algorithmName) Determine whether a given credential is definitely obtainable, possibly obtainable, or definitely not obtainable.
SupportLevel	getCredentialAcquireSupport(Class<? extends Credential> credentialType, String algorithmName, AlgorithmParameterSpec parameterSpec) Determine whether a given credential is definitely obtainable, possibly obtainable, or definitely not obtainable.
SupportLevel	getEvidenceVerifySupport(Class<? extends Evidence> evidenceType) Determine whether a given piece of evidence is definitely verifiable, possibly verifiable, or definitely not verifiable.
SupportLevel	getEvidenceVerifySupport(Class<? extends Evidence> evidenceType, String algorithmName) Determine whether a given piece of evidence is definitely verifiable, possibly verifiable, or definitely not verifiable.
boolean	importIdentity(SecurityIdentity identity) Attempt to import the given security identity as a trusted identity.
boolean	isDone() Determine if authentication was already completed on this context.
boolean	isSameName(String name) Determine if the given name refers to the same identity as the currently set authentication name.
boolean	isSamePrincipal(Principal principal) Determine if the given principal refers to the same identity as the currently set authentication name.
void	setAuthenticationName(String name) Set the authentication name for this authentication.
void	setAuthenticationName(String name, boolean exclusive) Set the authentication name for this authentication.
void	setAuthenticationPrincipal(Principal principal) Set the authentication principal for this authentication.
void	setAuthenticationPrincipal(Principal principal, boolean exclusive) Set the authentication principal for this authentication.
void	setMechanismInformation(MechanismInformation mechanismInformation) Set information about the current mechanism and request for this authentication attempt.
void	setMechanismRealmName(String realmName) Set the mechanism realm name to be equal to the given name.
void	succeed() Mark this authentication as "successful".
void	updateCredential(Credential credential) Update the credential for the current authentication identity.
boolean	verifyEvidence(Evidence evidence) Verify the given evidence.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

setMechanismInformation

public void setMechanismInformation(MechanismInformation mechanismInformation)
                             throws IllegalStateException

Set information about the current mechanism and request for this authentication attempt. If the mechanism information cannot be resolved to a mechanism configuration, an exception is thrown.

Parameters:

mechanismInformation - the mechanism information about the current authentication attempt.

Throws:

IllegalStateException - if the mechanism information about the current authentication attempt cannot be resolved to a mechanism configuration

getAuthorizedIdentity

public SecurityIdentity getAuthorizedIdentity()
                                       throws IllegalStateException

Get the authorized identity result of this authentication.

Returns:

the authorized identity

Throws:

IllegalStateException - if the authentication is incomplete

authorizeAnonymous

public boolean authorizeAnonymous()
                           throws IllegalStateException

Set the authentication to anonymous, completing the authentication process.

Throws:

IllegalStateException - if the authentication is already complete

authorizeAnonymous

public boolean authorizeAnonymous(boolean requireLoginPermission)
                           throws IllegalStateException

Set the authentication to anonymous, completing the authentication process.

Parameters:

requireLoginPermission - true if LoginPermission is required and false otherwise

Throws:

IllegalStateException - if the authentication is already complete

setAuthenticationName

public void setAuthenticationName(String name)
                           throws IllegalArgumentException,
                                  RealmUnavailableException,
                                  IllegalStateException

Set the authentication name for this authentication. If the name is already set, then the new name must be equal to the old name, or else an exception is thrown.

Parameters:

name - the authentication name

Throws:

IllegalArgumentException - if the name is syntactically invalid

RealmUnavailableException - if the realm is not available

IllegalStateException - if the authentication name was already set and there is a mismatch

setAuthenticationName

public void setAuthenticationName(String name,
                                  boolean exclusive)
                           throws IllegalArgumentException,
                                  RealmUnavailableException,
                                  IllegalStateException

Set the authentication name for this authentication. If the name is already set, then the new name must be equal to the old name, or else an exception is thrown.

Parameters:

name - the authentication name

exclusive - true if exclusive access to the backing identity is required

Throws:

IllegalArgumentException - if the name is syntactically invalid

RealmUnavailableException - if the realm is not available or if exclusive access to the backing identity is required but could not be granted

IllegalStateException - if the authentication name was already set and there is a mismatch

setAuthenticationPrincipal

public void setAuthenticationPrincipal(Principal principal)
                                throws IllegalArgumentException,
                                       RealmUnavailableException,
                                       IllegalStateException

Set the authentication principal for this authentication. Calling this method initiates authentication.

Parameters:

principal - the authentication principal

Throws:

IllegalArgumentException - if the principal cannot be mapped to a name, or the mapped name is syntactically invalid

RealmUnavailableException - if the realm is not available

IllegalStateException - if the authentication name was already set

setAuthenticationPrincipal

public void setAuthenticationPrincipal(Principal principal,
                                       boolean exclusive)
                                throws IllegalArgumentException,
                                       RealmUnavailableException,
                                       IllegalStateException

Set the authentication principal for this authentication. Calling this method initiates authentication.

Parameters:

principal - the authentication principal

exclusive - true if exclusive access to the backing identity is required

Throws:

IllegalArgumentException - if the principal cannot be mapped to a name, or the mapped name is syntactically invalid

RealmUnavailableException - if the realm is not available

IllegalStateException - if the authentication name was already set

isSameName

public boolean isSameName(String name)
                   throws IllegalArgumentException,
                          RealmUnavailableException,
                          IllegalStateException

Determine if the given name refers to the same identity as the currently set authentication name.

Parameters:

name - the authentication name

Returns:

true if the name matches the current identity, false otherwise

Throws:

IllegalArgumentException - if the name is syntactically invalid

RealmUnavailableException - if the realm is not available

IllegalStateException - if the authentication name was already set

isSamePrincipal

public boolean isSamePrincipal(Principal principal)
                        throws IllegalArgumentException,
                               RealmUnavailableException,
                               IllegalStateException

Determine if the given principal refers to the same identity as the currently set authentication name.

Parameters:

principal - the authentication name

Returns:

true if the name matches the current identity, false otherwise

Throws:

IllegalArgumentException - if the name is syntactically invalid

RealmUnavailableException - if the realm is not available

IllegalStateException - if the authentication name was already set

exists

public boolean exists()
               throws RealmUnavailableException,
                      IllegalStateException

Determine if the current authentication identity actually exists in the realm.

Returns:

true if the identity exists, false otherwise

Throws:

RealmUnavailableException - if the realm failed to access the identity

IllegalStateException - if there is no authentication name set

fail

public void fail()
          throws IllegalStateException

Mark this authentication as "failed". The context cannot be used after this method is called.

Throws:

IllegalStateException - if no authentication has been initiated or authentication is already completed

authorize

public boolean authorize()
                  throws RealmUnavailableException,
                         IllegalStateException

Attempt to authorize an authentication attempt. If the authorization is successful, true is returned and the context is placed in the "authorized" state with the new authorization identity. If the authorization fails, false is returned and the state of the context is unchanged.

Returns:

true if the authorization succeeded, false otherwise

Throws:

RealmUnavailableException - if the realm is not available

IllegalStateException - if the authentication name was not set or authentication was already complete

authorize

public boolean authorize(String name)
                  throws IllegalArgumentException,
                         RealmUnavailableException,
                         IllegalStateException

Attempt to authorize a change to a new user (possibly including an authentication attempt). If the authorization is successful, true is returned and the context is placed in the "authorized" state with the new authorization identity. If the authorization fails, false is returned and the state of the context is unchanged.

Parameters:

name - the authorization name (must not be null)

Returns:

true if the authorization succeeded, false otherwise

Throws:

IllegalArgumentException - if the name is syntactically invalid

RealmUnavailableException - if the realm is not available

IllegalStateException - if the authentication name was not set or authentication was already complete

authorize

public boolean authorize(Principal principal)
                  throws IllegalArgumentException,
                         RealmUnavailableException,
                         IllegalStateException

Attempt to authorize a change to a new user (possibly including an authentication attempt). If the authorization is successful, true is returned and the context is placed in the "authorized" state with the new authorization identity. If the authorization fails, false is returned and the state of the context is unchanged.

Parameters:

principal - the authorization principal (must not be null)

Returns:

true if the authorization succeeded, false otherwise

Throws:

IllegalArgumentException - if the principal is syntactically invalid

RealmUnavailableException - if the realm is not available

IllegalStateException - if the authentication principal was not set or authentication was already complete

succeed

public void succeed()
             throws IllegalStateException,
                    RealmUnavailableException

Mark this authentication as "successful". The context cannot be used after this method is called, however the authorized identity may thereafter be accessed via the getAuthorizedIdentity() method. If no authentication actually happened, then authentication will complete anonymously.

Throws:

IllegalStateException - if authentication is already completed

RealmUnavailableException - if the realm is not able to handle requests for any reason

isDone

public boolean isDone()

Determine if authentication was already completed on this context.

Returns:

true if authentication was completed; false otherwise

getAuthenticationPrincipal

public Principal getAuthenticationPrincipal()

Get the principal associated with the current authentication name. Only valid during authentication process.

Returns:

the principal

Throws:

IllegalStateException - if no authentication has been initiated or authentication is already completed

getCredentialAcquireSupport

public SupportLevel getCredentialAcquireSupport(Class<? extends Credential> credentialType,
                                                String algorithmName,
                                                AlgorithmParameterSpec parameterSpec)
                                         throws RealmUnavailableException

Determine whether a given credential is definitely obtainable, possibly obtainable, or definitely not obtainable. If an authentication identity is established this will be for that identity, otherwise this will be the general level of support advertised by the security domain.

Parameters:

credentialType - the credential type class (must not be null)

algorithmName - the algorithm name, or null if any algorithm is acceptable or the credential type does not support algorithm names

parameterSpec - the algorithm parameters to match, or null if any parameters are acceptable or the credential type does not support algorithm parameters

Returns:

the level of support for this credential type

Throws:

RealmUnavailableException - if the realm is not able to handle requests for any reason

IllegalStateException - if no authentication has been initiated or authentication is already completed

getCredentialAcquireSupport

public SupportLevel getCredentialAcquireSupport(Class<? extends Credential> credentialType,
                                                String algorithmName)
                                         throws RealmUnavailableException

Determine whether a given credential is definitely obtainable, possibly obtainable, or definitely not obtainable. If an authentication identity is established this will be for that identity, otherwise this will be the general level of support advertised by the security domain.

Parameters:

credentialType - the credential type class (must not be null)

algorithmName - the algorithm name, or null if any algorithm is acceptable or the credential type does not support algorithm names

Returns:

the level of support for this credential type

Throws:

RealmUnavailableException - if the realm is not able to handle requests for any reason

IllegalStateException - if no authentication has been initiated or authentication is already completed

getCredentialAcquireSupport

public SupportLevel getCredentialAcquireSupport(Class<? extends Credential> credentialType)
                                         throws RealmUnavailableException

Determine whether a given credential is definitely obtainable, possibly obtainable, or definitely not obtainable. If an authentication identity is established this will be for that identity, otherwise this will be the general level of support advertised by the security domain.

Parameters:

credentialType - the credential type class (must not be null)

Returns:

the level of support for this credential type

Throws:

RealmUnavailableException - if the realm is not able to handle requests for any reason

IllegalStateException - if no authentication has been initiated or authentication is already completed

getEvidenceVerifySupport

public SupportLevel getEvidenceVerifySupport(Class<? extends Evidence> evidenceType,
                                             String algorithmName)
                                      throws RealmUnavailableException

Determine whether a given piece of evidence is definitely verifiable, possibly verifiable, or definitely not verifiable. If an authentication identity is established this will be for that identity, otherwise this will be the general level of support advertised by the security domain.

Parameters:

evidenceType - the evidence type class (must not be null)

algorithmName - the algorithm name, or null if any algorithm is acceptable or the evidence type does not support algorithm names

Returns:

the level of support for this credential type

Throws:

RealmUnavailableException - if the realm is not able to handle requests for any reason

IllegalStateException - if no authentication has been initiated or authentication is already completed

getEvidenceVerifySupport

public SupportLevel getEvidenceVerifySupport(Class<? extends Evidence> evidenceType)
                                      throws RealmUnavailableException

Determine whether a given piece of evidence is definitely verifiable, possibly verifiable, or definitely not verifiable. If an authentication identity is established this will be for that identity, otherwise this will be the general level of support advertised by the security domain.

Parameters:

evidenceType - the evidence type class (must not be null)

Returns:

the level of support for this credential type

Throws:

RealmUnavailableException - if the realm is not able to handle requests for any reason

IllegalStateException - if no authentication has been initiated or authentication is already completed

getCredential

public <C extends Credential> C getCredential(Class<C> credentialType,
                                              String algorithmName,
                                              AlgorithmParameterSpec parameterSpec)
                                       throws RealmUnavailableException

Acquire a credential of the given type. The credential type is defined by its Class and an optional algorithmName. If the algorithm name is not given, then the query is performed for any algorithm of the given type.

Type Parameters:

C - the credential type

Parameters:

credentialType - the credential type class (must not be null)

algorithmName - the algorithm name, or null if any algorithm is acceptable or the credential type does not support algorithm names

parameterSpec - the algorithm parameters to match, or null if any parameters are acceptable or the credential type does not support algorithm parameters

Returns:

the credential, or null if the principal has no credential of that type

Throws:

RealmUnavailableException - if the realm is not able to handle requests for any reason

IllegalStateException - if no authentication has been initiated or authentication is already completed

getCredential

public <C extends Credential> C getCredential(Class<C> credentialType,
                                              String algorithmName)
                                       throws RealmUnavailableException

Acquire a credential of the given type. The credential type is defined by its Class and an optional algorithmName. If the algorithm name is not given, then the query is performed for any algorithm of the given type.

Type Parameters:

C - the credential type

Parameters:

credentialType - the credential type class (must not be null)

algorithmName - the algorithm name, or null if any algorithm is acceptable or the credential type does not support algorithm names

Returns:

the credential, or null if the principal has no credential of that type

Throws:

RealmUnavailableException - if the realm is not able to handle requests for any reason

IllegalStateException - if no authentication has been initiated or authentication is already completed

getCredential

public <C extends Credential> C getCredential(Class<C> credentialType)
                                       throws RealmUnavailableException

Acquire a credential of the given type. The credential type is defined by its Class and an optional algorithmName. If the algorithm name is not given, then the query is performed for any algorithm of the given type.

Type Parameters:

C - the credential type

Parameters:

credentialType - the credential type class (must not be null)

Returns:

the credential, or null if the principal has no credential of that type

Throws:

RealmUnavailableException - if the realm is not able to handle requests for any reason

IllegalStateException - if no authentication has been initiated or authentication is already completed

applyToCredential

public <C extends Credential,R> R applyToCredential(Class<C> credentialType,
                                                    Function<C,R> function)
                                             throws RealmUnavailableException

Apply the given function to the acquired credential, if it is set and of the given type.

Type Parameters:

C - the credential type

R - the return type

Parameters:

credentialType - the credential type class (must not be null)

function - the function to apply (must not be null)

Returns:

the result of the function, or null if the criteria are not met

Throws:

RealmUnavailableException - if the realm is not able to handle requests for any reason

IllegalStateException - if no authentication has been initiated or authentication is already completed

applyToCredential

public <C extends Credential,R> R applyToCredential(Class<C> credentialType,
                                                    String algorithmName,
                                                    Function<C,R> function)
                                             throws RealmUnavailableException

Apply the given function to the acquired credential, if it is set and of the given type and algorithm.

Type Parameters:

C - the credential type

R - the return type

Parameters:

credentialType - the credential type class (must not be null)

algorithmName - the algorithm name

function - the function to apply (must not be null)

Returns:

the result of the function, or null if the criteria are not met

Throws:

RealmUnavailableException - if the realm is not able to handle requests for any reason

IllegalStateException - if no authentication has been initiated or authentication is already completed

applyToCredential

public <C extends Credential,R> R applyToCredential(Class<C> credentialType,
                                                    String algorithmName,
                                                    AlgorithmParameterSpec parameterSpec,
                                                    Function<C,R> function)
                                             throws RealmUnavailableException

Apply the given function to the acquired credential, if it is set and of the given type and algorithm.

Type Parameters:

C - the credential type

R - the return type

Parameters:

credentialType - the credential type class (must not be null)

algorithmName - the algorithm name

parameterSpec - the algorithm parameters to match, or null if any parameters are acceptable or the credential type does not support algorithm parameters

function - the function to apply (must not be null)

Returns:

the result of the function, or null if the criteria are not met

Throws:

RealmUnavailableException - if the realm is not able to handle requests for any reason

IllegalStateException - if no authentication has been initiated or authentication is already completed

verifyEvidence

public boolean verifyEvidence(Evidence evidence)
                       throws RealmUnavailableException

Verify the given evidence.

Parameters:

evidence - the evidence to verify

Returns:

true if verification was successful, false otherwise

Throws:

RealmUnavailableException - if the realm is not able to handle requests for any reason

IllegalStateException - if no authentication has been initiated or authentication is already completed

addPublicCredential

public void addPublicCredential(Credential credential)

Add a public credential to the identity being authenticated.

Parameters:

credential - the credential to add (must not be null)

addPrivateCredential

public void addPrivateCredential(Credential credential)

Add a private credential to the identity being authenticated. This credential may be forwarded to outbound authentication mechanisms.

Parameters:

credential - the credential to add (must not be null)

importIdentity

public boolean importIdentity(SecurityIdentity identity)
                       throws RealmUnavailableException

Attempt to import the given security identity as a trusted identity. If this method returns true, the context will be in an authorized state, and the new identity can be retrieved.

Parameters:

identity - the identity to import (must not be null)

Returns:

true if the identity is authorized, false otherwise

Throws:

RealmUnavailableException - if the realm is not able to handle requests for any reason

setMechanismRealmName

public void setMechanismRealmName(String realmName)
                           throws IllegalStateException,
                                  IllegalArgumentException

Set the mechanism realm name to be equal to the given name. If no mechanism realms are configured, the realm name is ignored.

Parameters:

realmName - the selected realm name

Throws:

IllegalStateException - if a realm name was already selected or it is too late to choose a realm

IllegalArgumentException - if the selected realm name was not offered

updateCredential

public void updateCredential(Credential credential)
                      throws RealmUnavailableException

Update the credential for the current authentication identity.

Parameters:

credential - the new credential (must not be null)

Throws:

RealmUnavailableException - if the realm is not able to handle requests for any reason

close

public void close()

Close the server authentication context, failing any in-progress authentication and releasing any associated resources.

Specified by:

close in interface AutoCloseable