Package org.wildfly.security.auth.server

Class SecurityDomain

java.lang.Object

org.wildfly.security.auth.server.SecurityDomain

public final class SecurityDomain
extends Object

A security domain. Security domains encapsulate a set of security policies.

Author:

David M. Lloyd, Darran Lofthouse

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	SecurityDomain.Builder	A builder for creating new security domains.
static class	SecurityDomain.RealmBuilder	A builder for a realm within a security domain.

Method Summary

Modifier and Type	Method	Description
SecurityIdentity	authenticate(String name, Evidence evidence)	Perform an authentication based on Evidence for the specified identity name.
SecurityIdentity	authenticate(Principal principal, Evidence evidence)	Perform an authentication based on Evidence for the specified identity Principal.
SecurityIdentity	authenticate(Evidence evidence)	Perform an authentication based on Evidence alone.
static SecurityDomain.Builder	builder()	Create a new security domain builder.
SecurityIdentity	createAdHocIdentity(String name)	Create an empty ad-hoc identity.
SecurityIdentity	createAdHocIdentity(Principal principal)	Create an empty ad-hoc identity.
ServerAuthenticationContext	createNewAuthenticationContext()	Create a new authentication context for this security domain which can be used to carry out a single authentication operation.
ServerAuthenticationContext	createNewAuthenticationContext(MechanismConfigurationSelector mechanismConfigurationSelector)	Create a new authentication context for this security domain which can be used to carry out a single authentication operation.
static SecurityDomain	forIdentity(SecurityIdentity identity)	Get the security domain associated with the given identity.
SecurityIdentity	getAnonymousSecurityIdentity()	Get the anonymous security identity for this realm.
SupportLevel	getCredentialAcquireSupport(Class<? extends Credential> credentialType)	Determine whether a credential of the given type and algorithm is definitely obtainable, possibly obtainable (for some identities), or definitely not obtainable.
SupportLevel	getCredentialAcquireSupport(Class<? extends Credential> credentialType, String algorithmName)	Determine whether a credential of the given type and algorithm is definitely obtainable, possibly obtainable (for some identities), or definitely not obtainable.
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.
static SecurityDomain	getCurrent()	Get the SecurityDomain associated with the context class loader of the calling Thread or null if one is not associated.
SecurityIdentity	getCurrentSecurityIdentity()	Get the current security identity for this domain.
SupportLevel	getEvidenceVerifySupport(Class<? extends Evidence> evidenceType)	Determine whether a given type of evidence is definitely verifiable, possibly verifiable (for some identities), or definitely not verifiable.
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.
RealmIdentity	getIdentity(String name)	Look up a RealmIdentity by name by wrapping the name in a NamePrincipal and calling getIdentity(Principal).
RealmIdentity	getIdentity(Principal principal)	Look up a RealmIdentity by principal.
ModifiableRealmIdentity	getIdentityForUpdate(Principal principal)	Look up a ModifiableRealmIdentity by principal.
org.wildfly.common.function.ExceptionFunction<Principal,ModifiableRealmIdentity,RealmUnavailableException>	getIdentityLookupForUpdateFunction()	Get a function which can be used to look up principals for update without a security manager permission check.
org.wildfly.common.function.ExceptionFunction<Principal,RealmIdentity,RealmUnavailableException>	getIdentityLookupFunction()	Get a function which can be used to look up principals without a security manager permission check.
static ScheduledExecutorService	getScheduledExecutorService()	Gets ScheduledExecutorService for authentication related scheduled task (like authentication timeout).
void	handleSecurityEvent(SecurityEvent securityEvent)	Handle a SecurityEvent.
void	registerWithClassLoader(ClassLoader classLoader)	Register this SecurityDomain with the specified ClassLoader.
static void	unregisterClassLoader(ClassLoader classLoader)	Unregister any SecurityDomain associated with the specified ClassLoader.

Methods inherited from class java.lang.Object

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

Method Detail

registerWithClassLoader

public void registerWithClassLoader(ClassLoader classLoader)

Register this SecurityDomain with the specified ClassLoader. Registration with enabled security manager requires registerSecurityDomain ElytronPermission.

Parameters:

classLoader - the non null ClassLoader to associate this SecurityDomain with.

Throws:

IllegalStateException - If a SecurityDomain is already associated with the specified ClassLoader.

getCurrent

public static SecurityDomain getCurrent()

Get the SecurityDomain associated with the context class loader of the calling Thread or null if one is not associated. Obtaining security domain with enabled security manager requires getSecurityDomain ElytronPermission.

Returns:

the SecurityDomain associated with the context class loader of the calling Thread or null if one is not associated.

forIdentity

