Authentication services

Classes are provided by the IBM^® Toolbox for Java™ that interact with the security services provided by i5/OS™. Specifically, support is provided to authenticate a user identity, sometimes referred to as a principal, and password against the i5/OS user registry. A credential representing the authenticated user can then be established. You can use the credential to alter the identity of the current i5/OS thread to perform work under the authorities and permissions of the authenticated user. In effect, this swap of identity results in the thread acting as if a signon was performed by the authenticated user.

Note: The services to establish and swap credentials are only supported for servers at release V5R1M0 or greater.

Overview of support provided

The AS400 object provides authentication for a given user profile and password against the server. You can also retrieve Kerberos tickets and profile tokens that represent authenticated user profiles and passwords for the system.

Note: Using Kerberos tickets requires that you install J2SDK, v1.4 and configure the Java General Security Services (JGSS) Application Programming Interface. For more information about JGSS, see the J2SDK, v1.4 Security Documentation Link outside information center

To use Kerberos tickets, set only the system name (and not the password) into the AS400 object. The user identity is retrieved through the JGSS framework. You can set only one means of authentication in an AS400 object at a time. Setting the password clears any Kerberos ticket or profile token.

To use profile tokens, use the getProfileToken() methods to retrieve instances of the ProfileTokenCredential class. Think of profile tokens as a representation of an authenticated user profile and password for a specific server. Profile tokens expire based on time, up to one hour, but can be refreshed in certain cases to provide an extended life span.

Note: If you use the ProfileTokenCredential class, make sure to review the information at the bottom of this page that discuss the methods for setting tokens.

The following example creates a system object and uses that object to generate a profile token. The example then uses the profile token to create another system object, and uses the second system object to connect to the command service:

     AS400 system = new AS400("mySystemName", "MYUSERID", "MYPASSWORD");
     ProfileTokenCredential myPT = system.getProfileToken();
     AS400 system2 = new AS400("mySystemName", myPT);
     system2.connectService(AS400.COMMAND);

Setting thread identities

You can establish a credential on either a remote or local context. Once created, you can serialize or distribute the credential as required by the calling application. When passed to a running process on the associated server, a credential can be used to modify or swap the i5/OS thread identity and perform work on behalf of the previously authenticated user.

A practical application of this support might be in a two tier application, with authentication of a user profile and password being performed by a graphical user interface on the first tier (i.e. a PC) and work being performed for that user on the second tier (the server). By utilizing ProfileTokenCredentials, the application can avoid directly passing user IDs and passwords over the network. The profile token can then be distributed to the program on the second tier, which can perform the swap() and operate under the i5/OS authorities and permissions assigned to the user.

Note: While inherently more secure than passing a user profile and password due to limited life span, profile tokens should still be considered sensitive information by the application and handled accordingly. Since the token represents an authenticated user and password, it could potentially be exploited by a hostile application to perform work on behalf of that user. It is ultimately the responsibility of the application to ensure that credentials are accessed in a secure manner.

Methods for setting tokens in ProfileTokenCredential

The methods for setting tokens in ProfileTokenCredential class require that you distinguish different ways to specify passwords:

As a special value, such as *NOPWD or *NOPWDCHK, by using a defined special value integer
As the password for the user profile by using a String that represents the password

Note: In V5R3, IBM Toolbox for Java deprecates the setToken methods that do not require you to distinguish how to specify the password.

Additionally, the setToken methods allow remote users to specify password special values and allow longer user profile passwords of up to 128 characters.

To specify a password special value integer, such as *NOPWD or *NOPWDCHK, use one of the following methods:

setToken(AS400Principal principal, int passwordSpecialValue)
setToken(String name, int passwordSpecialValue)

The ProfileTokenCredential class includes the following static constants for password special value integers:

ProfileTokenCredential.PW_NOPWD: indicates *NOPWD
ProfileTokenCredential.PW_NOPWDCHK: indicates *NOPWDCHK

To specify a user profile password as a String, use one of the following methods:

setTokenExtended(AS400Principal principal, String password)
setTokenExtended(String name, String password)

The setTokenExended methods do not allow you to pass password special value strings as the password parameter. For example, these methods do not allow a password string of *NOPWD.

For more information, see the following Javadoc reference information:

ProfileTokenCredential

Example

Refer to this code for an example of how to use a profile token credential to swap the i5/OS thread identity and perform work on behalf of a specific user.