Package org.wildfly.security.auth.server

Interface SecurityRealm

All Known Subinterfaces:

CacheableSecurityRealm, ModifiableSecurityRealm

All Known Implementing Classes:

AggregateSecurityRealm, CachingModifiableSecurityRealm, CachingSecurityRealm, DistributedSecurityRealm, FailoverSecurityRealm, FileSystemSecurityRealm, JaasSecurityRealm, JdbcSecurityRealm, KeyStoreBackedSecurityRealm, LdapSecurityRealm, LegacyPropertiesSecurityRealm, OidcSecurityRealm, SimpleMapBackedSecurityRealm, TokenSecurityRealm

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	Description
static SecurityRealm	EMPTY_REALM	An empty security realm.

Method Summary

Modifier and Type	Method	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(Principal principal)	Get a handle for to the identity for the given principal in the context of this security realm.
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(Evidence evidence, Function<Principal,Principal> principalTransformer)	Get a handle for the identity for the given evidence 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

getRealmIdentity

default RealmIdentity getRealmIdentity(Evidence evidence,
                                       Function<Principal,Principal> principalTransformer)
                                throws RealmUnavailableException

Get a handle for 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 principal obtained is transformed prior to obtaining the authorization identity. 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)

principalTransformer - a function which defines how the principal is transformed before the authorization identity is obtained

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)