All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class com.ibm.as400.security.auth.ProfileTokenCredential

java.lang.Object
   |
   +----com.ibm.as400.security.auth.AS400Credential
           |
           +----com.ibm.as400.security.auth.ProfileTokenCredential

public final class ProfileTokenCredential
extends AS400Credential
implements AS400BasicAuthenticationCredential
The ProfileTokenCredential class represents an AS/400 profile token.

A profile token provides a timed credential representing an authenticated AS/400 user profile and password. A profile token can be established in either a remote (not running on the target AS/400) or local (running on the target AS/400) context. Once created, it may be serialized or distributed as required by the application.

When referenced from a running process on the associated AS/400, a profile token can be used to modify or swap the OS/400 thread identity and perform a specific task or tasks on behalf of the authenticated user. However, a profile token generated on one AS/400 system cannot be used to swap thread identity on any other system.

An application of this support would be in a single tier application running on the AS/400 when a designated operation must be run under the OS/400 authorities and permissions of a specific user profile. A profile token can be used to swap identity prior to performing the operation. Support is also provided to swap back to the original identity upon completion.

Another 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 AS/400). By utilizing ProfileTokenCredentials, the application can avoid directly passing the user ID and password over the network. The profile token can be distributed as required to the program on the second tier, which can perform the swap() and run designated operations under the OS/400 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.

Profile tokens are only supported for AS/400 systems at release V4R5M0 or greater.

The following example demonstrates the use of a ProfileTokenCredential when run on the local AS/400 system:

  // Prepare to work with the local AS/400 system.
 	AS400 system = new AS400("localhost", "*CURRENT", "*CURRENT");
  // Create a single-use ProfileTokenCredential with a 60 second timeout.
  // A valid user ID and password must be substituted.
 	ProfileTokenCredential pt = new ProfileTokenCredential();
 	pt.setSystem(system);
 	pt.setTimeoutInterval(60);
 	pt.setTokenType(ProfileTokenCredential.TYPE_SINGLE_USE);
 	pt.setToken("USERID", "PASSWORD");
  // Swap the OS/400 thread identity, retrieving a credential to
  // swap back to the original identity later.
 	AS400Credential cr = pt.swap(true);
  // Perform work under the swapped identity at this point.
  // Swap back to the original OS/400 thread identity.
 	cr.swap();
  // Clean up the credentials.
 	cr.destroy();
 	pt.destroy();
 

General restrictions:

Guidelines and restrictions for generating profile tokens based on a specified user profile name and password:

See Also:
AS400Credential

Variable Index

 o TOKEN_LENGTH
Indicates the length of a profile token (in bytes)
 o TYPE_MULTIPLE_USE_NON_RENEWABLE
ID indicating a multiple use token that cannot be regenerated.
 o TYPE_MULTIPLE_USE_RENEWABLE
ID indicating a multiple use token that can be regenerated.
 o TYPE_SINGLE_USE
ID indicating a single use token.

Constructor Index

 o ProfileTokenCredential()
Constructs a ProfileTokenCredential object.
 o ProfileTokenCredential(AS400, byte[], int, int)
Constructs and initializes a ProfileTokenCredential object.

Method Index

 o equals(Object)
Compares the specified Object with the credential for equality.
 o getTimeoutInterval()
Returns the number of seconds to expiration assigned when the token was last initialized or refreshed.
 o getToken()
Returns the actual bytes for the token as it exists on the AS/400 system.
 o getTokenType()
Returns an integer indicating the type assigned when the token was last initialized or refreshed.
 o hashCode()
Returns a hash code for this credential.
 o initialize(AS400BasicAuthenticationPrincipal, String, boolean, boolean, boolean, int)
Initializes and validates a credential for the local AS/400 system.
 o isRenewable()
Indicates if the credential can be refreshed.
 o isReusable()
Indicates if the credential can be used multiple times prior to expiration.
 o refresh()
Updates or extends the validity period for the credential.
 o refresh(int, int)
Updates or extends the validity period for the credential.
 o setTimeoutInterval(int)
Sets the number of seconds to expiration when the token is generated or refreshed.
 o setToken(AS400Principal, String)
Sets the token bytes based on the provided principal and password.
 o setToken(byte[])
Sets the actual bytes for the token as it exists on the AS/400 system.
 o setToken(String, String)
Sets the token bytes based on the provided user profile and password.
 o setTokenType(int)
Sets the type of token.
 o toString()
Returns a string representation of the object

Variables

 o TYPE_SINGLE_USE
 public static int TYPE_SINGLE_USE
ID indicating a single use token.

 o TYPE_MULTIPLE_USE_NON_RENEWABLE
 public static int TYPE_MULTIPLE_USE_NON_RENEWABLE
ID indicating a multiple use token that cannot be regenerated.

 o TYPE_MULTIPLE_USE_RENEWABLE
 public static int TYPE_MULTIPLE_USE_RENEWABLE
