1 // ======================================================================== 2 // Copyright 1996-2005 Mort Bay Consulting Pty. Ltd. 3 // ------------------------------------------------------------------------ 4 // Licensed under the Apache License, Version 2.0 (the "License"); 5 // you may not use this file except in compliance with the License. 6 // You may obtain a copy of the License at 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // Unless required by applicable law or agreed to in writing, software 9 // distributed under the License is distributed on an "AS IS" BASIS, 10 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 11 // See the License for the specific language governing permissions and 12 // limitations under the License. 13 // ======================================================================== 14 15 package org.mortbay.jetty.security; 16 import java.security.Principal; 17 18 import org.mortbay.jetty.Request; 19 20 /* ------------------------------------------------------------ */ 21 /** User Realm. 22 * 23 * This interface should be specialized to provide specific user 24 * lookup and authentication using arbitrary methods. 25 * 26 * For SSO implementation sof UserRealm should also implement SSORealm. 27 * 28 * 29 * @see SSORealm 30 * @author Greg Wilkins (gregw) 31 */ 32 public interface UserRealm 33 { 34 /* ------------------------------------------------------------ */ getName()35 public String getName(); 36 37 /* ------------------------------------------------------------ */ 38 /** Get the principal for a username. 39 * This method is not guaranteed to return a Principal for non-authenticated users. 40 */ getPrincipal(String username)41 public Principal getPrincipal(String username); 42 43 /* ------------------------------------------------------------ */ 44 /** Authenticate a users credentials. 45 * Implementations of this method may adorn the calling context to 46 * assoicate it with the authenticated principal (eg ThreadLocals). If 47 * such context associations are made, they should be considered valid 48 * until a UserRealm.deAuthenticate(UserPrincipal) call is made for this 49 * UserPrincipal. 50 * @param username The username. 51 * @param credentials The user credentials, normally a String password. 52 * @param request The request to be authenticated. Additional 53 * parameters may be extracted or set on this request as needed 54 * for the authentication mechanism (none required for BASIC and 55 * FORM authentication). 56 * @return The authenticated UserPrincipal. 57 */ authenticate(String username,Object credentials,Request request)58 public Principal authenticate(String username,Object credentials,Request request); 59 60 /* ------------------------------------------------------------ */ 61 /** Re Authenticate a Principal. 62 * Authenicate a principal that has previously been return from the authenticate method. 63 * 64 * Implementations of this method may adorn the calling context to 65 * assoicate it with the authenticated principal (eg ThreadLocals). If 66 * such context associations are made, they should be considered valid 67 * until a UserRealm.deAuthenticate(UserPrincipal) call is made for this 68 * UserPrincipal. 69 * 70 * @return True if this user is still authenticated. 71 */ reauthenticate(Principal user)72 public boolean reauthenticate(Principal user); 73 74 /* ------------------------------------------------------------ */ 75 /** Check if the user is in a role. 76 * @param role A role name. 77 * @return True if the user can act in that role. 78 */ isUserInRole(Principal user, String role)79 public boolean isUserInRole(Principal user, String role); 80 81 /* ------------------------------------------------------------ */ 82 /** Dissassociate the calling context with a Principal. 83 * This method is called when the calling context is not longer 84 * associated with the Principal. It should be used by an implementation 85 * to remove context associations such as ThreadLocals. 86 * The UserPrincipal object remains authenticated, as it may be 87 * associated with other contexts. 88 * @param user A UserPrincipal allocated from this realm. 89 */ disassociate(Principal user)90 public void disassociate(Principal user); 91 92 /* ------------------------------------------------------------ */ 93 /** Push role onto a Principal. 94 * This method is used to add a role to an existing principal. 95 * @param user An existing UserPrincipal or null for an anonymous user. 96 * @param role The role to add. 97 * @return A new UserPrincipal object that wraps the passed user, but 98 * with the added role. 99 */ pushRole(Principal user, String role)100 public Principal pushRole(Principal user, String role); 101 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 */ popRole(Principal user)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 */ logout(Principal user)116 public void logout(Principal user); 117 118 } 119