com.novell.emframe.dev
Class AuthenticationBroker

java.lang.Object
  com.novell.emframe.dev.AuthenticationBroker

public class AuthenticationBroker

extends java.lang.Object

Used by iManager to manage authentication and connections to various trees or servers. Can use many different protocols to create connections to trees or servers.

New Namespace related calls have been created to help make more code protocol independent. The hope is we will be able to write code that can work in both LDAP and NDAP environments with minimal logic to handle special cases.

New Methods

There are two new methods. One method getProtocolObject(java.lang.String) was added to AuthenticationBroker. The method is the same as getAPIObject(java.lang.String) except for two things.
1) It throws AuthBrokerException and
2) It accepts as a parameter the value PROTOCOL_ADMINNAMESPACE.
When this parameter is passed in, it will give you the currently authenticated namespace. Please note, PROTOCOL_ADMINNAMESPACE cannot be used with the 'old' getAPIObject method.

The second new method is ObjectEntry.getAdminNamespace. getAdminNamespace returns the namespace from the ObjectEntry. This method reduces the need to cast the return object to a Namespace or similar object. You should treat the returning namespace as an AdminNamespace, not as NDSNamespace.

Old Approach
AuthenticationBroker broker = m_context.getAuthenticationBroker();
ObjectEntry m_treeOE = (ObjectEntry) broker.getAPIObject("NDSNamespace");
NDSNamespace m_ns = (NDSNamespace) m_treeOE.getNamespace();

New Approach
AuthenticationBroker broker = m_context.getAuthenticationBroker();
ObjectEntry m_treeOE = (ObjectEntry) broker.getProtocolObject (AuthenticationBroker.PROTOCOL_ADMINNAMESPACE);
AdminNamespace m_ns = m_treeOE.getAdminNamespace();

Creating your own connections

You can get the credentials used to login to iManager using the getAuthNdapName(), getAuthPIdentity(), and getAuthNdapAccessDomain() calls. You can then use these credentials to attempt to connect to another back-end resource (database, web service, etc...). Any connections made must be cleaned up by the creator of the connection.

You can also get a raw JNDI LDAP connection to the directory using getAPIObject( PROTOCOL_JNDI_LDAP ). This hands back a bound JNDI LDAP connection to the directory. The task is responsible for cleaning up this JNDI LDAP connection.

Field Summary

static java.lang.String	PROTOCOL_ADMINNAMESPACE Authenticated Namespace.
static java.lang.String	PROTOCOL_ALLPROTOCOLS All available protocols.
static java.lang.String	PROTOCOL_ECB EJBs using reflection.
static java.lang.String	PROTOCOL_JNDI_LDAP JNDI connections over LDAP.
static java.lang.String	PROTOCOL_LDAPNAMESPACE LDAP connections.
static java.lang.String	PROTOCOL_NAAS NSure Audit.
static java.lang.String	PROTOCOL_NCS Clustering file system.
static java.lang.String	PROTOCOL_NDPS NDPS connections.
static java.lang.String	PROTOCOL_NDSNAMESPACE NCP connections.
static java.lang.String	PROTOCOL_NPSFILE CIFS access for Novell Portal Services.
static java.lang.String	PROTOCOL_NSS NSS file system.
static java.lang.String	PROTOCOL_PORTALCONNECTION Novell Portal Services connections.

Method Summary