ID indicating a multiple use token that can be regenerated.

 o TOKEN_LENGTH
 public static int TOKEN_LENGTH
Indicates the length of a profile token (in bytes)

Constructors

 o ProfileTokenCredential
 public ProfileTokenCredential()
Constructs a ProfileTokenCredential object.

The system and token must be set prior to accessing host information or taking action against the credential.

 o ProfileTokenCredential
 public ProfileTokenCredential(AS400 system,
                               byte token[],
                               int tokenType,
                               int timeoutInterval)
Constructs and initializes a ProfileTokenCredential object.

The system, token, tokenType, and timeoutInterval properties are initialized to the specified values.

This method allows a credential to be constructed based on an existing token (i.e. previously created using the QSYGENPT system API). It is the responsibility of the application to ensure the tokenType and timeoutInterval are consistent with the specified token value.

Parameters:
system - The AS/400 associated with the credential.
token - The actual bytes for the token as it exists on the AS/400 system.
tokenType - The type of token provided. Possible types are defined as fields on this class:
  • TYPE_SINGLE_USE
  • TYPE_MULTIPLE_USE_NON_RENEWABLE
  • TYPE_MULTIPLE_USE_RENEWABLE
timeoutInterval - The number of seconds to expiration, used as the default value when the token is refreshed (1-3600).

Methods

 o equals
 public boolean equals(Object o)
Compares the specified Object with the credential for equality.

Parameters:
o - Object to be compared for equality.
Returns:
true if equal; otherwise false.
Overrides:
equals in class Object
 o getTimeoutInterval
 public int getTimeoutInterval()
Returns the number of seconds to expiration assigned when the token was last initialized or refreshed.

This value also provides the default value for subsequent refresh attempts.

The default value is 3600 (1 hour).

Returns:
The number of seconds.
 o getToken
 public byte[] getToken()
Returns the actual bytes for the token as it exists on the AS/400 system.

Returns:
The token bytes; null if not set.
 o getTokenType
 public int getTokenType()
Returns an integer indicating the type assigned when the token was last initialized or refreshed.

This value also provides the default value for subsequent refresh attempts.

The default is TYPE_SINGLE_USE.

Returns:
The type of token. Possible types are defined as fields on this class:
  • TYPE_SINGLE_USE
  • TYPE_MULTIPLE_USE_NON_RENEWABLE
  • TYPE_MULTIPLE_USE_RENEWABLE
 o hashCode
 public int hashCode()
Returns a hash code for this credential.

Returns:
a hash code for this credential.
Overrides:
hashCode in class Object
 o initialize
 public void initialize(AS400BasicAuthenticationPrincipal principal,
                        String password,
                        boolean isPrivate,
                        boolean isReusable,
                        boolean isRenewable,
                        int timeoutInterval) throws Exception
Initializes and validates a credential for the local AS/400 system.

Parameters:
principal - The principal identifying the authenticated user. If not an instance of AS400Principal, a corresponding UserProfilePrincipal is generated and assigned.
password - The password for the authenticated user.
isPrivate - Indicates whether the credential is considered private.
isReusable - true if the credential can be used to swap OS/400 thread identity multiple times; otherwise false.
isRenewable - true if the validity period of the credential can be programmatically updated or extended; otherwise false.
timeoutInterval - The number of seconds to expiration when the credential is initially created; ignored if the credential does not expire based on time.
Throws: Exception
If an exception occurs.
 o isRenewable
 public boolean isRenewable()
Indicates if the credential can be refreshed.

Returns:
true if the validity period of the credential can be programmatically updated or extended using refresh(); otherwise false.
Overrides:
isRenewable in class AS400Credential
See Also:
refresh
 o isReusable
 public boolean isReusable()
Indicates if the credential can be used multiple times prior to expiration.

Returns:
true if the credential can be used to swap OS/400 thread identity multiple times; otherwise false.
 o refresh
 public void refresh() throws AS400SecurityException
Updates or extends the validity period for the credential.

Does nothing if the credential cannot be programmatically updated or extended.

Otherwise, generates a new profile token based on the previously established token, type, and timeoutInterval.

Throws: AS400SecurityException
If an AS/400 security or authentication error occurs.
Overrides:
refresh in class AS400Credential
 o refresh
 public void refresh(int type,
                     int timeoutInterval) throws AS400SecurityException
Updates or extends the validity period for the credential.

Does nothing if the credential cannot be programmatically updated or extended.

Otherwise, generates a new profile token based on the previously established token with the given type and timeoutInterval.

If successful, the specified type and interval become the default values for future refresh attempts.

This method is provided to handle cases where it is desirable to allow for a more restrictive type of token or a different timeout interval when a new token is generated during the refresh.

Parameters:
type - The type of token. Possible types are defined as fields on this class:
  • TYPE_SINGLE_USE
  • TYPE_MULTIPLE_USE_NON_RENEWABLE
  • TYPE_MULTIPLE_USE_RENEWABLE
