WSCredential (IBM WebSphere Application Server [security])

com.ibm.websphere.security.cred
Interface WSCredential

All Superinterfaces:
javax.security.auth.Destroyable, javax.security.auth.Refreshable, java.io.Serializable

public interface WSCredential
extends javax.security.auth.Refreshable, javax.security.auth.Destroyable, java.io.Serializable

Interface that defines a Credential used represent an authenticated principal to WebSphere.

Authentication mechanisms are expected to implement this interface.

Several of the method return types in this interface are array types. If implementors internally store instance data as arrays for these methods, they should return a deep copy of the array so that modifying the return result doesn't also modify the internally stored array.
Once a credential has been created, it is typically immutable except for expiration time.
If a credential is expired, any method access generates a CredentialExpiredException. An expired credential can be refreshed by call the refresh() method (Refreshable interface).

If a credential is destroyed, any method access generates a CredentialDestroyedException. A destroyed credential can not be used.

Since:

1.0

Version:

1.0

See Also:
Destroyable, Refreshable

Method Summary

java.lang.Object get(java.lang.String key)
           Allows user to get an Object based on a key.

java.lang.String getAccessId()
           Returns a string value that represents the access-Id of the principal.

byte[] getCredentialToken()
           Returns the credential token, for example: LTPA: Returns the credential token name of a LTPA credential Kerberos: Returns the credential token name of a Kerberos credential

long getExpiration()
           Returns a long value that indicates when a credential will expire.

java.util.ArrayList getGroupIds()
           Returns a java.util.ArrayList which indicates the groups the authenticated principal is a member of.

java.lang.String getHostName()
           Returns the IP address of the local machine.

java.lang.String getOID()
           Returns the OID that identifies the authentication mechanism, for example:

java.lang.String getPrimaryGroupId()
           Returns a string value that indicates the primary group the authenticated principal is a member of.

java.lang.String getRealmName()
           Return the realm name.

java.lang.String getRealmSecurityName()
           Returns the realm and the user principal name, the default implementation format is "realm/user principal name".

java.lang.String getRealmUniqueSecurityName()
           Returns the realm and the unique user name, the default implementation format is "realm/unique user name".

java.util.ArrayList getRoles()
           Returns a java.util.ArrayList containing the roles the authenticated principal is a member of.

java.lang.String getSecurityName()
           Returns the user principal name.

java.lang.String getUniqueSecurityName()
           Returns the unique user name as it applies to the configured user registry.

boolean isBasicAuth()
           Determines if the credential is a BasicAuth credential or not.

boolean isForwardable()
           Returns a boolean value that indicates if the credential is forwardable.

boolean isUnauthenticated()
           Return true if the credential is an Unauthenticated Credential.

java.lang.Object set(java.lang.String key, java.lang.Object value)
           Allows user to set an Object based on a key.

Methods inherited from interface javax.security.auth.Refreshable

isCurrent, refresh

Methods inherited from interface javax.security.auth.Destroyable

destroy, isDestroyed

Method Detail

getRealmName
public java.lang.String getRealmName()
                              throws CredentialDestroyedException,
                                     javax.security.auth.login.CredentialExpiredException
Return the realm name. The format of the realm name depends on the authentication targets, for example:

LTPA: Returns the domain name of LTPA

Kerberos: Returns the realm name of Kerberos

If there is no realm name, null is returned.

Returns:
The realm name, a string, or null.
Throws:
CredentialDestroyedException - Thrown if credential is destroyed.
javax.security.auth.login.CredentialExpiredException - Thrown if credential is expired.

getSecurityName
public java.lang.String getSecurityName()
                                 throws CredentialDestroyedException,
                                        javax.security.auth.login.CredentialExpiredException
Returns the user principal name. If there is no principal name, null is returned.

Returns:
The user principal name, a string, or null.
Throws:
CredentialDestroyedException - Thrown if credential is destroyed.
javax.security.auth.login.CredentialExpiredException - Thrown if credential is expired.

getRealmSecurityName
public java.lang.String getRealmSecurityName()
                                      throws CredentialDestroyedException,
                                             javax.security.auth.login.CredentialExpiredException
Returns the realm and the user principal name, the default implementation format is "realm/user principal name". If there is no valid value, null is returned.

Returns:
The realm and user principal name, a string, or null.
Throws:
CredentialDestroyedException - Thrown if credential is destroyed.
javax.security.auth.login.CredentialExpiredException - Thrown if credential is expired.

getUniqueSecurityName
public java.lang.String getUniqueSecurityName()
                                       throws CredentialDestroyedException,
                                              javax.security.auth.login.CredentialExpiredException
