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 org.apache.wiki.api.core.Engine;
022import org.apache.wiki.api.core.Session;
023
024import java.security.Principal;
025import java.util.Properties;
026
027
028/**
029 * Interface for service providers of authorization information. After a user successfully logs in, the
030 * {@link org.apache.wiki.auth.AuthenticationManager} consults the configured Authorizer to determine which additional
031 * {@link org.apache.wiki.auth.authorize.Role} principals should be added to the user's Session. To determine which roles should be
032 * injected, the Authorizer is queried for the roles it knows about by calling {@link org.apache.wiki.auth.Authorizer#getRoles()}. Then,
033 * each role returned by the Authorizer is tested by calling {@link org.apache.wiki.auth.Authorizer#isUserInRole(Session, Principal)}.
034 * If this check fails, and the Authorizer is of type WebAuthorizer, AuthenticationManager checks the role again by calling
035 * {@link org.apache.wiki.auth.authorize.WebAuthorizer#isUserInRole(javax.servlet.http.HttpServletRequest, Principal)}).
036 * Any roles that pass the test are injected into the Subject by firing appropriate authentication events.
037 * 
038 * @since 2.3
039 */
040public interface Authorizer {
041
042    /**
043     * Returns an array of role Principals this Authorizer knows about. This method will always return an array; an implementing class may
044     * choose to return an zero-length array if it has no ability to identify the roles under its control.
045     * 
046     * @return an array of Principals representing the roles
047     */
048    Principal[] getRoles();
049
050    /**
051     * Looks up and returns a role Principal matching a given String. If a matching role cannot be found, this method returns
052     * <code>null</code>. Note that it may not always be feasible for an Authorizer implementation to return a role Principal.
053     * 
054     * @param role the name of the role to retrieve
055     * @return the role Principal
056     */
057    Principal findRole( String role );
058
059    /**
060     * Initializes the authorizer.
061     * 
062     * @param engine the current wiki engine
063     * @param props the wiki engine initialization properties
064     * @throws WikiSecurityException if the Authorizer could not be initialized
065     */
066    void initialize( Engine engine, Properties props ) throws WikiSecurityException;
067
068    /**
069     * Determines whether the Subject associated with a WikiSession is in a particular role. This method takes two parameters: the
070     * WikiSession containing the subject and the desired role ( which may be a Role or a Group). If either parameter is <code>null</code>,
071     * this method must return <code>false</code>.
072     * 
073     * @param session the current WikiSession
074     * @param role the role to check
075     * @return <code>true</code> if the user is considered to be in the role, <code>false</code> otherwise
076     */
077    boolean isUserInRole( Session session, Principal role );
078
079}