## org.mortbay.http
Interface UserRealm

All Known Implementing Classes:
  HashUserRealm, JAASUserRealm

public interface UserRealm

User Realm. This interface should be specialized to provide specific user lookup and authentication using arbitrary methods. For SSO implementation sof UserRealm should also implement SSORealm.

Version:
  $Id: UserRealm.java,v 1.9.2.1 2003/10/12 03:08:59 gregwilkins Exp $
Author:
  Greg Wilkins (gregw)
See Also:
  `SSORealm`

Method Summary
`UserPrincipal` `authenticate(java.lang.String username, java.lang.Object credentials, HttpRequest request)` Authenticate a users credentials.
`void` `disassociate(UserPrincipal user)` Dissassociate the calling context with a Principal.
`java.lang.String` `getName()`
`void` `logout(UserPrincipal user)` Logout a role.
`UserPrincipal` `popRole(UserPrincipal user)` Pop role from a Principal.
`UserPrincipal` `pushRole(UserPrincipal user, java.lang.String role)` Push role onto a Principal.

Method Detail

### getName

    public java.lang.String getName()

### authenticate

    public UserPrincipal authenticate(java.lang.String username,
                                      java.lang.Object credentials,
                                      HttpRequest request)

  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.

  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(UserPrincipal user)

  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.

  Parameters:
    `user` - A UserPrincipal allocated from this realm.

### pushRole

    public UserPrincipal pushRole(UserPrincipal user,
                                  java.lang.String role)

  Push role onto a Principal. This method is used to add a role to an existing principal.

  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 UserPrincipal popRole(UserPrincipal user)

  Pop role from a Principal.

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

### logout

    public void logout(UserPrincipal user)

  Logout a role. This method is called for authentication mechanisms that have a concept of logout (which is only FORM). Most Authenticaton mechanisms need not do anything with this method.

Copyright © 2000 Mortbay Consulting Pty. Ltd. All Rights Reserved.