jespa.security

Class ChainSecurityProvider

java.lang.Object

java.util.AbstractMap<K,V>

java.util.HashMap

jespa.security.Properties

jespa.security.SecurityProvider

jespa.security.ChainSecurityProvider

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, java.util.Map

public class ChainSecurityProvider
extends SecurityProvider

A wrapper SecurityProvider around a "chain" of SecurityProviders. The chain is advanced if a failure occurs in either the acceptSecContext or authenticate methods. All other methods simply call the corresponding method on the currently selected SecurityProvider in the chain.

The ChainSecurityProvider is most commonly used with the HttpSecurityService to authenticate web clients against multiple independent security authorities.

Note: It is not necessary to use the ChainSecurityProvider for Active Directory domains that have trust relationships. The NtlmSecurityProvider fully supports cross domain authentication by itself.

A chain is defined entirely using properties. The chain.names property defines the list of chain element names. For each chain element name, the property chain.<name>.provider.classname indicates to ChainSecurityProvider the name of the SecurityProvider class to construct for that chain element. For all other properties that begin with chain.<name>., that prefix is removed and the property is inserted into the Map used to construct the SecurityProvider for that chain element. Consider the following list of properties:

chain.names = BUSICORP,OPENBOOK

chain.BUSICORP.provider.classname = jespa.ntlm.NtlmSecurityProvider
chain.BUSICORP.bindstr = busicorp.local
chain.BUSICORP.service.acctname = jespa1$@busicorp.local
chain.BUSICORP.service.password = opensaysme44
chain.BUSICORP.account.canonicalForm = 3 

chain.OPENBOOK.provider.classname = jespa.ldap.LdapSecurityProvider
chain.OPENBOOK.ldap.disposition = RFC
chain.OPENBOOK.domain.netbios.name = OPENBOOK 
chain.OPENBOOK.domain.dns.name = openbook.edu
chain.OPENBOOK.bindstr = ldap://192.168.2.119/OU=Engineering,DC=openbook,DC=edu
chain.OPENBOOK.service.acctname = CN=jespa1,DC=openbook,DC=edu
chain.OPENBOOK.service.password = moonbike55
chain.OPENBOOK.account.canonicalForm = 3

Properties used to initialize two SecurityProviders in the ChainSecurityProvdier.

The above example shows two SecurityProviders in a chain called BUSICORP and OPENBOOK.

Note: Chain names are completely arbitrary although they should not contain characters like equals (=) or bracket (<) which might collide with configuration file syntax.

The BUSICORP chain uses the NtlmSecurityProvider whereas the OPENBOOK chain uses the LdapSecurityProvider configured for an RFC-based LDAP server like OpenLDAP.

The currently selected SecurityProvider in the chain is stored in the state exported by exportState and subsequently restored in importState. This is useful with stateless applications like HTTP because the ChainSecurityProvider may be reconstructed without repeatedly iterating through the chain.

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class java.util.AbstractMap

java.util.AbstractMap.SimpleEntry<K,V>, java.util.AbstractMap.SimpleImmutableEntry<K,V>

Nested classes/interfaces inherited from interface java.util.Map

java.util.Map.Entry<K,V>

Field Summary

Fields inherited from class jespa.security.SecurityProvider

identity, isComplete

Fields inherited from class jespa.security.Properties

DUPLICATE_REFERENCE, NO_PROPERTY

Constructor Summary

Constructors

Constructor and Description
ChainSecurityProvider(java.util.Map properties)

Method Summary

Modifier and Type	Method and Description
byte[]	acceptSecContext(byte[] token, int off, int len) Call acceptSecContext on each SecurityProvider in the chain until the supplied token is successfully processed.
void	authenticate(java.lang.Object credential) Call authenticate on each SecurityProvider in the chain until the supplied credentials are successfully authenticated.
void	dispose() Dispose the currently selected SecurityProvider in the chain if any.
protected void	encodeObject(ByteBuffer bb, java.lang.Object obj) Serialize this ChainSecurityProvider and underlying currently selected SecurityProvider into the supplied buffer.
java.lang.Object	exportState() Return a byte[] array representing the complete state of the currently selected SecurityProvider so that it can be reconstituted later (by possibly another thread) with the importState(java.lang.Object) method.
Account	getAccount(java.lang.String acctname, java.lang.String[] attrs) Call getAccount on the currently selected SecurityProvider in the chain.
Domain	getDomain(java.lang.String dname, java.lang.String[] attrs) Call getDomain on the currently selected SecurityProvider in the chain.
boolean	getFlag(java.lang.String name) Call getFlag on the currently selected SecurityProvider in the chain.
java.lang.String	getIdentity() Call getIdentity on the currently selected SecurityProvider in the chain.
java.lang.String	getName() Call getName on the currently selected SecurityProvider in the chain.
java.lang.Object	getProperty(java.lang.String name, java.lang.Object def) Call getProperty on the currently selected SecurityProvider in the chain (unless the property is specific to the ChainSecurityProvider).
SecurityProvider	getSecurityProvider() Return the currently selected SecurityProvider.
void	importState(java.lang.Object ostate) Initialize and set as the currrently selected SecurityProvider to the SecurityProvider deserialized from the state Object returned by a previous call to exportState().
boolean	isComplete() Call isComplete on the currently selected SecurityProvider in the chain.
void	setFlag(java.lang.String name, boolean value) Call getFlag on the currently selected SecurityProvider in the chain.
void	setProperty(java.lang.String name, java.lang.Object obj) Set a property such as a SecurityProvider specific option.

