001: // ========================================================================
002: // Copyright 1996-2005 Mort Bay Consulting Pty. Ltd.
003: // ------------------------------------------------------------------------
004: // Licensed under the Apache License, Version 2.0 (the "License");
005: // you may not use this file except in compliance with the License.
006: // You may obtain a copy of the License at
007: // http://www.apache.org/licenses/LICENSE-2.0
008: // Unless required by applicable law or agreed to in writing, software
009: // distributed under the License is distributed on an "AS IS" BASIS,
010: // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
011: // See the License for the specific language governing permissions and
012: // limitations under the License.
013: // ========================================================================
014:
015: package org.mortbay.jetty.security;
016:
017: import java.security.Principal;
018:
019: import org.mortbay.jetty.Request;
020:
021: /* ------------------------------------------------------------ */
022: /** User Realm.
023: *
024: * This interface should be specialized to provide specific user
025: * lookup and authentication using arbitrary methods.
026: *
027: * For SSO implementation sof UserRealm should also implement SSORealm.
028: *
029: *
030: * @see SSORealm
031: * @author Greg Wilkins (gregw)
032: */
033: public interface UserRealm {
034: /* ------------------------------------------------------------ */
035: public String getName();
036:
037: /* ------------------------------------------------------------ */
038: /** Get the principal for a username.
039: * This method is not guaranteed to return a Principal for non-authenticated users.
040: */
041: public Principal getPrincipal(String username);
042:
043: /* ------------------------------------------------------------ */
044: /** Authenticate a users credentials.
045: * Implementations of this method may adorn the calling context to
046: * assoicate it with the authenticated principal (eg ThreadLocals). If
047: * such context associations are made, they should be considered valid
048: * until a UserRealm.deAuthenticate(UserPrincipal) call is made for this
049: * UserPrincipal.
050: * @param username The username.
051: * @param credentials The user credentials, normally a String password.
052: * @param request The request to be authenticated. Additional
053: * parameters may be extracted or set on this request as needed
054: * for the authentication mechanism (none required for BASIC and
055: * FORM authentication).
056: * @return The authenticated UserPrincipal.
057: */
058: public Principal authenticate(String username, Object credentials,
059: Request request);
060:
061: /* ------------------------------------------------------------ */
062: /** Re Authenticate a Principal.
063: * Authenicate a principal that has previously been return from the authenticate method.
064: *
065: * Implementations of this method may adorn the calling context to
066: * assoicate it with the authenticated principal (eg ThreadLocals). If
067: * such context associations are made, they should be considered valid
068: * until a UserRealm.deAuthenticate(UserPrincipal) call is made for this
069: * UserPrincipal.
070: *
071: * @return True if this user is still authenticated.
072: */
073: public boolean reauthenticate(Principal user);
074:
075: /* ------------------------------------------------------------ */
076: /** Check if the user is in a role.
077: * @param role A role name.
078: * @return True if the user can act in that role.
079: */
080: public boolean isUserInRole(Principal user, String role);
081:
082: /* ------------------------------------------------------------ */
083: /** Dissassociate the calling context with a Principal.
084: * This method is called when the calling context is not longer
085: * associated with the Principal. It should be used by an implementation
086: * to remove context associations such as ThreadLocals.
087: * The UserPrincipal object remains authenticated, as it may be
088: * associated with other contexts.
089: * @param user A UserPrincipal allocated from this realm.
090: */
091: public void disassociate(Principal user);
092:
093: /* ------------------------------------------------------------ */
094: /** Push role onto a Principal.
095: * This method is used to add a role to an existing principal.
096: * @param user An existing UserPrincipal or null for an anonymous user.
097: * @param role The role to add.
098: * @return A new UserPrincipal object that wraps the passed user, but
099: * with the added role.
100: */
101: public Principal pushRole(Principal user, String role);
102:
103: /* ------------------------------------------------------------ */
104: /** Pop role from a Principal.
105: * @param user A UserPrincipal previously returned from pushRole
106: * @return The principal without the role. Most often this will be the
107: * original UserPrincipal passed.
108: */
109: public Principal popRole(Principal user);
110:
111: /* ------------------------------------------------------------ */
112: /** logout a user Principal.
113: * Called by authentication mechanisms (eg FORM) that can detect logout.
114: * @param user A Principal previously returned from this realm
115: */
116: public void logout(Principal user);
117:
118: }
|