View Javadoc

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 }