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:
- Creating a token updates the last-used date for the associated
user and group profiles.
- Creating a token resets the 'signon attempts not valid' count to
zero for the user profile.
- If security-related events are being audited, creating a token
adds an entry to the AUDJRN audit journal.
- The maximum number of profile tokens that can be generated is
approximately 2,000,000; after that, the space to store them is full.
Message CPF4AAA is sent to the caller, and no more profile
tokens can be generated until one is removed.
- You cannot obtain a profile token for the following
system-supplied user profiles:
- QAUTPROF
- QFNC
- QNETSPLF
- QSPLJOB
- QDBSHR
- QGATE
- QNFSANON
- QSYS
- QDFTOWN
- QLPAUTO
- QRJE
- QTCP
- QDIRSRV
- QLPINSTALL
- QSNADS
- QTFTP
- QDOC
- QMSF
- QSPL
- QTSTRQS
- QDSNX
Guidelines and restrictions for generating profile tokens based
on a specified user profile name and password:
- On level 10 systems, only the user ID is validated
because no passwords are required.
- If a provided password is not correct, the incorrect password
count for the user profile is increased. (The QMAXSIGN system
value contains the maximum number of incorrect attempts to sign on.)
- If the QMAXSGNACN system value is set to disable
user profiles, repeated attempts to validate an incorrect
password disables the user ID. This keeps applications
from methodically determining user passwords.
- Considerations when specifying a password of *NOPWD or *NOPWDCHK:
- To obtain a profile token for a profile that does not have a
password, specify *NOPWD or *NOPWDCHK for the password
parameter.
- The user requesting the profile token must have *USE
authority to the user profile.
- *NOPWD is not allowed if the user profile name is the name
of the currently running user profile.
- If the password is *NOPWDCHK and the user requesting the
profile token has *ALLOBJ and *SECADM special authorities, a
profile token will be generated even when the status of the
profile is disabled or its password is expired.
- No profile token is created in the following situations:
- The user profile is disabled and *NOPWDCHK is not
specified for the password parameter, or *NOPWDCHK was
specified but the user requesting the profile token does
not have *ALLOBJ or *SECADM special authority.
- The password is expired and *NOPWDCHK is not
specified for the password parameter, or *NOPWDCHK was
specified but the user requesting the profile token does
not have *ALLOBJ or *SECADM special authority.
- The password is *NONE, and *NOPWD or *NOPWDCHK is not
specified for the password parameter.
- See Also:
- AS400Credential
-
TOKEN_LENGTH
- Indicates the length of a profile token (in bytes)
-
TYPE_MULTIPLE_USE_NON_RENEWABLE
- ID indicating a multiple use token that cannot be regenerated.
-
TYPE_MULTIPLE_USE_RENEWABLE
- ID indicating a multiple use token that can be regenerated.
-
TYPE_SINGLE_USE
- ID indicating a single use token.
-
ProfileTokenCredential()
- Constructs a ProfileTokenCredential object.
-
ProfileTokenCredential(AS400, byte[], int, int)
- Constructs and initializes a ProfileTokenCredential object.
-
equals(Object)
- Compares the specified Object with the credential
for equality.
-
getTimeoutInterval()
- Returns the number of seconds to expiration assigned
when the token was last initialized or refreshed.
-
getToken()
- Returns the actual bytes for the token as it exists
on the AS/400 system.
-
getTokenType()
- Returns an integer indicating the type assigned when
the token was last initialized or refreshed.
-
hashCode()
- Returns a hash code for this credential.
-
initialize(AS400BasicAuthenticationPrincipal, String, boolean, boolean, boolean, int)
- Initializes and validates a credential for the local AS/400 system.
-
isRenewable()
- Indicates if the credential can be refreshed.
-
isReusable()
- Indicates if the credential can be used multiple
times prior to expiration.
-
refresh()
- Updates or extends the validity period for the credential.
-
refresh(int, int)
- Updates or extends the validity period for the credential.
-
setTimeoutInterval(int)
- Sets the number of seconds to expiration when the
token is generated or refreshed.
-
setToken(AS400Principal, String)
- Sets the token bytes based on the provided principal and password.
-
setToken(byte[])
- Sets the actual bytes for the token as it exists
on the AS/400 system.
-
setToken(String, String)
- Sets the token bytes based on the provided user profile and password.
-
setTokenType(int)
- Sets the type of token.
-
toString()
- Returns a string representation of the object
TYPE_SINGLE_USE
public static int TYPE_SINGLE_USE
- ID indicating a single use token.
TYPE_MULTIPLE_USE_NON_RENEWABLE
public static int TYPE_MULTIPLE_USE_NON_RENEWABLE
- ID indicating a multiple use token that cannot be regenerated.
TYPE_MULTIPLE_USE_RENEWABLE
public static int TYPE_MULTIPLE_USE_RENEWABLE
- ID indicating a multiple use token that can be regenerated.
TOKEN_LENGTH
public static int TOKEN_LENGTH
- Indicates the length of a profile token (in bytes)
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.
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).
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
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.
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.
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
hashCode
public int hashCode()
- Returns a hash code for this credential.
- Returns:
- a hash code for this credential.
- Overrides:
- hashCode in class Object
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.
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
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.
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
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.
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.
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.
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.
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.
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.
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