    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}