Returns the unique user name as it applies to the configured user registry. For LDAP, this would might be the DistinguishedName. For LocalOS, this might return the unique name from the local registry. For Custom, this will be whatever the custom registry getUniqueUserId() API returns.

Returns:
The user unique name, a string, or null.
Throws:
CredentialDestroyedException - Thrown if credential is destroyed.
javax.security.auth.login.CredentialExpiredException - Thrown if credential is expired.

getRealmUniqueSecurityName
public java.lang.String getRealmUniqueSecurityName()
                                            throws CredentialDestroyedException,
                                                   javax.security.auth.login.CredentialExpiredException
Returns the realm and the unique user name, the default implementation format is "realm/unique user name". If there is no valid value, null is returned.

Returns:
The realm and unique user name, a string, or null.
Throws:
CredentialDestroyedException - Thrown if credential is destroyed.
javax.security.auth.login.CredentialExpiredException - Thrown if credential is expired.

getCredentialToken
public byte[] getCredentialToken()
                          throws CredentialDestroyedException,
                                 javax.security.auth.login.CredentialExpiredException
Returns the credential token, for example:

LTPA: Returns the credential token name of a LTPA credential

Kerberos: Returns the credential token name of a Kerberos credential

The Credential Token should be treated as an opaque object. It should be a deep copy of any byte array that an actual WSCredential implementation may use to store the token internally.

If there is no credential token, null is returned.

Returns:
The Credential Token of a credential, a byte array or null.
Throws:
CredentialDestroyedException - Thrown if credential is destroyed.
javax.security.auth.login.CredentialExpiredException - Thrown if credential is expired.

getOID
public java.lang.String getOID()
                        throws CredentialDestroyedException,
                               javax.security.auth.login.CredentialExpiredException
Returns the OID that identifies the authentication mechanism, for example:

The OID is an object identifier in string format, e.g. 111.222.33 for instance.

If there is no OID, null is returned.

Returns:
The OID of a credential or null.
Throws:
CredentialDestroyedException - Thrown if credential is destroyed.
javax.security.auth.login.CredentialExpiredException - Thrown if credential is expired.

isForwardable
public boolean isForwardable()
                      throws CredentialDestroyedException,
                             javax.security.auth.login.CredentialExpiredException
Returns a boolean value that indicates if the credential is forwardable. A forwardable credential can be propogated to other servers as part of a delegated remote method invocation. The authentication mechanism determines forwardability.

Returns:
boolean.
Throws:
CredentialDestroyedException - Thrown if credential is destroyed.
javax.security.auth.login.CredentialExpiredException - Thrown if credential is expired.

getExpiration
public long getExpiration()
                   throws CredentialDestroyedException,
                          javax.security.auth.login.CredentialExpiredException
Returns a long value that indicates when a credential will expire. The authentication mechanism determines if and when a credential expires typically when the credential was issued. The unit of measure is also determined by the actual authentication mechanism.
If there is no expiration time, 0 is returned.

Returns:
long.
Throws:
CredentialDestroyedException - Thrown if credential is destroyed.
javax.security.auth.login.CredentialExpiredException - Thrown if credential is expired.

getPrimaryGroupId
public java.lang.String getPrimaryGroupId()
                                   throws CredentialDestroyedException,
                                          javax.security.auth.login.CredentialExpiredException
Returns a string value that indicates the primary group the authenticated principal is a member of.
If there is no primary group ID, null is returned.

Returns:
String or null.
Throws:
CredentialDestroyedException - Thrown if credential is destroyed.
javax.security.auth.login.CredentialExpiredException - Thrown if credential is expired.

getRoles
public java.util.ArrayList getRoles()
                             throws CredentialDestroyedException,
                                    javax.security.auth.login.CredentialExpiredException
Returns a java.util.ArrayList containing the roles the authenticated principal is a member of. If the underlying implementation stores the roles internally as an array, then this method should return a deep copy of the array.
If there are no roles ID, an empty List is returned.

Returns:
java.util.ArrayList
Throws:
CredentialDestroyedException - Thrown if credential is destroyed.
javax.security.auth.login.CredentialExpiredException - Thrown if credential is expired.

getAccessId
public java.lang.String getAccessId()
                             throws CredentialDestroyedException,
                                    javax.security.auth.login.CredentialExpiredException
Returns a string value that represents the access-Id of the principal. An access-Id is used to uniquely identity the principal in a user registry and is typically used during authorization checks.
If there is no access-Id null is returned.

Returns:
String or null.
Throws:
CredentialDestroyedException - Thrown if credential is destroyed.
javax.security.auth.login.CredentialExpiredException - Thrown if credential is expired.

