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 }