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 */
019 package org.apache.wiki.auth;
020
021 import java.security.Principal;
022 import java.util.Properties;
023
024 import org.apache.wiki.WikiEngine;
025 import 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 */
046 public 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 }