void	addAuthBrokerListener(AuthBrokerListener newListener) Adds a listener to for notification of Authentication Broker events.
java.lang.Object	checkAPIObject(java.lang.String protocolId) Method to check for the associated APIObject with the specified protocol id.
static AuthenticationBroker	createAuthenticationBroker(java.lang.String ldapName, java.lang.String ndapName, java.lang.String password, java.lang.String ldapAccessDomain, java.lang.String ndapAccessDomain, boolean useLdapSSL, ManagementServiceSet manageSS) Returns an AuthenticationBroker.
static AuthenticationBroker	createAuthenticationBroker(java.lang.String ldapName, java.lang.String ndapName, java.lang.String password, java.lang.String ldapAccessDomain, java.lang.String ndapAccessDomain, boolean useLdapSSL, ManagementServiceSet manageSS, java.lang.String portalTreename) Deprecated. In iManager 2.5, there is no concept of a portal tree. Use the other createAuthenticationBroker instead without the portalTreename variable.
protected void	finalize() Clean up the protocols when garbage is collected.
java.lang.Object	getAPIObject(java.lang.String protocolId) Method to get the associated APIObject with the specified protocol id.
java.lang.Object	getAPIObject(java.lang.String protocolId, java.util.Properties properties) This is the method to get the required APIObject using a protocol based upon LazyAuthentication.
AuthBrokerReport	getAPIReport(java.lang.String protocolId) Similar to the getAPIObject call.
java.lang.String	getAuthLdapAccessDomain() Gets the LDAP address required to log in to LDAP protocols with.
java.lang.String	getAuthLdapDefaultClearPort() Based upon the LDAP server and LDAP group object of eDir, this returns the port number to use for clear LDAP access.
java.lang.String	getAuthLdapDefaultSSLPort() Based upon the LDAP server and LDAP group object of eDir, this returns the port number to use for SSL LDAP access.
java.lang.String	getAuthLdapName() Gets the fully qualified LDAP user name associated with this authentication broker.
java.lang.String	getAuthNdapAccessDomain() Gets the NDAP address required to log in to NDAP protocols with.
java.lang.String	getAuthNdapName() Gets the full NDAP user name in "." format associated with this authentication broker.
java.lang.String	getAuthPIdentity() Gets the password used to log into this tree.
java.lang.String	getAuthTreeName() Gets the tree name to where this broker will be connecting the protocols.
boolean	getAuthUseLdapSSL() Gets the full NDAP user name in "." format associated with this authentication broker.
java.lang.String[]	getIdentity() Gets a String array containing all identity information.
java.lang.Object	getProtocolObject(java.lang.String protocolId) Method to get the associated protocol object with the specified protocol id.
boolean	isUsingNPSTree() Deprecated. No replacement since NPS has been removed in iManager 2.5.
void	logoutAll() Log out of all active protocols that have been accessed.
void	removeAuthBrokerListener(AuthBrokerListener oldListener) Removes a listener from notification of Authentication Broker events.
static void	staticDestroyAll() The anti-method to initializing the protocols once for all instances of the AuthenticationBroker.

Methods inherited from class java.lang.Object

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

Field Detail

PROTOCOL_ADMINNAMESPACE

public static final java.lang.String PROTOCOL_ADMINNAMESPACE

Authenticated Namespace.

See Also:

Constant Field Values

PROTOCOL_ALLPROTOCOLS

public static final java.lang.String PROTOCOL_ALLPROTOCOLS

All available protocols.

See Also:

Constant Field Values

PROTOCOL_ECB

public static final java.lang.String PROTOCOL_ECB

EJBs using reflection.

See Also:

Constant Field Values

PROTOCOL_JNDI_LDAP

public static final java.lang.String PROTOCOL_JNDI_LDAP

JNDI connections over LDAP.

See Also:

Constant Field Values

PROTOCOL_LDAPNAMESPACE

public static final java.lang.String PROTOCOL_LDAPNAMESPACE

LDAP connections.

See Also:

Constant Field Values

PROTOCOL_NAAS

public static final java.lang.String PROTOCOL_NAAS

NSure Audit.

See Also:

Constant Field Values

PROTOCOL_NCS

public static final java.lang.String PROTOCOL_NCS

Clustering file system.

See Also:

Constant Field Values

PROTOCOL_NDPS

public static final java.lang.String PROTOCOL_NDPS

NDPS connections.

See Also:

Constant Field Values

PROTOCOL_NDSNAMESPACE

public static final java.lang.String PROTOCOL_NDSNAMESPACE

NCP connections.

See Also:

Constant Field Values

PROTOCOL_NPSFILE

public static final java.lang.String PROTOCOL_NPSFILE

CIFS access for Novell Portal Services.

See Also:

Constant Field Values

PROTOCOL_NSS

public static final java.lang.String PROTOCOL_NSS

NSS file system.

See Also:

Constant Field Values

PROTOCOL_PORTALCONNECTION

public static final java.lang.String PROTOCOL_PORTALCONNECTION

Novell Portal Services connections.

See Also:

Constant Field Values

Method Detail

addAuthBrokerListener

public void addAuthBrokerListener(AuthBrokerListener newListener)
                           throws AuthBrokerException

Adds a listener to for notification of Authentication Broker events. The same listener may be added multiple times. Notification of the events will be sent for each occurance that the listener is added.

Parameters:

newListener - listener to be added.

Throws:

AuthBrokerException - if the new listener is null or of the wrong class type an AuthBrokerException is thrown

See Also:

removeAuthBrokerListener(com.novell.emframe.dev.AuthBrokerListener)

checkAPIObject

public java.lang.Object checkAPIObject(java.lang.String protocolId)
                                throws AuthBrokerException