Methods inherited from class jespa.security.SecurityProvider

initSecContext, unwrap, wrap

Methods inherited from class jespa.security.Properties

decodeObject, getEncryptedProperty, getFilteredProperties, getFilteredProperties, getProperty, getPropertyAsBoolean, getPropertyAsLong, setEncryptedProperty

Methods inherited from class java.util.HashMap

clear, clone, compute, computeIfAbsent, computeIfPresent, containsKey, containsValue, entrySet, forEach, get, getOrDefault, isEmpty, keySet, merge, put, putAll, putIfAbsent, remove, remove, replace, replace, replaceAll, size, values

Methods inherited from class java.util.AbstractMap

equals, hashCode, toString

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Map

equals, hashCode

Constructor Detail

ChainSecurityProvider

public ChainSecurityProvider(java.util.Map properties)

Method Detail

setProperty

public void setProperty(java.lang.String name,
                        java.lang.Object obj)
                 throws SecurityProviderException

Description copied from class: SecurityProvider

Set a property such as a SecurityProvider specific option. See the specific SecurityProvider documentation for lists of options and their semantics.

Overrides:

setProperty in class SecurityProvider

Parameters:

name - the name of the property to set.

obj - the value of the property to set (which may be null).

Throws:

SecurityProviderException - if the property or it's value are invalid or cannot be set.

getProperty

public java.lang.Object getProperty(java.lang.String name,
                                    java.lang.Object def)
                             throws SecurityProviderException

Call getProperty on the currently selected SecurityProvider in the chain (unless the property is specific to the ChainSecurityProvider). If no provider is selected, the first provider in the chain will be created.

For details, see the API documentation for the corresponding methods of the concrete SecurityProvider classes configured for this chain.

Overrides:

getProperty in class SecurityProvider

Parameters:

name - the name of the property to retrieve.

def - the default value to return of the named property is not set.

Returns:

the property value.

Throws:

SecurityProviderException - if the name is invalid or it's value cannot be retrieved.

encodeObject

protected void encodeObject(ByteBuffer bb,
                            java.lang.Object obj)
                     throws EncodingException

Serialize this ChainSecurityProvider and underlying currently selected SecurityProvider into the supplied buffer. The developer should not be concerned with this method as it is used exclusively by the exportState method.

Overrides:

encodeObject in class jespa.security.Properties

Throws:

EncodingException

exportState

public java.lang.Object exportState()
                             throws SecurityProviderException

Return a byte[] array representing the complete state of the currently selected SecurityProvider so that it can be reconstituted later (by possibly another thread) with the importState(java.lang.Object) method. This method allows multi-step authentication to occur with stateless protocols such as HTTP. For example, the HttpSecurityService uses this method to store authentication state or state about the authenticated principal into the HTTP session.

Overrides:

exportState in class SecurityProvider

Returns:

an object (or preferrably a byte[] array) that represents the state of this SecurityProvider.

Throws:

SecurityProviderException - if the state could not or cannot be exported.

importState

public void importState(java.lang.Object ostate)
                 throws SecurityProviderException

Initialize and set as the currrently selected SecurityProvider to the SecurityProvider deserialized from the state Object returned by a previous call to exportState(). This method allows multi-step authentication to occur with stateless protocols such as HTTP. For example, the HttpSecurityService uses this method to reconstitute authentication state and state about the authenticated principal from HTTP session data.

Overrides:

importState in class SecurityProvider

Parameters:

ostate - an Object (or byte[] array) that represets the state to be imported.

Throws:

SecurityProviderException - if the state could not be imported such as because the state being imported has been transferred beyond it's acceptable boundries.

getSecurityProvider

public SecurityProvider getSecurityProvider()
                                     throws SecurityProviderException

Return the currently selected SecurityProvider. If no provider is selected, the first provider in the chain will be created.

For details, see the API documentation for the corresponding methods of the concrete SecurityProvider classes configured for this chain.

Throws:

SecurityProviderException

getName

public java.lang.String getName()
                         throws SecurityProviderException

Call getName on the currently selected SecurityProvider in the chain. If no provider is selected, the first provider in the chain will be created.

For details, see the API documentation for the corresponding methods of the concrete SecurityProvider classes configured for this chain.

Overrides:

getName in class SecurityProvider

Throws:

SecurityProviderException

getFlag

public boolean getFlag(java.lang.String name)
                throws SecurityProviderException

Call getFlag on the currently selected SecurityProvider in the chain. If no provider is selected, the first provider in the chain will be created.

For details, see the API documentation for the corresponding methods of the concrete SecurityProvider classes configured for this chain.

Overrides:

getFlag in class SecurityProvider

Parameters:

