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 /* ------------------------------------------------------------ */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 }