Method to check for the associated APIObject with the specified protocol id. If this specific APIObject has already been created and retrieved it will be returned. If it has not been created, NULL will be returned. This does not cause the associated authenticator to create the APIObject. In other words, this checks if getAPIObject() has been called yet.

Parameters:

protocolId - - the protocol that is being requested

Returns:

object that was created by the protocols login method else null if it has not been created yet.

Throws:

AuthBrokerException - - an exception

See Also:

getAPIObject(java.lang.String)

createAuthenticationBroker

public static AuthenticationBroker createAuthenticationBroker(java.lang.String ldapName,
                                                              java.lang.String ndapName,
                                                              java.lang.String password,
                                                              java.lang.String ldapAccessDomain,
                                                              java.lang.String ndapAccessDomain,
                                                              boolean useLdapSSL,
                                                              ManagementServiceSet manageSS)

Returns an AuthenticationBroker.

Parameters:

ldapName - The username in fully qualified LDAP format. If not provided this should be set to null. This parameter is optional, however at least a ldapName or a ndapName must be provided. Both may also be provided. Example: "cn=admin,ou=provo,o=novell"

ndapName - The full username in NDAP "." format. If not provided this should be set to null. This parameter is optional, however at least a ldapName or a ndapName must be provided. Both may also be provided. Example: "admin.provo.novell"

password - the users password

ldapAccessDomain - The IP address or dns name of the ldap server to connect to. An optional port may be provided as a colon separated part of the address. If not provided this should be set to null. This parameter is optional, however at least a ldapAccessDomain or a ndapAccessDomain must be provided. Both may also be provided.

ndapAccessDomain - The tree - this is preferred to be an IP address but may be a tree name If it is a tree name the API's must be able to locate the tree via the available discovery mechanisms. If it is an IP address, an optional port may be provided as a colon separated part of the address. If this parameter is not provided it should be set to null. This parameter is optional, however at least a ldapAccessDomain or a ndapAccessDomain must be provided. Both may also be provided.

useLdapSSL - Flag set to true if SSL binds should be used for LDAP type protocols. If a port is provided as part of the ldapAccessDomain, it must be the correct port to use SSL.

manageSS - The management service set for this authentication broker. This value will be cached for later use.

Returns:

A valid AuthenticationBroker. Resources of the broker will not be consumed until first requested by a user.

createAuthenticationBroker

public static AuthenticationBroker createAuthenticationBroker(java.lang.String ldapName,
                                                              java.lang.String ndapName,
                                                              java.lang.String password,
                                                              java.lang.String ldapAccessDomain,
                                                              java.lang.String ndapAccessDomain,
                                                              boolean useLdapSSL,
                                                              ManagementServiceSet manageSS,
                                                              java.lang.String portalTreename)

Deprecated. In iManager 2.5, there is no concept of a portal tree. Use the other createAuthenticationBroker instead without the portalTreename variable.

Returns an AuthenticationBroker.

Parameters:

ldapName - The username in fully qualified LDAP format. If not provided this should be set to null. This parameter is optional, however at least a ldapName or a ndapName must be provided. Both may also be provided. Example: "cn=admin,ou=provo,o=novell"

ndapName - The full username in NDAP "." format. If not provided this should be set to null. This parameter is optional, however at least a ldapName or a ndapName must be provided. Both may also be provided. Example: "admin.provo.novell"

password - the users password

ldapAccessDomain - The IP address or dns name of the ldap server to connect to. An optional port may be provided as a colon separated part of the address. If not provided this should be set to null. This parameter is optional, however at least a ldapAccessDomain or a ndapAccessDomain must be provided. Both may also be provided.

ndapAccessDomain - The tree - this is preferred to be an IP address but may be a tree name If it is a tree name the API's must be able to locate the tree via the available discovery mechanisms. If it is an IP address, an optional port may be provided as a colon separated part of the address. If this parameter is not provided it should be set to null. This parameter is optional, however at least a ldapAccessDomain or a ndapAccessDomain must be provided. Both may also be provided.

useLdapSSL - Flag set to true if SSL binds should be used for LDAP type protocols. If a port is provided as part of the ldapAccessDomain, it must be the correct port to use SSL.

manageSS - The management service set for this authentication broker. This value will be cached for later use.

portalTreename - The name of the tree the portal we are using is associated with.

Returns:

A valid AuthenticationBroker. Resources of the broker will not be consumed until first requested by a user.

finalize

protected void finalize()
                 throws java.lang.Throwable

Clean up the protocols when garbage is collected. The logoutAll() method is synchronized on the active proto item hash so it should be thread safe. Make sure and call the super classes finalize in case there is one or one is added later

