Package com.ibm.itim.authentication

Provides an application programming interface for authentication that supports different trusted identity stores.

See:
Description

Interface Summary

AuthenticationProvider	AuthenticationProvider is an interface for authenticating a user using a specific implementation of a specific authentication mechanism.
AuthenticationProviderFactory	AuthenticationProviderFactory is an interface for constructing AuthenticationProviders.
Authenticator	Authenticator is an interface for authenticating a user given a set of user credentials.

Class Summary

AuthenticationAuthority	AuthenticationAuthority is a class that implements the Authenticator interface for authenticating a user that is independent of the authentication mechanism being used.
Credentials	Credentials is a class that extends the Hashtable class for holding a user's credentials for authentication.

Exception Summary

AuthenticationException	AuthenticationException is a class that extends the Exception class for identifying exceptions that are originated from within the Authentication package.
AuthenticationFailedException	AuthenticationFailedException is a class that extends the AuthenticationException class for identifying authentication failure exceptions.
ConfigurationException	ConfigurationException is a class that extends the AuthenticationException class for identifying configuration exceptions.

Package com.ibm.itim.authentication Description

Provides an application programming interface for authentication that supports different trusted identity stores.

The authentication extensible framework and API has been developed to satisfy two specific goals. One goal is to enable the use of different trusted identity stores. For example, a customer may want to make use of the identity information stored on a Windows NT domain server or an LDAP directory.

Figure - 1 Use of Windows NT domain server for identity store

Another goal is to enable the use of different types of keys, typically passwords, to unlock the application to the user. For example, the use of a SecureID token could be used instead of the typical hashed password.

The java-based framework that satisfies these goals is called by the Identity Manager provisioning platform at any time it needs to authenticate a user. The interface used by the platform is abstracted so that any custom extensions would be hidden, and therefore the presence of these extensions will have no impact on the overall design of the platform itself.

There are two primary audiences, or types of clients, that will use this API. One type of client will make authentication requests to the framework, like the Identity Manager provisioning platform. The other type of client will extend the framework to customize the way the authentication is performed. In the interest of limiting the amount of education each of these audiences may require, the Authentication API will be described in two smaller pieces. The Authentication Client API will focus on making authentication requests. The Authentication Provider API will focus on implementing the authentication requests.

Client API Description

The Authentication Client API is very focused on just asking for a user to be authenticated, and therefore, is very simple in nature. It consists of only one class, the SystemAuthenticationAuthority. The SystemAuthenticationAuthority is a singleton class, meaning only one instance is needed per process. To obtain this global instance, a static method is provided named getInstance. One this instance has been retrieved, the authenticateStrongly method can be used to perform the authentication.

The authenticateStrongly method takes in a set of credentials (represented by the Credentials class) and returns an instance of the SystemUser representing the authenticated credentials if those credentials are valid. If the credentials are invalid, an AuthenticationFailedException will be thrown.

The following code snippet illustrates the use of the client API:

try {

    // Get the global instance of SystemAuthenticationAuthority

    SystemAuthenticationAuthority authority = SystemAuthenticationAuthority.getInstance();

    Credentials userCredentials = new Credentials();

    // Indicate the type of credentials to "simple" (name and password)

    userCredentials.setCredential(SystemAuthenticationAuthority.CREDENTIALS_TYPE,
        "enrole.authentication.provider.simple");

    // Specify the name and password

    userCredentials.setCredential(Authenticator.PRINCIPAL, "joe");

    userCredentials.setCredential(Authenticator.KEY, new String("cool").getBytes());

    // Authenticate credentials

    SystemUser user = authority.authenticate(userCredentials);

    // Perform operations for authenticated user

    System.out.println("authentication successful");

} catch(AuthenticationException e) {

    // Handle unsuccessful authentication attempt

    System.out.println(e.toString());

}

Provider API Description

The purpose of the Provider API is to allow custom extensions to the authentication framework. A client attempting to authenticate a user will not use this portion of the API, but instead, a client what wishes to override the behavior of the system when other clients attempt to authenticate a user.

The authentication framework consists of the SystemAuthenticationAuthority class (mentioned in the Client API) which makes use of one or more AuthenticationProvider classes to implement the actual authentication algorithms. The SystemAuthenticationAuthority itself merely constructs the correct AuthenticationProvider based on the type of credentials being used and defers to that provider to perform the actual authentication logic. So, to extend or customize the authentication logic to be performed, a client would create their own AuthenticationProvider and register it with the SystemAuthenticationAuthority.

The AuthenticationProvider class is a java interface. Its purpose is to define the method signatures needed for the SystemAuthenticationAuthority to use for authentication. The method that is used for this has the same signature as the authenticateStrongly method in the SystemAuthenticationAuthority discussed in the previous section. When a class implements the AuthenticationProvider interface, it will also implement the logic to be used within the authenticateStrongly method.

In order to make the implementation of the authentication calls totally transparent to a client requesting authentication, the SystemAuthenticationAuthority must be able to determine which implementation class of the AuthenticationProvider interface to use during a request. This is achieved through the use of factories that can be specified to the SystemAuthenticationAuthority within the enRoleAuthentication.properties file. The client that creates the AuthenticationProvider implementation will also provide an implementation of the AuthenticationProviderFactory interface. This interface will be called by the SystemAuthenticationAuthority when it needs to create a new AuthenticationProvider implementation. Because the details that go into setting up the context and constructing an AuthenticationProvider may be quite different between implementations, the factory’s purpose is to hide those differences and perform the construction behind a standard interface. This interface is defined with the create method. This create method performs its implementation specific construction and returns an instance of an AuthenticationProvider interface.

The enroleAuthentication.properties files holds assignments of AuthenticationProvider classes to authentication mechanisms. Two of the mechanisms are used when a user authenticates to the provisioning server, (user id and password) and certificate. There is one additional mechanism, service, which is how connectors authenticate to the provisioning platform. To assign an AuthenticationProvider to one of these mechanisms, place the full class name of the corresponding AuthenticationProviderFactory in the file. See below for the default enRoleAuthentication.properties file that is installed with the platform.

###########################################################
## Authentication information
###########################################################
# Indicates the type of credentials required by end-user
# for authentication. Choices are: simple, certificate
enrole.authentication.requiredCredentials=simple

# Supported authentication providers
# simple provider
enrole.authentication.provider.simple=\
factory=com.ibm.itim.authentication.simple.SimpleAuthentication

# ProviderFactory
# certificate provider
#enrole.authentication.provider.certificate=\
#    factory=com.ibm.itim.authentication.certificate.CertificateAuthenticationProviderFactory
# service provider
enrole.authentication.provider.service=\
    factory=com.ibm.itim.authentication.service.ServiceAuthenticationProviderFactory