public static SecurityDomain forIdentity(SecurityIdentity identity)

Get the security domain associated with the given identity. Obtaining security domain with enabled security manager requires getSecurityDomain ElytronPermission.

Parameters:

identity - the security identity (must not be null)

Returns:

the identity's security domain (not null)

unregisterClassLoader

public static void unregisterClassLoader(ClassLoader classLoader)

Unregister any SecurityDomain associated with the specified ClassLoader. Unregistration with enabled security manager requires unregisterSecurityDomain ElytronPermission.

Parameters:

classLoader - the non null ClassLoader to clear any SecurityDomain association.

builder

public static SecurityDomain.Builder builder()

Create a new security domain builder.

Returns:

the builder

createNewAuthenticationContext

public ServerAuthenticationContext createNewAuthenticationContext()

Create a new authentication context for this security domain which can be used to carry out a single authentication operation. Calling with enabled security manager requires createServerAuthenticationContext ElytronPermission.

Returns:

the new authentication context

createNewAuthenticationContext

public ServerAuthenticationContext createNewAuthenticationContext(MechanismConfigurationSelector mechanismConfigurationSelector)

Create a new authentication context for this security domain which can be used to carry out a single authentication operation. Calling with enabled security manager requires createServerAuthenticationContext ElytronPermission.

Parameters:

mechanismConfigurationSelector - the selector to use to obtain the mechanism configuration

Returns:

the new authentication context

authenticate

public SecurityIdentity authenticate(Evidence evidence)
                              throws RealmUnavailableException,
                                     SecurityException

Perform an authentication based on Evidence alone. Note: It is the caller's responsibility to destroy any evidence passed into this method.

Parameters:

evidence - the Evidence to use for authentication.

Returns:

the authenticated identity.

Throws:

RealmUnavailableException - if the requires SecurityRealm is not available.

SecurityException - if authentication fails.

authenticate

public SecurityIdentity authenticate(String name,
                                     Evidence evidence)
                              throws RealmUnavailableException,
                                     SecurityException

Perform an authentication based on Evidence for the specified identity name. Note: It is the caller's responsibility to destroy any evidence passed into this method.

Parameters:

name - the name of the identity to authenticate or null if the identity is to be derived from the evidence.

evidence - the Evidence to use for authentication.

Returns:

the authenticated identity.

Throws:

RealmUnavailableException - if the requires SecurityRealm is not available.

SecurityException - if authentication fails.

authenticate

public SecurityIdentity authenticate(Principal principal,
                                     Evidence evidence)
                              throws RealmUnavailableException,
                                     SecurityException

Perform an authentication based on Evidence for the specified identity Principal. Note: It is the caller's responsibility to destroy any evidence passed into this method. Calling with enabled security manager requires authenticate ElytronPermission.

Parameters:

principal - the principal of the identity to authenticate or null if the identity is to be derived from the evidence.

evidence - the Evidence to use for authentication.

Returns:

the authenticated identity.

Throws:

RealmUnavailableException - if the requires SecurityRealm is not available.

SecurityException - if authentication fails.

getIdentity

public RealmIdentity getIdentity(String name)
                          throws RealmUnavailableException

Look up a RealmIdentity by name by wrapping the name in a NamePrincipal and calling getIdentity(Principal). The returned identity must be disposed.

Parameters:

name - the name to map (must not be null)

Returns:

the identity for the name (not null, may be non-existent)

Throws:

RealmUnavailableException - if the realm is not able to perform the mapping

IllegalArgumentException - if the name is not valid

SecurityException - if the caller is not authorized to perform the operation

getIdentity

public RealmIdentity getIdentity(Principal principal)
                          throws RealmUnavailableException,
                                 IllegalArgumentException

Look up a RealmIdentity by principal. The returned identity must be disposed. Calling with enabled security manager requires getIdentity ElytronPermission.

Parameters:

principal - the principal to map (must not be null)

Returns:

the identity for the name (not null, may be non-existent)

Throws:

IllegalArgumentException - if the principal could not be successfully decoded to a name

RealmUnavailableException - if the realm is not able to perform the mapping

SecurityException - if the caller is not authorized to perform the operation

getIdentityForUpdate

public ModifiableRealmIdentity getIdentityForUpdate(Principal principal)
                                             throws RealmUnavailableException,
                                                    IllegalArgumentException

Look up a ModifiableRealmIdentity by principal. The returned identity must be disposed. Calling with enabled security manager requires getIdentityForUpdate ElytronPermission.

Parameters:

principal - the principal to map (must not be null)

Returns:

the identity for the name (not null, may be non-existent)

Throws:

IllegalArgumentException - if the principal could not be successfully decoded to a name

RealmUnavailableException - if the realm is not able to perform the mapping

