## org.mortbay.jetty.security
Class HashUserRealm

    java.lang.Object
      org.mortbay.component.AbstractLifeCycle
          org.mortbay.jetty.security.HashUserRealm

All Implemented Interfaces:
  LifeCycle, SSORealm, UserRealm

Direct Known Subclasses:
  JDBCUserRealm

    public class HashUserRealm

extends AbstractLifeCycle
implements UserRealm, SSORealm

HashMapped User Realm. An implementation of UserRealm that stores users and roles in-memory in HashMaps.

Typically these maps are populated by calling the load() method or passing a properties resource to the constructor. The format of the properties file is:

      username: password [,rolename ...]

Passwords may be clear text, obfuscated or checksummed. The class com.mortbay.Util.Password should be used to generate obfuscated passwords or password checksums. If DIGEST Authentication is used, the password must be in a recoverable format, either plain text or OBF:. The HashUserRealm also implements SSORealm but provides no implementation of SSORealm. Instead setSSORealm may be used to provide a delegate SSORealm implementation.

Author:
  Greg Wilkins (gregw)
See Also:
  `Password`

Field Summary
`static String` `__SSO` HttpContext Attribute to set to activate SSO.
`protected HashMap` `_roles`
`protected HashMap` `_users`

Constructor Summary
`HashUserRealm()` Constructor.
`HashUserRealm(String name)` Constructor.
`HashUserRealm(String name, String config)` Constructor.

Method Summary
`void` `addUserToRole(String userName, String roleName)` Add a user to a role.
`Principal` `authenticate(String username, Object credentials, Request request)` Authenticate a users credentials.
`void` `clearSingleSignOn(String username)` Clear SSO for user.
`void` `disassociate(Principal user)` Dissassociate the calling context with a Principal.
`protected void` `doStart()`
`protected void` `doStop()`
`void` `dump(PrintStream out)`
`String` `getConfig()`
`String` `getName()`
`Principal` `getPrincipal(String username)` Get the principal for a username.
`int` `getRefreshInterval()`
`Credential` `getSingleSignOn(Request request, Response response)` Get SSO credentials.
`SSORealm` `getSSORealm()`
`boolean` `isUserInRole(Principal user, String roleName)` Check if a user is in a role.
`void` `loadConfig()`
`void` `logout(Principal user)` logout a user Principal.
`Principal` `popRole(Principal user)` Pop role from a Principal.
`Principal` `pushRole(Principal user, String role)` Push role onto a Principal.
`Object` `put(Object name, Object credentials)` Put user into realm.
`boolean` `reauthenticate(Principal user)` Re Authenticate a Principal.
`void` `setConfig(String config)` Load realm users from properties file.
`void` `setName(String name)`
`void` `setRefreshInterval(int msec)`
`void` `setSingleSignOn(Request request, Response response, Principal principal, Credential credential)` Set SSO principal and credential.
`void` `setSSORealm(SSORealm ssoRealm)` Set the SSORealm.
`String` `toString()`

Methods inherited from class org.mortbay.component.AbstractLifeCycle
`isFailed, isRunning, isStarted, isStarting, isStopped, isStopping, start, stop`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Field Detail

### __SSO

    public static final String __SSO

  HttpContext Attribute to set to activate SSO.

  See Also:
    Constant Field Values

### _users

    protected HashMap _users

### _roles

    protected HashMap _roles

Constructor Detail

### HashUserRealm

    public HashUserRealm()

  Constructor.

### HashUserRealm

    public HashUserRealm(String name)

  Constructor.

  Parameters:
    `name` - Realm Name

### HashUserRealm

    public HashUserRealm(String name,
                         String config)
                  throws IOException

  Constructor.

  Parameters:
    `name` - Realm name
    `config` - Filename or url of user properties file.
  Throws:
    `IOException`

Method Detail

### getConfig

    public String getConfig()

### setConfig

    public void setConfig(String config)
                   throws IOException

  Load realm users from properties file. The property file maps usernames to password specs followed by an optional comma separated list of role names.

  Parameters:
    `config` - Filename or url of user properties file.
  Throws:
    `IOException`

### setRefreshInterval

    public void setRefreshInterval(int msec)

### getRefreshInterval

    public int getRefreshInterval()

### loadConfig

    public void loadConfig()
                    throws IOException

  Throws:
    `IOException`

### setName

    public void setName(String name)

  Parameters:
    `name` - The realm name

### getName

    public String getName()

  Specified by:
    `getName` in interface `UserRealm`
  Returns:
    The realm name.

### getPrincipal

    public Principal getPrincipal(String username)

  Description copied from interface: `UserRealm`
  Get the principal for a username. This method is not guaranteed to return a Principal for non-authenticated users.

  Specified by:
    `getPrincipal` in interface `UserRealm`

### authenticate

    public Principal authenticate(String username,
                                  Object credentials,
                                  Request request)

  Description copied from interface: `UserRealm`
  Authenticate a users credentials. Implementations of this method may adorn the calling context to assoicate it with the authenticated principal (eg ThreadLocals). If such context associations are made, they should be considered valid until a UserRealm.deAuthenticate(UserPrincipal) call is made for this UserPrincipal.

  Specified by:
    `authenticate` in interface `UserRealm`
  Parameters:
    `username` - The username.
    `credentials` - The user credentials, normally a String password.
    `request` - The request to be authenticated. Additional parameters may be extracted or set on this request as needed for the authentication mechanism (none required for BASIC and FORM authentication).
  Returns:
    The authenticated UserPrincipal.