Throws:

java.lang.Throwable - because the super.finalize did and we just pass that on.

getAPIObject

public java.lang.Object getAPIObject(java.lang.String protocolId)
                              throws AuthBrokerWrappedRuntimeException

Method to get the associated APIObject with the specified protocol id.

To return the AdminNamespace that is currently authenticated, use getProtocolObject instead.

This call will return an Object that you can use to communicate with the directory. The AuthenticationBroker has been modified to create the protocol and login the first time the protocol is requested. An exception could be thrown to the user the first time the user request that specific protocol. It is thrown as a runtime exception that ecapsulated the real exception so that current callers do not have to change.

Generally, you will use PROTOCOL_NDSNAMESPACE and get back an ObjectEntry Object. You can also get a raw JNDI LDAP connection to the directory using getAPIObject( PROTOCOL_JNDI_LDAP ). This hands back a bound JNDI LDAP connection to the directory. The task is responsible for cleaning up this JNDI LDAP connection.

Parameters:

protocolId - - the protocol that is being requested

Returns:

object that was created by the protocols login method

Throws:

AuthBrokerWrappedRuntimeException - - a runtime exception that need not be caught but contains error information if unable to successfully login into the protocol the first time.

See Also:

checkAPIObject(java.lang.String), getAPIReport(java.lang.String), getProtocolObject(java.lang.String)

getAPIObject

public java.lang.Object getAPIObject(java.lang.String protocolId,
                                     java.util.Properties properties)
                              throws AuthBrokerException

This is the method to get the required APIObject using a protocol based upon LazyAuthentication. Lazy Authentication means that the authentication/login does not happen until it is requested. This method will call an authenticate() method on the LazyAuthBrokerAuthenticator and that newly created APIObject is returned to the user. The user will have full control over this APIObject and it is their responsibility to see that it is free'ed or cleaned up.

Note: If the requested protocol is not an implementation of Lazy Authentication an error will be thrown

To return the AdminNamespace that is currently authenticated, use getProtocolObject instead.

Parameters:

protocolId - - identifies which Lazy protocol to use.

properties - - additional paramaters for the authenticate method of the protocol

Returns:

the newly created APIObject

Throws:

AuthBrokerException

See Also:

getProtocolObject(java.lang.String)

getAPIReport

public AuthBrokerReport getAPIReport(java.lang.String protocolId)
                              throws AuthBrokerException

Similar to the getAPIObject call. Authenticators have the ability to have furthur information with the loginAPIObject if they wish. For Example: When you log into eDir with NDSNamespace you can successfully log in, BUT you may actually have a -223 error that you password has expired. The loginAPIObject is valid and will be returned by the getAPIObject call, but if the user wants, they can query and get the report which will indicate that a -223 error occurred. The content of the auth report is defined between the Authenticator and the user. It is simply passed back here. If a AuthBrokerReport was not returned from the Authenticator, one will be created by this method where the report type is unknown and the loginAPIObject is the object returned from the Authenticator's login call. The userData and aeException will be null

Parameters:

protocolId - The protocol that is being requested

Returns:

a valid AuthBrokerReport

Throws:

AuthBrokerException - - a exception from the Authenticator's login method if login was not successful

See Also:

getAPIObject(java.lang.String)

getAuthLdapAccessDomain

public java.lang.String getAuthLdapAccessDomain()

Gets the LDAP address required to log in to LDAP protocols with. This will be the ldapAccessDomain provided to the broker at creation or, if not provided, will be determined from the ndapAccessDomain. If the provided ldapAccessDomain is returned, this may or may not have an associated port depending on how it was provided. If it is determined from the ndapAccessDomain, it will not have a port and the default port should be used based upon the useLdapSSL flag. The default clear port is 389 and the default SSL port is 636.

Returns:

String containing the LDAP access domain

getAuthLdapDefaultClearPort

public java.lang.String getAuthLdapDefaultClearPort()

Based upon the LDAP server and LDAP group object of eDir, this returns the port number to use for clear LDAP access. If that cannot be determined from the eDir objects, the LDAP default of 389 will be returned.

Returns:

String containing the non-SSL port for LDAP connections

getAuthLdapDefaultSSLPort

public java.lang.String getAuthLdapDefaultSSLPort()

Based upon the LDAP server and LDAP group object of eDir, this returns the port number to use for SSL LDAP access. If that cannot be determined from the eDir objects, the LDAP default SSL port of 636 will be returned.

Returns:

String containing the SSL port for LDAP connections

getAuthLdapName

