org.apache.catalina.realm

Class GenericPrincipal

java.lang.Object

org.apache.catalina.realm.GenericPrincipal

All Implemented Interfaces:

java.io.Serializable, java.security.Principal, TomcatPrincipal

Direct Known Subclasses:

UserDatabaseRealm.UserDatabasePrincipal

public class GenericPrincipal
extends java.lang.Object
implements TomcatPrincipal, java.io.Serializable

Generic implementation of java.security.Principal that is available for use by Realm implementations.

Author:

Craig R. McClanahan

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
protected java.util.Map<java.lang.String,java.lang.Object>	attributes The additional attributes associated with this Principal.
protected org.ietf.jgss.GSSCredential	gssCredential The user's delegated credentials.
protected javax.security.auth.login.LoginContext	loginContext The JAAS LoginContext, if any, used to authenticate this Principal.
protected java.lang.String	name The username of the user represented by this Principal.
protected java.lang.String	password The authentication credentials for the user represented by this Principal.
protected java.lang.String[]	roles The set of roles associated with this user.
protected java.security.Principal	userPrincipal The authenticated Principal to be exposed to applications.

Constructor Summary

Constructors

Constructor and Description
GenericPrincipal(java.lang.String name, java.lang.String password, java.util.List<java.lang.String> roles) Construct a new Principal, associated with the specified Realm, for the specified username and password, with the specified role names (as Strings).
GenericPrincipal(java.lang.String name, java.lang.String password, java.util.List<java.lang.String> roles, java.security.Principal userPrincipal) Construct a new Principal, associated with the specified Realm, for the specified username and password, with the specified role names (as Strings).
GenericPrincipal(java.lang.String name, java.lang.String password, java.util.List<java.lang.String> roles, java.security.Principal userPrincipal, javax.security.auth.login.LoginContext loginContext) Construct a new Principal, associated with the specified Realm, for the specified username and password, with the specified role names (as Strings).
GenericPrincipal(java.lang.String name, java.lang.String password, java.util.List<java.lang.String> roles, java.security.Principal userPrincipal, javax.security.auth.login.LoginContext loginContext, org.ietf.jgss.GSSCredential gssCredential, java.util.Map<java.lang.String,java.lang.Object> attributes) Construct a new Principal, associated with the specified Realm, for the specified username and password, with the specified role names (as Strings).

Method Summary

Modifier and Type	Method and Description
java.lang.Object	getAttribute(java.lang.String name) Returns the value of the named attribute as an Object, or null if no attribute of the given name exists, or if null has been specified as the attribute's name.
java.util.Enumeration<java.lang.String>	getAttributeNames() Returns an Enumeration containing the names of the attributes available to this Principal.
org.ietf.jgss.GSSCredential	getGssCredential()
java.lang.String	getName()
java.lang.String	getPassword()
java.lang.String[]	getRoles()
java.security.Principal	getUserPrincipal()
boolean	hasRole(java.lang.String role) Does the user represented by this Principal possess the specified role?
void	logout() Calls logout, if necessary, on any associated JAASLoginContext and/or GSSContext.
protected void	setGssCredential(org.ietf.jgss.GSSCredential gssCredential)
java.lang.String	toString() Return a String representation of this object, which exposes only information that should be public.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.security.Principal

equals, hashCode, implies

Field Detail

name

protected final java.lang.String name

The username of the user represented by this Principal.

password

protected final java.lang.String password

The authentication credentials for the user represented by this Principal.

roles

protected final java.lang.String[] roles

The set of roles associated with this user.

userPrincipal

protected final java.security.Principal userPrincipal

The authenticated Principal to be exposed to applications.

loginContext

protected final transient javax.security.auth.login.LoginContext loginContext

The JAAS LoginContext, if any, used to authenticate this Principal. Kept so we can call logout().

gssCredential

protected transient org.ietf.jgss.GSSCredential gssCredential

The user's delegated credentials.

attributes

protected final java.util.Map<java.lang.String,java.lang.Object> attributes

The additional attributes associated with this Principal.

Constructor Detail

GenericPrincipal

public GenericPrincipal(java.lang.String name,
                        java.lang.String password,
                        java.util.List<java.lang.String> roles)

Construct a new Principal, associated with the specified Realm, for the specified username and password, with the specified role names (as Strings).

Parameters:

name - The username of the user represented by this Principal

password - Credentials used to authenticate this user

roles - List of roles (must be Strings) possessed by this user

GenericPrincipal

public GenericPrincipal(java.lang.String name,
                        java.lang.String password,
                        java.util.List<java.lang.String> roles,
                        java.security.Principal userPrincipal)

Construct a new Principal, associated with the specified Realm, for the specified username and password, with the specified role names (as Strings).

Parameters:

name - The username of the user represented by this Principal

password - Credentials used to authenticate this user