SecurityException - if the caller is not authorized to perform the operation

getIdentityLookupFunction

public org.wildfly.common.function.ExceptionFunction<Principal,RealmIdentity,RealmUnavailableException> getIdentityLookupFunction()

Get a function which can be used to look up principals without a security manager permission check. All returned identities must be disposed. Calling with enabled security manager requires getIdentity ElytronPermission.

Returns:

the lookup function (not null)

Throws:

SecurityException - if the caller is not authorized to perform the operation

getIdentityLookupForUpdateFunction

public org.wildfly.common.function.ExceptionFunction<Principal,ModifiableRealmIdentity,RealmUnavailableException> getIdentityLookupForUpdateFunction()

Get a function which can be used to look up principals for update without a security manager permission check. All returned identities must be disposed. Calling with enabled security manager requires getIdentityForUpdate ElytronPermission.

Returns:

the lookup function (not null)

Throws:

SecurityException - if the caller is not authorized to perform the operation

getCredentialAcquireSupport

public 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. Credential is SupportLevel.SUPPORTED, if it is supported by all realms of the domain. Credential is SupportLevel.POSSIBLY_SUPPORTED if it is supported or possibly supported by at least one realm of the domain. Otherwise it is SupportLevel.UNSUPPORTED.

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

getCredentialAcquireSupport

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

Determine whether a credential of the given type and algorithm is definitely obtainable, possibly obtainable (for some identities), or definitely not obtainable. Credential is SupportLevel.SUPPORTED, if it is supported by all realms of the domain. Credential is SupportLevel.POSSIBLY_SUPPORTED if it is supported or possibly supported by at least one realm of the domain. Otherwise it is SupportLevel.UNSUPPORTED.

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

Returns:

the level of support for this credential

getCredentialAcquireSupport

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

Determine whether a credential of the given type and algorithm is definitely obtainable, possibly obtainable (for some identities), or definitely not obtainable. Credential is SupportLevel.SUPPORTED, if it is supported by all realms of the domain. Credential is SupportLevel.POSSIBLY_SUPPORTED if it is supported or possibly supported by at least one realm of the domain. Otherwise it is SupportLevel.UNSUPPORTED.

Parameters:

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

Returns:

the level of support for this credential

getEvidenceVerifySupport

public 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. Evidence is SupportLevel.SUPPORTED, if it is supported by all realms of the domain. Evidence is SupportLevel.POSSIBLY_SUPPORTED if it is supported or possibly supported by at least one realm of the domain. Otherwise it is SupportLevel.UNSUPPORTED.

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

getEvidenceVerifySupport

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

Determine whether a given type of evidence is definitely verifiable, possibly verifiable (for some identities), or definitely not verifiable. Evidence is SupportLevel.SUPPORTED, if it is supported by all realms of the domain. Evidence is SupportLevel.POSSIBLY_SUPPORTED if it is supported or possibly supported by at least one realm of the domain. Otherwise it is SupportLevel.UNSUPPORTED.

Parameters:

evidenceType - the type of evidence to be verified (must not be null)

Returns:

the level of support for this evidence type

getCurrentSecurityIdentity

public SecurityIdentity getCurrentSecurityIdentity()

Get the current security identity for this domain. Code can be executed with given identity using SecurityIdentity.runAs* methods.

Returns:

the current security identity for this domain (not null)

getAnonymousSecurityIdentity

public SecurityIdentity getAnonymousSecurityIdentity()

Get the anonymous security identity for this realm.

Returns:

the anonymous security identity for this realm (not null)

createAdHocIdentity

public SecurityIdentity createAdHocIdentity(String name)

Create an empty ad-hoc identity. The identity will have no authorization information and no credentials associated with it.

Parameters:

name - the identity name (must not be null)

Returns:

the ad-hoc identity

createAdHocIdentity

public SecurityIdentity createAdHocIdentity(Principal principal)

Create an empty ad-hoc identity. The identity will have no authorization information and no credentials associated with it. Calling with enabled security manager requires createAdHocIdentity ElytronPermission.

Parameters:

principal - the identity principal (must not be null)

Returns:

the ad-hoc identity

handleSecurityEvent

public void handleSecurityEvent(SecurityEvent securityEvent)

Handle a SecurityEvent. Calling with enabled security manager requires handleSecurityEvent ElytronPermission.

Parameters:

securityEvent - SecurityEvent to be handled

See Also:

SecurityDomain.Builder.setSecurityEventListener(Consumer)

getScheduledExecutorService

public static ScheduledExecutorService getScheduledExecutorService()

Gets ScheduledExecutorService for authentication related scheduled task (like authentication timeout).

Returns:

the executor service