name - the name of the flag value to retrieve.

Returns:

the flag value. If the named flag is not defined, false is returned.

Throws:

SecurityProviderException

setFlag

public void setFlag(java.lang.String name,
                    boolean value)
             throws SecurityProviderException

Call getFlag on the currently selected SecurityProvider in the chain. If no provider is selected, the first provider in the chain will be created.

For details, see the API documentation for the corresponding methods of the concrete SecurityProvider classes configured for this chain.

Overrides:

setFlag in class SecurityProvider

Parameters:

name - the name of the flag to set.

value - the new value of the flag.

Throws:

SecurityProviderException

getDomain

public Domain getDomain(java.lang.String dname,
                        java.lang.String[] attrs)
                 throws SecurityProviderException

Call getDomain on the currently selected SecurityProvider in the chain. If no provider is selected, the first provider in the chain will be created.

For details, see the API documentation for the corresponding methods of the concrete SecurityProvider classes configured for this chain.

Overrides:

getDomain in class SecurityProvider

Parameters:

dname - the name of the domain to retrieve

attrs - the list of attribute names to populate in the Domain object returned

Throws:

SecurityProviderException - if the named domain could not be found or if a catostrophic error occurs.

getAccount

public Account getAccount(java.lang.String acctname,
                          java.lang.String[] attrs)
                   throws SecurityProviderException

Call getAccount on the currently selected SecurityProvider in the chain. If no provider is selected, the first provider in the chain will be created.

For details, see the API documentation for the corresponding methods of the concrete SecurityProvider classes configured for this chain.

Overrides:

getAccount in class SecurityProvider

Parameters:

acctname - the name of the account to retrieve or null to indicate that a default account should be retrieved

attrs - the names of the account attributes to retrieve or null to indicate that a default set of attriubutes should be retrieved or the special constant Account.ALL_ATTRS to indicate that "all attributes" should be retrieved.

Throws:

SecurityProviderException - if the named account could not be found or if a catostrophic error occurs.

getIdentity

public java.lang.String getIdentity()
                             throws SecurityProviderException

Call getIdentity on the currently selected SecurityProvider in the chain. If no provider is selected, null is returned.

For details, see the API documentation for the corresponding methods of the concrete SecurityProvider classes configured for this chain.

Overrides:

getIdentity in class SecurityProvider

Returns:

the canonical account name of the currently authenticated user or null if no such user has sufficiently authenticated.

Throws:

SecurityProviderException - if an error occurs trying to retrieve the identity value.

isComplete

public boolean isComplete()

Call isComplete on the currently selected SecurityProvider in the chain. If no provider is selected, false is returned.

For details, see the API documentation for the corresponding methods of the concrete SecurityProvider classes configured for this chain.

Overrides:

isComplete in class SecurityProvider

Returns:

true if authentication is complete. Otherwise, more tokens from the other peer need to be supplied to the authentication function being used.

acceptSecContext

public byte[] acceptSecContext(byte[] token,
                               int off,
                               int len)
                        throws SecurityProviderException

Call acceptSecContext on each SecurityProvider in the chain until the supplied token is successfully processed. If the SecurityProvider does not accept NTLMSSP tokens (as indicated by the capabilities.accept.ntlmssp flag), the next provider will be selected. If no provider successfully accepts the token, the last exception caught will be rethrown.

For details, see the API documentation for the corresponding methods of the concrete SecurityProvider classes configured for this chain.

Overrides:

acceptSecContext in class SecurityProvider

Parameters:

token - the buffer containing the authentication token supplied by the other peer.

off - the offset within token to the relevant data.

len - the length of the token within token at offset off.

Returns:

the token to be supplied to the other peer.

Throws:

SecurityProviderException - if a catostrophic error occured in processing. Note that unlike initSecContext, this method should not throw an exception to indicate that authentication has failed. Most errors will be encoded into a final token so as to communicate the failure to the initiator.

authenticate

public void authenticate(java.lang.Object credential)
                  throws SecurityProviderException

Call authenticate on each SecurityProvider in the chain until the supplied credentials are successfully authenticated. If no provider successfully authenticates the credential, the last exception caught will be rethrown.

For details, see the API documentation for the corresponding methods of the concrete SecurityProvider classes configured for this chain.

Overrides:

authenticate in class SecurityProvider

Parameters:

credential - a credential to be validated. Providers should support the generic PasswordCredential class.

Throws:

SecurityProviderException - if the validation fails. The exception code should be SecurityProviderException.STATUS_ACCOUNT_NOT_FOUND if the credential identity was not found by the provider authority or SecurityProviderException.STATUS_INVALID_CREDENTIALS if the credential was cryptographically incorrect. If the authority only indicated that the authentication failed in general and does not distinguish between the two cases, STATUS_INVALID_CREDENTIALS should be favored.

dispose

public void dispose()
             throws SecurityProviderException

Dispose the currently selected SecurityProvider in the chain if any.

For details, see the API documentation for the corresponding methods of the concrete SecurityProvider classes configured for this chain.

Overrides:

dispose in class SecurityProvider

Throws:

SecurityProviderException