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 }