getGroupIds
public java.util.ArrayList getGroupIds()
                                throws CredentialDestroyedException,
                                       javax.security.auth.login.CredentialExpiredException
Returns a java.util.ArrayList which indicates the groups the authenticated principal is a member of.
If there are no groups, an empty List is returned.

Returns:
java.util.ArrayList
Throws:
CredentialDestroyedException - Thrown if credential is destroyed.
javax.security.auth.login.CredentialExpiredException - Thrown if credential is expired.

getHostName
public java.lang.String getHostName()
                             throws CredentialDestroyedException,
                                    javax.security.auth.login.CredentialExpiredException
Returns the IP address of the local machine. If there is no IP address, null is returned.

Returns:
The IP of the local machine.
Throws:
CredentialDestroyedException - Thrown if credential is destroyed.
javax.security.auth.login.CredentialExpiredException - Thrown if credential is expired.

get
public java.lang.Object get(java.lang.String key)
                     throws CredentialDestroyedException,
                            javax.security.auth.login.CredentialExpiredException
Allows user to get an Object based on a key. It is similar to a hash table.

Parameters:
key - A String value, "wssecurity.*" is keys reserved for WebSphere internal usage
Returns:
return null if no object associated with the key
Throws:
CredentialDestroyedException - Thrown if credential is destroyed.
javax.security.auth.login.CredentialExpiredException - Thrown if credential is expired.

set
public java.lang.Object set(java.lang.String key,
                            java.lang.Object value)
                     throws CredentialDestroyedException,
                            javax.security.auth.login.CredentialExpiredException
Allows user to set an Object based on a key. It is similar to a hash table. Please do not use key values begin with "wssecurity.*", the "wssecurity" is the namespace reserved by WebSphere internal usage.

Parameters:
key - A String value, "wssecurity.*" is keys reserved for WebSphere internal usage
value - Object to be set to associate with the key
Returns:
if there is already an object associated with the key prior to the set, then the object is returned, else null is returned
Throws:
CredentialDestroyedException - Thrown if credential is destroyed.
javax.security.auth.login.CredentialExpiredException - Thrown if credential is expired.

isUnauthenticated
public boolean isUnauthenticated()
Return true if the credential is an Unauthenticated Credential.

Returns:
Return true if the credential is an Unauthenticated Credential.

isBasicAuth
public boolean isBasicAuth()
Determines if the credential is a BasicAuth credential or not. If a BasicAuth credential, it will contain data to authenticate a user, but cannot represent an authenticated user. If not a BasicAuth credential, it can be used for authorization decisions.

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.

Method Summary
java.lang.Object	get(java.lang.String key) Allows user to get an Object based on a key.
java.lang.String	getAccessId() Returns a string value that represents the access-Id of the principal.
byte[]	getCredentialToken() Returns the credential token, for example: LTPA: Returns the credential token name of a LTPA credential Kerberos: Returns the credential token name of a Kerberos credential
long	getExpiration() Returns a long value that indicates when a credential will expire.
java.util.ArrayList	getGroupIds() Returns a java.util.ArrayList which indicates the groups the authenticated principal is a member of.
java.lang.String	getHostName() Returns the IP address of the local machine.
java.lang.String	getOID() Returns the OID that identifies the authentication mechanism, for example:
java.lang.String	getPrimaryGroupId() Returns a string value that indicates the primary group the authenticated principal is a member of.
java.lang.String	getRealmName() Return the realm name.
java.lang.String	getRealmSecurityName() Returns the realm and the user principal name, the default implementation format is "realm/user principal name".
java.lang.String	getRealmUniqueSecurityName() Returns the realm and the unique user name, the default implementation format is "realm/unique user name".
java.util.ArrayList	getRoles() Returns a java.util.ArrayList containing the roles the authenticated principal is a member of.
java.lang.String	getSecurityName() Returns the user principal name.
java.lang.String	getUniqueSecurityName() Returns the unique user name as it applies to the configured user registry.
boolean	isBasicAuth() Determines if the credential is a BasicAuth credential or not.
boolean	isForwardable() Returns a boolean value that indicates if the credential is forwardable.
boolean	isUnauthenticated() Return true if the credential is an Unauthenticated Credential.
java.lang.Object	set(java.lang.String key, java.lang.Object value) Allows user to set an Object based on a key.

com.ibm.websphere.security.cred Interface WSCredential

getRealmName

getSecurityName

getRealmSecurityName

getUniqueSecurityName

getRealmUniqueSecurityName

getCredentialToken

getOID

isForwardable

getExpiration

getPrimaryGroupId

getRoles

getAccessId

getGroupIds

getHostName

get

set

isUnauthenticated

isBasicAuth

com.ibm.websphere.security.cred
Interface WSCredential