public java.lang.String getAuthLdapName()
                                 throws AuthBrokerException

Gets the fully qualified LDAP user name associated with this authentication broker. This will be the LDAP name provided to the broker at creation time or, if not provided, will use the resources of the broker and the management service set to determine the LDAP name from the provided NDAP name. The resources required to do this are heavy weight.

Returns:

String containing the fully qualified LDAP user name

Throws:

AuthBrokerException - if there is an authentication problem

getAuthNdapAccessDomain

public java.lang.String getAuthNdapAccessDomain()

Gets the NDAP address required to log in to NDAP protocols with. This will be the ndapAccessDomain provided to the broker at creation or, if not provided, will be determined from the ldapAccessDomain. If the provided ndapAccessDomain is returned, this may or may not have an associated port depending on how it was provided. If it is determined from the ldapAccessDomain, it will not have a port and the default port of 524 should be used.

Returns:

String containing the NDAP access domain

getAuthNdapName

public java.lang.String getAuthNdapName()
                                 throws AuthBrokerException

Gets the full NDAP user name in "." format associated with this authentication broker. This will be the NDAP name provided to the broker at creation time or, if not provided, will use the resources of the broker and the management service set to determine the NDAP name from the provided LDAP name. This involves indepth parsing of the provided LDAP name. The resources required to do this are light weight.

Returns:

String containing the full NDAP user name

Throws:

AuthBrokerException - if there is an authentication problem

getAuthPIdentity

public java.lang.String getAuthPIdentity()

Gets the password used to log into this tree.

Returns:

String containing the password

getAuthTreeName

public java.lang.String getAuthTreeName()

Gets the tree name to where this broker will be connecting the protocols.

Returns:

String containing the tree name

getAuthUseLdapSSL

public boolean getAuthUseLdapSSL()
                          throws AuthBrokerException

Gets the full NDAP user name in "." format associated with this authentication broker. This will be the NDAP name provided to the broker at creation time or, if not provided, will use the resources of the broker and the management service set to determine the NDAP name from the provided LDAP name. This involves indepth parsing of the provided LDAP name. The resources required to do this are light weight.

Returns:

boolean true if SSL is used for LDAP connection, false if otherwise

Throws:

AuthBrokerException - if there is a problem with SSL communication

getIdentity

public java.lang.String[] getIdentity()

Gets a String array containing all identity information.

Returns:

String array containing the username, password, and access domain

getProtocolObject

public java.lang.Object getProtocolObject(java.lang.String protocolId)
                                   throws AuthBrokerException

Method to get the associated protocol object with the specified protocol id. Generally, you will want to call this method with PROTOCOL_ADMINNAMESPACE, and the Object returned will be an ObjectEntry from which you can get the AdminNamespace object (which is a wrapper around the NDSNamespace and LDAPNamespace objects).

The AuthenticationBroker has been modified to create the protocol and login the first time the protocol is requested. An exception could be thrown to the user the first time the user request that specific protocol.

Parameters:

protocolId - String containing the protocol that is being requested

Returns:

Object that was created by the protocols login method (generally an ObjectEntry)

Throws:

AuthBrokerException - A runtime exception that need not be caught but contains error information if unable to successfully login into the protocol the first time.

See Also:

getAPIObject(java.lang.String), checkAPIObject(java.lang.String), getAPIReport(java.lang.String)

isUsingNPSTree

public boolean isUsingNPSTree()

Deprecated. No replacement since NPS has been removed in iManager 2.5.

Gets whether the connection is to the NPS tree. This call is no longer valid.

Returns:

true always

logoutAll

public void logoutAll()

Log out of all active protocols that have been accessed.

removeAuthBrokerListener

public void removeAuthBrokerListener(AuthBrokerListener oldListener)
                              throws AuthBrokerException

Removes a listener from notification of Authentication Broker events. Since a listener may be added multiple times, the last listener added that matches is removed.

Parameters:

oldListener - listener to be added.

Throws:

AuthBrokerException - if the old listener to remove is null or of the wrong class type an AuthBrokerException is thrown. An exception is not thrown if the old listener is not found as a registered listener.

See Also:

addAuthBrokerListener(com.novell.emframe.dev.AuthBrokerListener)

staticDestroyAll

public static void staticDestroyAll()

The anti-method to initializing the protocols once for all instances of the AuthenticationBroker. It goes through the internal staticProtoHash and calls the destroy() method for each of the protocol classes. It is used to uninitialize things like JClient. This does not do anything concerning logout. All instances of the AuthenticationBroker should fully be logged out before this is called, otherwise things may be yanked from underneath active credentials.