001/* 
002    Licensed to the Apache Software Foundation (ASF) under one
003    or more contributor license agreements.  See the NOTICE file
004    distributed with this work for additional information
005    regarding copyright ownership.  The ASF licenses this file
006    to you under the Apache License, Version 2.0 (the
007    "License"); you may not use this file except in compliance
008    with the License.  You may obtain a copy of the License at
009
010       http://www.apache.org/licenses/LICENSE-2.0
011
012    Unless required by applicable law or agreed to in writing,
013    software distributed under the License is distributed on an
014    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015    KIND, either express or implied.  See the License for the
016    specific language governing permissions and limitations
017    under the License.  
018 */
019package org.apache.wiki.auth;
020
021import java.security.Principal;
022import java.util.Properties;
023
024import org.apache.wiki.WikiEngine;
025import org.apache.wiki.WikiSession;
026
027/**
028 * Interface for service providers of authorization information. After a user
029 * successfully logs in, the
030 * {@link org.apache.wiki.auth.AuthenticationManager} consults the configured
031 * Authorizer to determine which additional
032 * {@link org.apache.wiki.auth.authorize.Role} principals should be added to
033 * the user's WikiSession. To determine which roles should be injected, the
034 * Authorizer is queried for the roles it knows about by calling
035 * {@link org.apache.wiki.auth.Authorizer#getRoles()}. Then, each role
036 * returned by the Authorizer is tested by calling
037 * {@link org.apache.wiki.auth.Authorizer#isUserInRole(WikiSession, Principal)}.
038 * If this check fails, and the Authorizer is of type WebAuthorizer,
039 * AuthenticationManager checks the role again by calling
040 * {@link org.apache.wiki.auth.authorize.WebAuthorizer#isUserInRole(javax.servlet.http.HttpServletRequest, Principal)}).
041 * Any roles that pass the test are injected into the Subject by firing
042 * appropriate authentication events.
043 * 
044 * @since 2.3
045 */
046public interface Authorizer
047{
048
049    /**
050     * Returns an array of role Principals this Authorizer knows about. This
051     * method will always return an array; an implementing class may choose to
052     * return an zero-length array if it has no ability to identify the roles
053     * under its control.
054     * 
055     * @return an array of Principals representing the roles
056     */
057    Principal[] getRoles();
058
059    /**
060     * Looks up and returns a role Principal matching a given String. If a
061     * matching role cannot be found, this method returns <code>null</code>.
062     * Note that it may not always be feasible for an Authorizer implementation
063     * to return a role Principal.
064     * 
065     * @param role the name of the role to retrieve
066     * @return the role Principal
067     */
068    Principal findRole( String role );
069
070    /**
071     * Initializes the authorizer.
072     * 
073     * @param engine the current wiki engine
074     * @param props the wiki engine initialization properties
075     * @throws WikiSecurityException if the Authorizer could not be initialized
076     */
077    void initialize( WikiEngine engine, Properties props ) throws WikiSecurityException;
078
079    /**
080     * Determines whether the Subject associated with a WikiSession is in a
081     * particular role. This method takes two parameters: the WikiSession
082     * containing the subject and the desired role ( which may be a Role or a
083     * Group). If either parameter is <code>null</code>, this method must
084     * return <code>false</code>.
085     * 
086     * @param session the current WikiSession
087     * @param role the role to check
088     * @return <code>true</code> if the user is considered to be in the role,
089     *         <code>false</code> otherwise
090     */
091    boolean isUserInRole( WikiSession session, Principal role );
092
093}