Package org.wildfly.security.auth.client

Class AuthenticationConfiguration

java.lang.Object
org.wildfly.security.auth.client.AuthenticationConfiguration
public final class AuthenticationConfiguration extends Object
A configuration which controls how authentication is performed.
Author:
David M. Lloyd, Darran Lofthouse

  • Field Details

    • EMPTY

      @Deprecated public static final AuthenticationConfiguration EMPTY
      Deprecated.
      to obtain empty configuration use empty() method instead
      An empty configuration which can be used as the basis for any configuration. This configuration supports no remapping of any kind, and always uses an anonymous principal.

  • Method Details

    • empty

      public static AuthenticationConfiguration empty()
      An empty configuration which can be used as the basis for any configuration. This configuration supports no remapping of any kind, and always uses an anonymous principal.

    • rewriteUser

      public AuthenticationConfiguration rewriteUser(org.wildfly.security.auth.server.NameRewriter rewriter)
      Create a new configuration which is the same as this configuration, but rewrites the user name using the given name rewriter. The name rewriter is appended to the the existing name rewrite function.
      Parameters:
      rewriter - the name rewriter
      Returns:
      the new configuration

    • rewriteUserOnlyWith

      public AuthenticationConfiguration rewriteUserOnlyWith(org.wildfly.security.auth.server.NameRewriter rewriter)
      Create a new configuration which is the same as this configuration, but rewrites the user name using only the given name rewriter. Any name rewriters on this configuration are ignored for the new configuration.
      Parameters:
      rewriter - the name rewriter
      Returns:
      the new configuration

    • useAnonymous

      public AuthenticationConfiguration useAnonymous()
      Create a new configuration which is the same as this configuration, but which uses an anonymous login.
      Returns:
      the new configuration

    • usePrincipal

      public AuthenticationConfiguration usePrincipal(org.wildfly.security.auth.principal.NamePrincipal principal)
      Create a new configuration which is the same as this configuration, but which uses the given principal to authenticate.
      Parameters:
      principal - the principal to use (must not be null)
      Returns:
      the new configuration

    • usePrincipal

      public AuthenticationConfiguration usePrincipal(Principal principal)
      Create a new configuration which is the same as this configuration, but which uses the given principal to authenticate.
      Parameters:
      principal - the principal to use (must not be null)
      Returns:
      the new configuration

    • useName

      public AuthenticationConfiguration useName(String name)
      Create a new configuration which is the same as this configuration, but which uses the given login name to authenticate.
      Parameters:
      name - the principal to use (must not be null)
      Returns:
      the new configuration

    • useAuthorizationName

      public AuthenticationConfiguration useAuthorizationName(String name)
      Create a new configuration which is the same as this configuration, but which attempts to authorize to the given name after authentication. Only mechanisms which support an authorization name principal will be selected.
      Parameters:
      name - the name to use, or null to not request authorization in the new configuration
      Returns:
      the new configuration

    • useAuthorizationPrincipal

      public AuthenticationConfiguration useAuthorizationPrincipal(Principal principal)
      Create a new configuration which is the same as this configuration, but which attempts to authorize to the given principal after authentication. Only mechanisms which support an authorization principal of the given type will be selected.
      Parameters:
      principal - the principal to use, or null to not request authorization in the new configuration
      Returns:
      the new configuration

    • useCredential

      public AuthenticationConfiguration useCredential(Credential credential)
      Create a new configuration which is the same as this configuration, but which uses the given credential to authenticate.
      Parameters:
      credential - the credential to authenticate
      Returns:
      the new configuration

    • usePassword

      public AuthenticationConfiguration usePassword(Password password)
      Create a new configuration which is the same as this configuration, but which uses the given password to authenticate.
      Parameters:
      password - the password to use
      Returns:
      the new configuration

    • usePassword

      public AuthenticationConfiguration usePassword(char[] password)
      Create a new configuration which is the same as this configuration, but which uses the given password to authenticate.
      Parameters:
      password - the password to use
      Returns:
      the new configuration

    • usePassword

      public AuthenticationConfiguration usePassword(String password)
      Create a new configuration which is the same as this configuration, but which uses the given password to authenticate.
      Parameters:
      password - the password to use
      Returns:
      the new configuration

    • useMaskedPassword

      public AuthenticationConfiguration useMaskedPassword(MaskedPassword password) throws NoSuchAlgorithmException, InvalidKeySpecException
      Create a new configuration which is the same as this configuration, but converts the given masked password to a clear password and uses the clear password to authenticate.
      Parameters:
      password - the password to use
      Returns:
      the new configuration
      Throws:
      NoSuchAlgorithmException - if algorithm used to get PasswordFactory instance is invalid
      InvalidKeySpecException - if invalid spec is used to generate password

    • useMaskedPassword

      public AuthenticationConfiguration useMaskedPassword(byte[] maskedPasswordBytes, String algorithm, char[] initialKeyMaterial, int iterationCount, byte[] salt, byte[] initializationVector) throws NoSuchAlgorithmException, InvalidKeySpecException
      Create a new configuration which is the same as this configuration, but which uses the given masked password to authenticate.
      Parameters:
      maskedPasswordBytes - the masked password bytes (must not be null)
      algorithm - the algorithm (can be null, default:"masked-MD5-DES")
      initialKeyMaterial - the initial key material (can be null, default:"somearbitrarycrazystringthatdoesnotmatter")
      iterationCount - the iteration count (must not be less than 1)
      salt - the salt bytes (must not be null)
      initializationVector - the initialization vector (can be null)
      Returns:
      the new configuration
      Throws:
      NoSuchAlgorithmException - if algorithm used to get PasswordFactory instance is invalid
      InvalidKeySpecException - if invalid spec is used to generate password

    • useMaskedPassword

      public AuthenticationConfiguration useMaskedPassword(String maskedPassword, String algorithm, String initialKeyMaterial, int iterationCount, String salt, String initializationVector) throws InvalidKeySpecException, NoSuchAlgorithmException
      Create a new configuration which is the same as this configuration, but which uses the given masked password to authenticate.
      Parameters:
      maskedPassword - the masked password, as a string (must not be null)
      algorithm - the algorithm (can be null, default:"masked-MD5-DES")
      initialKeyMaterial - the initial key material, as a string(can be null, default:"somearbitrarycrazystringthatdoesnotmatter")
      iterationCount - the iteration count, as an integer (must not be less than 1)
      salt - the salt, as a string (must not be null)
      initializationVector - the initialization vector, as a string (can be null)
      Returns:
      the new configuration
      Throws:
      NoSuchAlgorithmException - if algorithm used to get PasswordFactory instance is invalid
      InvalidKeySpecException - if invalid spec is used to generate password

    • useCredentialCallbackHandler

      public AuthenticationConfiguration useCredentialCallbackHandler(CallbackHandler callbackHandler)
      Create a new configuration which is the same as this configuration, but which uses the given callback handler to acquire a password with which to authenticate, when a password-based authentication algorithm is in use.
      Parameters:
      callbackHandler - the password callback handler
      Returns:
      the new configuration

    • useCallbackHandler

      public AuthenticationConfiguration useCallbackHandler(CallbackHandler callbackHandler)
      Create a new configuration which is the same as this configuration, but which uses the given callback handler to authenticate.

      Important notes: It is important to ensure that each distinct client identity uses a distinct CallbackHandler instance in order to avoid mis-pooling of connections, identity crossovers, and other potentially serious problems. It is not recommended that a CallbackHandler implement equals() and hashCode(), however if it does, it is important to ensure that these methods consider equality based on an authenticating identity that does not change between instances. In particular, a callback handler which requests user input on each usage is likely to cause a problem if the user name can change on each authentication request.

      Because CallbackHandler instances are unique per identity, it is often useful for instances to cache identity information, credentials, and/or other authentication-related information in order to facilitate fast re-authentication.

      Parameters:
      callbackHandler - the callback handler to use
      Returns:
      the new configuration

    • useCallbackHandler

      public AuthenticationConfiguration useCallbackHandler(CallbackHandler callbackHandler, Set<CallbackKind> callbackKinds)
      Create a new configuration which is the same as this configuration, but which uses the given callback handler to authenticate.

      Important notes: It is important to ensure that each distinct client identity uses a distinct CallbackHandler instance in order to avoid mis-pooling of connections, identity crossovers, and other potentially serious problems. It is not recommended that a CallbackHandler implement equals() and hashCode(), however if it does, it is important to ensure that these methods consider equality based on an authenticating identity that does not change between instances. In particular, a callback handler which requests user input on each usage is likely to cause a problem if the user name can change on each authentication request.

      Because CallbackHandler instances are unique per identity, it is often useful for instances to cache identity information, credentials, and/or other authentication-related information in order to facilitate fast re-authentication.

      Parameters:
      callbackHandler - the callback handler to use
      callbackKinds - the kinds of callbacks that the handler should use
      Returns:
      the new configuration

    • useGSSCredential

      public AuthenticationConfiguration useGSSCredential(GSSCredential credential)
      Create a new configuration which is the same as this configuration, but which uses the given GSS-API credential to authenticate.
      Parameters:
      credential - the GSS-API credential to use
      Returns:
      the new configuration

    • useKeyStoreCredential

      public AuthenticationConfiguration useKeyStoreCredential(KeyStore.Entry keyStoreEntry)
      Create a new configuration which is the same as this configuration, but which uses the given key store and alias to acquire the credential required for authentication.
      Parameters:
      keyStoreEntry - the key store entry to use
      Returns:
      the new configuration

    • useKeyStoreCredential

      public AuthenticationConfiguration useKeyStoreCredential(KeyStore keyStore, String alias)
      Create a new configuration which is the same as this configuration, but which uses the given key store and alias to acquire the credential required for authentication.
      Parameters:
      keyStore - the key store to use
      alias - the key store alias
      Returns:
      the new configuration

    • useKeyStoreCredential

      public AuthenticationConfiguration useKeyStoreCredential(KeyStore keyStore, String alias, KeyStore.ProtectionParameter protectionParameter)
      Create a new configuration which is the same as this configuration, but which uses the given key store and alias to acquire the credential required for authentication.
      Parameters:
      keyStore - the key store to use
      alias - the key store alias
      protectionParameter - the protection parameter to use to access the key store entry
      Returns:
      the new configuration

    • useCertificateCredential

      public AuthenticationConfiguration useCertificateCredential(PrivateKey privateKey, X509Certificate... certificateChain)
      Create a new configuration which is the same as this configuration, but which uses the given private key and X.509 certificate chain to authenticate.
      Parameters:
      privateKey - the client private key
      certificateChain - the client certificate chain
      Returns:
      the new configuration

    • useCertificateCredential

      public AuthenticationConfiguration useCertificateCredential(X509CertificateChainPrivateCredential credential)
      Create a new configuration which is the same as this configuration, but which uses the given private key and X.509 certificate chain to authenticate.
      Parameters:
      credential - the credential containing the private key and certificate chain
      Returns:
      the new configuration

    • useCredentialStoreEntry

      public AuthenticationConfiguration useCredentialStoreEntry(CredentialStore credentialStore, String alias)
      Create a new configuration which is the same as this configuration, but uses credentials found at the given alias and credential store.
      Parameters:
      credentialStore - the credential store (must not be null)
      alias - the alias within the store (must not be null)
      Returns:
      the new configuration

    • useKeyManagerCredential

      public AuthenticationConfiguration useKeyManagerCredential(X509KeyManager keyManager)
      Create a new configuration which is the same as this configuration, but which uses the given key manager to acquire the credential required for authentication.
      Parameters:
      keyManager - the key manager to use
      Returns:
      the new configuration

    • useLocalKerberosCredential

      @Deprecated public AuthenticationConfiguration useLocalKerberosCredential(Oid[] mechanismOids)
      Deprecated.
      can be ommited - kerberos based authentication mechanism obtains credential himself
      Create a new configuration which is the same as this configuration, but which uses local kerberos ticket cache to acquire the credential required for authentication.
      Parameters:
      mechanismOids - array of oid's indicating the mechanisms over which the credential is to be acquired
      Returns:
      the new configuration
      Since:
      1.2.0

    • useCredentials

      public AuthenticationConfiguration useCredentials(org.wildfly.security.credential.source.CredentialSource credentials)
      Create a new configuration which is the same as this configuration, but which uses the given identity credentials to acquire the credential required for authentication.
      Parameters:
      credentials - the credentials to use
      Returns:
      the new configuration

    • useChoice

      public AuthenticationConfiguration useChoice(BiPredicate<Class<? extends ChoiceCallback>,String> matchPredicate, String choice)
      Create a new configuration which is the same as this configuration, but which uses the given choice if the given predicate evaluates to true.
      Parameters:
      matchPredicate - the predicate that should be used to determine if a choice callback type and prompt are relevant for the given choice
      choice - the choice to use if the given predicate evaluates to true
      Returns:
      the new configuration

    • useParameterSpec

      public AuthenticationConfiguration useParameterSpec(AlgorithmParameterSpec parameterSpec)
      Create a new configuration which is the same as this configuration, but which uses the given parameter specification.
      Parameters:
      parameterSpec - the algorithm parameter specification to use
      Returns:
      the new configuration

    • useTrustManager

      public AuthenticationConfiguration useTrustManager(X509TrustManager trustManager)
      Create a new configuration which is the same as this configuration, but which uses the given trust manager for trust verification.
      Parameters:
      trustManager - the trust manager to use or null if the default trust manager should be used
      Returns:
      the new configuration

    • useHost

      @Deprecated public AuthenticationConfiguration useHost(String hostName)
      Deprecated.
      This configuration is not supported by most providers and will be removed in a future release.
      Create a new configuration which is the same as this configuration, but which connects to a different host name.
      Parameters:
      hostName - the host name to connect to
      Returns:
      the new configuration

    • useProtocol

      @Deprecated public AuthenticationConfiguration useProtocol(String protocol)
      Deprecated.
      This configuration is not supported by most providers and will be removed in a future release.
      Create a new configuration which is the same as this configuration, but which specifies a different protocol to be used for outgoing connection.
      Parameters:
      protocol - the protocol to be used for outgoing connection.
      Returns:
      the new configuration

    • useSaslProtocol

      public AuthenticationConfiguration useSaslProtocol(String saslProtocol)
      Create a new configuration which is the same as this configuration, but which specifies a different protocol to be passed to the authentication mechanisms.
      Parameters:
      saslProtocol - the protocol to pass to the authentication mechanisms.
      Returns:
      the new configuration

    • useWebServices

      public AuthenticationConfiguration useWebServices(Map<String,?> webservicesProperties)

    • usePort

      @Deprecated public AuthenticationConfiguration usePort(int port)
      Deprecated.
      This configuration is not supported by most providers and will be removed in a future release.
      Create a new configuration which is the same as this configuration, but which connects to a different port.
      Parameters:
      port - the port to connect to, or -1 to not override the port
      Returns:
      the new configuration

    • useForwardedIdentity

      public AuthenticationConfiguration useForwardedIdentity(org.wildfly.security.auth.server.SecurityDomain securityDomain)
      Create a new configuration which is the same as this configuration, but which forwards the authentication name and credentials from the current identity of the given security domain.
      Parameters:
      securityDomain - the security domain
      Returns:
      the new configuration

    • useForwardedAuthenticationIdentity

      public AuthenticationConfiguration useForwardedAuthenticationIdentity(org.wildfly.security.auth.server.SecurityDomain securityDomain)
      Create a new configuration which is the same as this configuration, but which forwards the authentication name from the current identity of the given security domain.
      Parameters:
      securityDomain - the security domain
      Returns:
      the new configuration

    • useForwardedAuthenticationCredentials

      public AuthenticationConfiguration useForwardedAuthenticationCredentials(org.wildfly.security.auth.server.SecurityDomain securityDomain)
      Create a new configuration which is the same as this configuration, but which forwards the authentication credentials from the current identity of the given security domain.
      Parameters:
      securityDomain - the security domain
      Returns:
      the new configuration

    • useForwardedAuthorizationIdentity

      public AuthenticationConfiguration useForwardedAuthorizationIdentity(org.wildfly.security.auth.server.SecurityDomain securityDomain)
      Create a new configuration which is the same as this configuration, but which forwards the authorization name from the current identity of the given security domain.
      Parameters:
      securityDomain - the security domain
      Returns:
      the new configuration

    • useProviders

      public AuthenticationConfiguration useProviders(Supplier<Provider[]> providerSupplier)
      Use the given security provider supplier to locate security implementations.
      Parameters:
      providerSupplier - the provider supplier
      Returns:
      the new configuration

    • useDefaultProviders

      public AuthenticationConfiguration useDefaultProviders()
      Use the default provider discovery behaviour of combining service loader discovered providers with the system default security providers when locating security implementations.
      Returns:
      the new configuration

    • useProvidersFromClassLoader

      public AuthenticationConfiguration useProvidersFromClassLoader(ClassLoader classLoader)
      Use security providers from the given class loader.
      Parameters:
      classLoader - the class loader to search for security providers
      Returns:
      the new configuration

    • useSaslClientFactory

      public AuthenticationConfiguration useSaslClientFactory(SaslClientFactory saslClientFactory)
      Use a pre-existing SaslClientFactory instead of discovery.
      Parameters:
      saslClientFactory - the pre-existing SaslClientFactory to use.
      Returns:
      the new configuration.

    • useSaslClientFactory

      public AuthenticationConfiguration useSaslClientFactory(Supplier<SaslClientFactory> saslClientFactory)
      Use the given sasl client factory supplier to obtain the SaslClientFactory to use.
      Parameters:
      saslClientFactory - the sasl client factory supplier to use.
      Returns:
      the new configuration.

    • useSaslClientFactoryFromProviders

      public AuthenticationConfiguration useSaslClientFactoryFromProviders()
      Use provider based discovery to load available SaslClientFactory implementations.
      Returns:
      the new configuration.

    • useMechanismProperties

      @Deprecated public AuthenticationConfiguration useMechanismProperties(Map<String,?> mechanismProperties)
      Deprecated.
      use useSaslMechanismProperties(Map)
      Create a new configuration which is the same as this configuration, but which sets the properties that will be passed to the SaslClientFactory when the mechanism is created. Existing properties defined on this authentication context will be retained unless overridden by new properties, any properties resulting with a value of null will be removed.
      Parameters:
      mechanismProperties - the properties to be passed to the SaslClientFactory to create the mechanism.
      Returns:
      the new configuration.

    • useSaslMechanismProperties

      public AuthenticationConfiguration useSaslMechanismProperties(Map<String,?> mechanismProperties)
      Create a new configuration which is the same as this configuration, but which sets the properties that will be passed to the SaslClientFactory when the mechanism is created. Existing properties defined on this authentication context will be retained unless overridden by new properties, any properties resulting with a value of null will be removed.
      Parameters:
      mechanismProperties - the properties to be passed to the SaslClientFactory to create the mechanism.
      Returns:
      the new configuration.

    • useMechanismProperties

      @Deprecated public AuthenticationConfiguration useMechanismProperties(Map<String,?> mechanismProperties, boolean exclusive)
      Deprecated.
      use useSaslMechanismProperties(Map, boolean)
      Create a new configuration which is the same as this configuration, but which sets the properties that will be passed to the SaslClientFactory when the mechanism is created. If exclusive the existing properties will be discarded and replaced with the new properties otherwise existing properties defined on this authentication context will be retained unless overridden by new properties, any properties resulting with a value of null will be removed.
      Parameters:
      mechanismProperties - the properties to be passed to the SaslClientFactory to create the mechanism.
      exclusive - should the provided properties be used exclusively or merged with the existing properties?
      Returns:
      the new configuration.

    • useSaslMechanismProperties

      public AuthenticationConfiguration useSaslMechanismProperties(Map<String,?> mechanismProperties, boolean exclusive)
      Create a new configuration which is the same as this configuration, but which sets the properties that will be passed to the SaslClientFactory when the mechanism is created. If exclusive the existing properties will be discarded and replaced with the new properties otherwise existing properties defined on this authentication context will be retained unless overridden by new properties, any properties resulting with a value of null will be removed.
      Parameters:
      mechanismProperties - the properties to be passed to the SaslClientFactory to create the mechanism.
      exclusive - should the provided properties be used exclusively or merged with the existing properties?
      Returns:
      the new configuration.

    • useWebServicesProperties

      public AuthenticationConfiguration useWebServicesProperties(Map<String,?> webServicesProperties)
      Create a new configuration which is the same as this configuration, but which sets the properties that can be used by WebServices client.
      Parameters:
      webServicesProperties - the properties that can be used by WS client.
      Returns:
      the new configuration.

    • useKerberosSecurityFactory

      @Deprecated public AuthenticationConfiguration useKerberosSecurityFactory(org.wildfly.security.SecurityFactory<? extends Credential> kerberosSecurityFactory)
      Deprecated.
      Create a new configuration which is the same as this configuration, but which uses the given kerberos security factory to acquire the GSS credential required for authentication.
      Parameters:
      kerberosSecurityFactory - a reference to the kerberos security factory to be use
      Returns:
      the new configuration

    • setSaslMechanismSelector

      public AuthenticationConfiguration setSaslMechanismSelector(SaslMechanismSelector saslMechanismSelector)
      Set the SASL mechanism selector for this authentication configuration.
      Parameters:
      saslMechanismSelector - the SASL mechanism selector, or null to clear the current selector
      Returns:
      the new configuration

    • useRealm

      public AuthenticationConfiguration useRealm(String realm)
      Create a new configuration which is the same as this configuration, but uses the given realm for authentication.
      Parameters:
      realm - the realm to use, or null to accept the default realm always
      Returns:
      the new configuration

    • useBearerTokenCredential

      public AuthenticationConfiguration useBearerTokenCredential(BearerTokenCredential credential)
      Create a new configuration which is the same as this configuration, but which uses the given BearerTokenCredential to authenticate.
      Parameters:
      credential - the bearer token credential to use
      Returns:
      the new configuration

    • withCapturedAccessControlContext

      public AuthenticationConfiguration withCapturedAccessControlContext()
      Create a new configuration which is the same as this configuration, but which captures the caller's access control context to be used in authentication decisions.
      Returns:
      the new configuration

    • with

      public AuthenticationConfiguration with(AuthenticationConfiguration other)
      Create a new configuration which is the same as this configuration, but which adds or replaces every item in the other configuration with that item, overwriting any corresponding such item in this configuration.
      Parameters:
      other - the other authentication configuration
      Returns:
      the merged authentication configuration

    • captureAuthorizationIdentity

      public AuthenticationConfiguration captureAuthorizationIdentity()
      Create a new configuration which is the same as this configuration, but which attempts to authorize to the principal from the current identity from the configured security domain.
      Returns:
      the new configuration

    • equals

      public boolean equals(Object obj)
      Determine whether this configuration is equal to another object. Two configurations are equal if they apply the same items.
      Overrides:
      equals in class Object
      Parameters:
      obj - the other object
      Returns:
      true if they are equal, false otherwise

    • equals

      public boolean equals(AuthenticationConfiguration other)
      Determine whether this configuration is equal to another object. Two configurations are equal if they apply the same items.
      Parameters:
      other - the other object
      Returns:
      true if they are equal, false otherwise

    • hashCode

      public int hashCode()
      Get the hash code of this authentication configuration.
      Overrides:
      hashCode in class Object
      Returns:
      the hash code of this authentication configuration

    • toString

      public String toString()
      Overrides:
      toString in class Object