### disassociate

    public void disassociate(Principal user)

  Description copied from interface: `UserRealm`
  Dissassociate the calling context with a Principal. This method is called when the calling context is not longer associated with the Principal. It should be used by an implementation to remove context associations such as ThreadLocals. The UserPrincipal object remains authenticated, as it may be associated with other contexts.

  Specified by:
    `disassociate` in interface `UserRealm`
  Parameters:
    `user` - A UserPrincipal allocated from this realm.

### pushRole

    public Principal pushRole(Principal user,
                              String role)

  Description copied from interface: `UserRealm`
  Push role onto a Principal. This method is used to add a role to an existing principal.

  Specified by:
    `pushRole` in interface `UserRealm`
  Parameters:
    `user` - An existing UserPrincipal or null for an anonymous user.
    `role` - The role to add.
  Returns:
    A new UserPrincipal object that wraps the passed user, but with the added role.

### popRole

    public Principal popRole(Principal user)

  Description copied from interface: `UserRealm`
  Pop role from a Principal.

  Specified by:
    `popRole` in interface `UserRealm`
  Parameters:
    `user` - A UserPrincipal previously returned from pushRole
  Returns:
    The principal without the role. Most often this will be the original UserPrincipal passed.

### put

    public Object put(Object name,
                      Object credentials)

  Put user into realm.

  Parameters:
    `name` - User name
    `credentials` - String password, Password or UserPrinciple instance.
  Returns:
    Old UserPrinciple value or null

### addUserToRole

    public void addUserToRole(String userName,
                              String roleName)

  Add a user to a role.

  Parameters:
    `userName` -
    `roleName` -

### reauthenticate

    public boolean reauthenticate(Principal user)

  Description copied from interface: `UserRealm`
  Re Authenticate a Principal. Authenicate a principal that has previously been return from the authenticate method. Implementations of this method may adorn the calling context to assoicate it with the authenticated principal (eg ThreadLocals). If such context associations are made, they should be considered valid until a UserRealm.deAuthenticate(UserPrincipal) call is made for this UserPrincipal.

  Specified by:
    `reauthenticate` in interface `UserRealm`
  Returns:
    True if this user is still authenticated.

### isUserInRole

    public boolean isUserInRole(Principal user,
                                String roleName)

  Check if a user is in a role.

  Specified by:
    `isUserInRole` in interface `UserRealm`
  Parameters:
    `user` - The user, which must be from this realm
    `roleName` -
  Returns:
    True if the user can act in the role.

### logout

    public void logout(Principal user)

  Description copied from interface: `UserRealm`
  logout a user Principal. Called by authentication mechanisms (eg FORM) that can detect logout.

  Specified by:
    `logout` in interface `UserRealm`
  Parameters:
    `user` - A Principal previously returned from this realm

### toString

    public String toString()

  Overrides:
    `toString` in class `Object`

### dump

    public void dump(PrintStream out)

### getSSORealm

    public SSORealm getSSORealm()

  Returns:
    The SSORealm to delegate single sign on requests to.

### setSSORealm

    public void setSSORealm(SSORealm ssoRealm)

  Set the SSORealm. A SSORealm implementation may be set to enable support for SSO.

  Parameters:
    `ssoRealm` - The SSORealm to delegate single sign on requests to.

### getSingleSignOn

    public Credential getSingleSignOn(Request request,
                                      Response response)

  Description copied from interface: `SSORealm`
  Get SSO credentials. This call is used by an authenticator to check if a SSO exists for a request. If SSO authentiation is successful, the requests UserPrincipal and AuthUser fields are set. If available, the credential used to authenticate the user is returned. If recoverable credentials are not required then null may be return.

  Specified by:
    `getSingleSignOn` in interface `SSORealm`
  Parameters:
    `request` - The request to SSO.
    `response` - The response to SSO.
  Returns:
    A credential if available for SSO authenticated requests.

### setSingleSignOn

    public void setSingleSignOn(Request request,
                                Response response,
                                Principal principal,
                                Credential credential)

  Description copied from interface: `SSORealm`
  Set SSO principal and credential. This call is used by an authenticator to inform the SSO mechanism that a user has signed on. The SSO mechanism should record the principal and credential and update the response with any cookies etc. required.

  Specified by:
    `setSingleSignOn` in interface `SSORealm`
  Parameters:
    `request` - The authenticated request.
    `response` - The authenticated response/
    `principal` - The principal that has been authenticated.
    `credential` - The credentials used to authenticate.

### clearSingleSignOn

    public void clearSingleSignOn(String username)

  Description copied from interface: `SSORealm`
  Clear SSO for user.

  Specified by:
    `clearSingleSignOn` in interface `SSORealm`
  Parameters:
    `username` - The user to clear.

### doStart

    protected void doStart()
                    throws Exception

  Overrides:
    `doStart` in class `AbstractLifeCycle`
  Throws:
    `Exception`
  See Also:
    `AbstractLifeCycle.doStart()`

### doStop

    protected void doStop()
                   throws Exception

  Overrides:
    `doStop` in class `AbstractLifeCycle`
  Throws:
    `Exception`
  See Also:
    `AbstractLifeCycle.doStop()`

Copyright © 2007 Mort Bay Consulting. All Rights Reserved.