org.wildfly.security.auth.server

Interface SecurityRealm

All Known Subinterfaces:

ModifiableSecurityRealm

public interface SecurityRealm

A single authentication realm. A realm is backed by a single homogeneous store of identities and credentials.

Author:

David M. Lloyd, Darran Lofthouse

Field Summary

Fields

Modifier and Type	Field and Description
static SecurityRealm	EMPTY_REALM An empty security realm.

Method Summary

Modifier and Type	Method and Description
default SupportLevel	getCredentialAcquireSupport(Class<? extends Credential> credentialType, String algorithmName) Deprecated. Transition method; remove before GA.
SupportLevel	getCredentialAcquireSupport(Class<? extends Credential> credentialType, String algorithmName, AlgorithmParameterSpec parameterSpec) Determine whether a credential of the given type and algorithm is definitely obtainable, possibly obtainable (for] some identities), or definitely not obtainable.
SupportLevel	getEvidenceVerifySupport(Class<? extends Evidence> evidenceType, String algorithmName) Determine whether a given type of evidence is definitely verifiable, possibly verifiable (for some identities), or definitely not verifiable.
default RealmIdentity	getRealmIdentity(Evidence evidence) Get a handle for to the identity for the given evidence in the context of this security realm.
default RealmIdentity	getRealmIdentity(Principal principal) Get a handle for to the identity for the given principal in the context of this security realm.
default void	handleRealmEvent(RealmEvent event) Handle a realm event.
static void	safeHandleRealmEvent(SecurityRealm realm, RealmEvent event) Safely pass an event to a security realm, absorbing and logging any exception that occurs.

Field Detail

EMPTY_REALM

static final SecurityRealm EMPTY_REALM

An empty security realm.

Method Detail

getRealmIdentity

default RealmIdentity getRealmIdentity(Principal principal)
                                throws RealmUnavailableException

Get a handle for to the identity for the given principal in the context of this security realm. Any validation / name mapping is an implementation detail for the realm. The identity may or may not exist. The returned handle must be cleaned up by a call to RealmIdentity.dispose().

Parameters:

principal - the principal which identifies the identity within the realm (must not be null)

Returns:

the RealmIdentity for the provided principal (not null)

Throws:

RealmUnavailableException

getRealmIdentity

default RealmIdentity getRealmIdentity(Evidence evidence)
                                throws RealmUnavailableException

Get a handle for to the identity for the given evidence in the context of this security realm. Any validation / name mapping is an implementation detail for the realm. The identity may or may not exist. The returned handle must be cleaned up by a call to RealmIdentity.dispose(). Where this method is used to obtain a RealmIdentity prior to evidence verification the method RealmIdentity.getEvidenceVerifySupport(Class, String) will be used to verify if the identity is usable.

Parameters:

evidence - an evidence instance which identifies the identity within the realm (must not be null)

Returns:

the RealmIdentity for the provided evidence (not null)

Throws:

RealmUnavailableException

getCredentialAcquireSupport

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

Deprecated. Transition method; remove before GA.

Throws:

RealmUnavailableException

getCredentialAcquireSupport

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

Determine whether a credential of the given type and algorithm is definitely obtainable, possibly obtainable (for] some identities), or definitely not obtainable.

Parameters:

credentialType - the exact credential type (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

Throws:

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

getEvidenceVerifySupport

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

Determine whether a given type of evidence is definitely verifiable, possibly verifiable (for some identities), or definitely not verifiable.

Parameters:

evidenceType - the type of evidence to be verified (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 evidence type

Throws:

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

handleRealmEvent

default void handleRealmEvent(RealmEvent event)

Handle a realm event. These events allow the realm to act upon occurrences that are relevant to policy of the realm; for example, the realm may choose to increase password iteration count on authentication success, or change the salt of a password after a certain number of authentications.

The default implementation does nothing.

Parameters:

event - the realm event

safeHandleRealmEvent

static void safeHandleRealmEvent(SecurityRealm realm,
                                 RealmEvent event)

Safely pass an event to a security realm, absorbing and logging any exception that occurs.

Parameters:

realm - the security realm to notify (not null)

event - the event to send (not null)