Developing Authentication Service clients in Java

Use the Authentication Service client Java APIs, Javadoc, and the sample application source code to develop an Authentication Service client in Java.

About this task

To develop an Authentication Service client in Java, consider the following high level steps:

Use Java Authentication and Authorization Service (JAAS) interfaces to enable the authentication process. A LoginContext object is instantiated, which in turn references a Configuration to determine the authentication technologies, or LoginModules, to perform the authentication.
Provide configuration information by using a properties file, -D option, or a configuration file.
Implement logging.

Procedure

Create a login context by providing following parameters:
Name

Required parameter that determines which JAAS login modules are invoked. Its suggested value is the name of the exploiting product.

Subject

Optional parameter that specifies the user or service currently being authenticated. When it is not provided, a Subject is created and populated with the Principal and Credential information.

CallbackHandler

Required parameter that specifies the callback handler that the login modules invoke. This handler takes a set of callbacks as a parameter. Callbacks get the information required to perform the login, such as the token information and user ID and password information.

The product needs to implement a callback handler by using the JAAS callbacks; alternatively, it can use one of the callback handlers provided by the Authentication Service client.
Invoke the login method on the login context.
When the login is successful, the Subject is populated the Principal and Credential information.
To retrieve user information from the Subject, use the following getter methods:
- getPrincipals method on the Subject to get a Principal
- getName method on the Principal to get the user name
To retrieve group information from the Subject, use the following getter methods:
- getPublicCredentials(com.ibm.security.authn.Group) method to get a Group.
- getGroupIds method on the Group to return a list of group IDs
To retrieve the token from the Subject, use the following getter methods:
- getPublicCredentials(com.ibm.security.authn.CredToken) method to get credential token.
- getTokenDescriptor() method on credential token to get a token descriptor object that contains the information for this token.
Invoke the logout method on the login context.
Principal and Credential information is removed from the Subject.
Specify the JAAS configuration file by using one of the following methods:
- login.config.url.(n) property in the java.security properties file
  This option is considered best practice.
- -Djava.security.auth.login.config option on the command line
- java.login.config file in the user’s home directory
The following code block shows the entry written to the JAAS configuration file to use Authentication Service client Java API:
```
productName{
			com.ibm.security.ess.WSTrustLoginModule  required  ESSConfigFile=”authn_config_file_pathname”
			}
```
Where:
- productName is the value for the Name parameter that is specified when creating the login context.
- ESSConfigFile specifies the fully qualified path and name of the Authentication Service client properties file, which contains the configuration properties.
Implement logging by using java.util.logging.Logger facility or the Authentication Service client’s logging facility. See Authentication Service client logging.