timeoutInterval - The number of seconds before expiration (1-3600).
Throws: AS400SecurityException
If an AS/400 security or authentication error occurs.
Throws: ExtendedIllegalArgumentException
If a parameter value is out of range.
 o setTimeoutInterval
 public void setTimeoutInterval(int seconds) throws PropertyVetoException
Sets the number of seconds to expiration when the token is generated or refreshed.

It is the application's responsibility to maintain consistency between explicitly set token values (those not generated from a user and password) and the tokenType and timeoutInterval.

This property cannot be changed once a request initiates a connection for the object to the AS/400 system (for example, refresh).

Parameters:
seconds - The number of seconds to expiration (1-3600).
Throws: PropertyVetoException
If the change is vetoed.
Throws: ExtendedIllegalArgumentException
If the provided value is out of range.
Throws: ExtendedIllegalStateException
If the property cannot be changed due to the current state.
 o setToken
 public void setToken(byte bytes[]) throws PropertyVetoException
Sets the actual bytes for the token as it exists on the AS/400 system.

This method allows a credential to be constructed based on an existing token (i.e. previously created using the QSYGENPT system API). It is the responsibility of the application to ensure the tokenType and timeoutInterval are consistent with the specified token value.

This property cannot be changed once a request initiates a connection for the object to the AS/400 system (for example, refresh).

Parameters:
bytes - The token bytes.
Throws: PropertyVetoException
If the change is vetoed.
Throws: ExtendedIllegalArgumentException
If the provided value is not the correct length.
Throws: ExtendedIllegalStateException
If the property cannot be changed due to the current state.
 o setToken
 public void setToken(AS400Principal principal,
                      String password) throws PropertyVetoException, AS400SecurityException
Sets the token bytes based on the provided principal and password.

The system property must be set prior to invoking this method.

If successful, this method results in a new token being created on the AS/400 system. The new token is generated using the previously established tokenType and timeoutInterval settings.

This property cannot be changed once a request initiates a connection for the object to the AS/400 system (for example, refresh).

Parameters:
principal - The principal identifying the user profile for which the token is to be generated.
password - The user profile password. The following special values are allowed:
  • *NOPWD - The password is not verified. This value is not allowed if the name of the currently running profile is specified for the name parameter. If specified, the user requesting the profile token must have *USE authority to the user profile.
  • *NOPWDCHK - The password is not verified. This value allows a profile token to be generated for a profile that is disabled or has an expired password. If disabled or expired, the user requesting the profile token must have *ALLOBJ and *SECADM special authority.
Throws: AS400SecurityException
If an AS/400 security or authentication error occurs.
Throws: PropertyVetoException
If the change is vetoed.
Throws: ExtendedIllegalArgumentException
If errors occur during parameter validation.
Throws: ExtendedIllegalStateException
If the token cannot be initialized due to the current state.
 o setToken
 public void setToken(String name,
                      String password) throws PropertyVetoException, AS400SecurityException
Sets the token bytes based on the provided user profile and password.

The system property must be set prior to invoking this method.

If successful, this method results in a new token being created on the AS/400 system. The new token is generated using the previously established tokenType and timeoutInterval settings.

This property cannot be changed once a request initiates a connection for the object to the AS/400 system (for example, refresh).

Parameters:
name - The name of the user profile for which the token is to be generated.
password - The user profile password. The following special values are allowed:
  • *NOPWD - The password is not verified. This value is not allowed if the name of the currently running profile is specified for the name parameter. If specified, the user requesting the profile token must have *USE authority to the user profile.
  • *NOPWDCHK - The password is not verified. This value allows a profile token to be generated for a profile that is disabled or has an expired password. If disabled or expired, the user requesting the profile token must have *ALLOBJ and *SECADM special authority.
Throws: AS400SecurityException
If an AS/400 security or authentication error occurs.
Throws: PropertyVetoException
If the change is vetoed.
Throws: ExtendedIllegalArgumentException
If errors occur during parameter validation.
Throws: ExtendedIllegalStateException
If the token cannot be initialized due to the current state.
 o setTokenType
 public void setTokenType(int type) throws PropertyVetoException
Sets the type of token.

It is the application's responsibility to maintain consistency between explicitly set token values (those not generated from a user and password) and the tokenType and timeoutInterval.

This property cannot be changed once a request initiates a connection for the object to the AS/400 system (for example, refresh).

Parameters:
type - The type of token. Possible types are defined as fields on this class:
  • TYPE_SINGLE_USE
  • TYPE_MULTIPLE_USE_NON_RENEWABLE
  • TYPE_MULTIPLE_USE_RENEWABLE
Throws: PropertyVetoException
If the change is vetoed.
Throws: ExtendedIllegalArgumentException
If the provided value is out of range.
Throws: ExtendedIllegalStateException
If the property cannot be changed due to the current state.
 o toString
 public String toString()
Returns a string representation of the object

Returns:
a string representation of the object.
Overrides:
toString in class Object

All Packages  Class Hierarchy  This Package  Previous  Next  Index