roles - List of roles (must be Strings) possessed by this user

userPrincipal - - the principal to be returned from the request getUserPrincipal call if not null; if null, this will be returned

GenericPrincipal

public GenericPrincipal(java.lang.String name,
                        java.lang.String password,
                        java.util.List<java.lang.String> roles,
                        java.security.Principal userPrincipal,
                        javax.security.auth.login.LoginContext loginContext)

Construct a new Principal, associated with the specified Realm, for the specified username and password, with the specified role names (as Strings).

Parameters:

name - The username of the user represented by this Principal

password - Credentials used to authenticate this user

roles - List of roles (must be Strings) possessed by this user

userPrincipal - - the principal to be returned from the request getUserPrincipal call if not null; if null, this will be returned

loginContext - - If provided, this will be used to log out the user at the appropriate time

GenericPrincipal

public GenericPrincipal(java.lang.String name,
                        java.lang.String password,
                        java.util.List<java.lang.String> roles,
                        java.security.Principal userPrincipal,
                        javax.security.auth.login.LoginContext loginContext,
                        org.ietf.jgss.GSSCredential gssCredential,
                        java.util.Map<java.lang.String,java.lang.Object> attributes)

Construct a new Principal, associated with the specified Realm, for the specified username and password, with the specified role names (as Strings).

Parameters:

name - The username of the user represented by this Principal

password - Credentials used to authenticate this user

roles - List of roles (must be Strings) possessed by this user

userPrincipal - - the principal to be returned from the request getUserPrincipal call if not null; if null, this will be returned

loginContext - - If provided, this will be used to log out the user at the appropriate time

gssCredential - - If provided, the user's delegated credentials

attributes - - If provided, additional attributes associated with this Principal

Method Detail

getName

public java.lang.String getName()

Specified by:

getName in interface java.security.Principal

getPassword

public java.lang.String getPassword()

getRoles

public java.lang.String[] getRoles()

getUserPrincipal

public java.security.Principal getUserPrincipal()

Specified by:

getUserPrincipal in interface TomcatPrincipal

Returns:

The authenticated Principal to be exposed to applications.

getGssCredential

public org.ietf.jgss.GSSCredential getGssCredential()

Specified by:

getGssCredential in interface TomcatPrincipal

Returns:

The user's delegated credentials.

setGssCredential

protected void setGssCredential(org.ietf.jgss.GSSCredential gssCredential)

hasRole

public boolean hasRole(java.lang.String role)

Does the user represented by this Principal possess the specified role?

Parameters:

role - Role to be tested

Returns:

true if this Principal has been assigned the given role, otherwise false

toString

public java.lang.String toString()

Return a String representation of this object, which exposes only information that should be public.

Specified by:

toString in interface java.security.Principal

Overrides:

toString in class java.lang.Object

logout

public void logout()
            throws java.lang.Exception

Description copied from interface: TomcatPrincipal

Calls logout, if necessary, on any associated JAASLoginContext and/or GSSContext. May in the future be extended to cover other logout requirements.

Specified by:

logout in interface TomcatPrincipal

Throws:

java.lang.Exception - If something goes wrong with the logout. Uses Exception to allow for future expansion of this method to cover other logout mechanisms that might throw a different exception to LoginContext

getAttribute

public java.lang.Object getAttribute(java.lang.String name)

Description copied from interface: TomcatPrincipal

Returns the value of the named attribute as an Object, or null if no attribute of the given name exists, or if null has been specified as the attribute's name.

Only the servlet container may set attributes to make available custom information about a Principal or the user it represents.

The purpose of the method is to implement read only access to attributes which may be stored in the Realm implementation's backend due to its inherent design.

As using this method from application code will make it non portable to other EE compliant containers, it is advised this should never be used as an object storage facility tied to the Principal, but rather as simple extra additional metadata. It is recommended that a container level object is used to further process the attributes that may be associated with the Principal.

Realm implementations that are provided by Tomcat will not provide complex type mapping, but will in most cases always return a result as a String object which may need custom decoding.

Realm implementations that are provided by Tomcat will not provide an implementation for this facility unless it is inherent to the storage backend of the Realm itself and metadata is available without additional user intervention or configuration.

Specified by:

getAttribute in interface TomcatPrincipal

Parameters:

name - a String specifying the name of the attribute

Returns:

an Object containing the value of the attribute, or null if the attribute does not exist, or if null has been specified as the attribute's name

getAttributeNames

public java.util.Enumeration<java.lang.String> getAttributeNames()

Description copied from interface: TomcatPrincipal

Returns an Enumeration containing the names of the attributes available to this Principal. This method returns an empty Enumeration if the Principal has no attributes available to it.

Specified by:

getAttributeNames in interface TomcatPrincipal

Returns:

an Enumeration of strings containing the names of the Principal's attributes