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; 16 import java.security.Principal; 17 18 /* ------------------------------------------------------------ */ 19 /** User Realm. 20 * 21 * This interface should be specialized to provide specific user 22 * lookup and authentication using arbitrary methods. 23 * 24 * For SSO implementation sof UserRealm should also implement SSORealm. 25 * 26 * @see SSORealm 27 * @author Greg Wilkins (gregw) 28 */ 29 public interface UserRealm 30 { 31 /* ------------------------------------------------------------ */ 32 /* ------------------------------------------------------------ */ 33 /* ------------------------------------------------------------ */ 34 /** Nobody user. 35 * The Nobody UserPrincipal is used to indicate a partial state of 36 * authentication. A request with a Nobody UserPrincipal will be allowed 37 * past all authentication constraints - but will not be considered an 38 * authenticated request. It can be used by Authenticators such as 39 * FormAuthenticator to allow access to logon and error pages within an 40 * authenticated URI tree. 41 */ 42 public static final Principal NOBODY=new Principal() 43 { 44 public String getName() 45 { 46 return "Nobody"; 47 } 48 49 public String toString() 50 { 51 return getName(); 52 } 53 }; 54 55 /* ------------------------------------------------------------ */ 56 public static final Principal NOT_CHECKED=new Principal() 57 { 58 public String getName() 59 { 60 return "NOT CHECKED"; 61 } 62 63 public String toString() 64 { 65 return getName(); 66 } 67 }; 68 69 /* ------------------------------------------------------------ */ 70 public static final Principal NO_USER=new Principal() 71 { 72 public String getName() 73 { 74 return "No User"; 75 } 76 77 public String toString() 78 { 79 return getName(); 80 } 81 }; 82 83 /* ------------------------------------------------------------ */ 84 public String getName(); 85 86 /* ------------------------------------------------------------ */ 87 /** Get the principal for a username. 88 * This method is not guaranteed to return a Principal for non-authenticated users. 89 */ 90 public Principal getPrincipal(String username); 91 92 /* ------------------------------------------------------------ */ 93 /** Authenticate a users credentials. 94 * Implementations of this method may adorn the calling context to 95 * assoicate it with the authenticated principal (eg ThreadLocals). If 96 * such context associations are made, they should be considered valid 97 * until a UserRealm.deAuthenticate(UserPrincipal) call is made for this 98 * UserPrincipal. 99 * @param username The username. 100 * @param credentials The user credentials, normally a String password. 101 * @param request The request to be authenticated. Additional 102 * parameters may be extracted or set on this request as needed 103 * for the authentication mechanism (none required for BASIC and 104 * FORM authentication). 105 * @return The authenticated UserPrincipal. 106 */ 107 public Principal authenticate(String username,Object credentials,Request request); 108 109 /* ------------------------------------------------------------ */ 110 /** Re Authenticate a Principal. 111 * Authenicate a principal that has previously been return from the authenticate method. 112 * 113 * Implementations of this method may adorn the calling context to 114 * assoicate it with the authenticated principal (eg ThreadLocals). If 115 * such context associations are made, they should be considered valid 116 * until a UserRealm.deAuthenticate(UserPrincipal) call is made for this 117 * UserPrincipal. 118 * 119 * @return True if this user is still authenticated. 120 */ 121 public boolean reauthenticate(Principal user); 122 123 /* ------------------------------------------------------------ */ 124 /** Check if the user is in a role. 125 * @param role A role name. 126 * @return True if the user can act in that role. 127 */ 128 public boolean isUserInRole(Principal user, String role); 129 130 /* ------------------------------------------------------------ */ 131 /** Dissassociate the calling context with a Principal. 132 * This method is called when the calling context is not longer 133 * associated with the Principal. It should be used by an implementation 134 * to remove context associations such as ThreadLocals. 135 * The UserPrincipal object remains authenticated, as it may be 136 * associated with other contexts. 137 * @param user A UserPrincipal allocated from this realm. 138 */ 139 public void disassociate(Principal user); 140 141 /* ------------------------------------------------------------ */ 142 /** Push role onto a Principal. 143 * This method is used to add a role to an existing principal. 144 * @param user An existing UserPrincipal or null for an anonymous user. 145 * @param role The role to add. 146 * @return A new UserPrincipal object that wraps the passed user, but 147 * with the added role. 148 */ 149 public Principal pushRole(Principal user, String role); 150 151 152 /* ------------------------------------------------------------ */ 153 /** Pop role from a Principal. 154 * @param user A UserPrincipal previously returned from pushRole 155 * @return The principal without the role. Most often this will be the 156 * original UserPrincipal passed. 157 */ 158 public Principal popRole(Principal user); 159 160 /* ------------------------------------------------------------ */ 161 /** logout a user Principal. 162 * Called by authentication mechanisms (eg FORM) that can detect logout. 163 * @param user A Principal previously returned from this realm 164 */ 165 public void logout(Principal user); 166 167 }