| /* |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| */ |
| package org.apache.wiki.auth; |
| |
| import org.apache.wiki.WikiSession; |
| import org.apache.wiki.api.core.Engine; |
| |
| import java.security.Principal; |
| import java.util.Properties; |
| |
| |
| /** |
| * Interface for service providers of authorization information. After a user successfully logs in, the |
| * {@link org.apache.wiki.auth.AuthenticationManager} consults the configured Authorizer to determine which additional |
| * {@link org.apache.wiki.auth.authorize.Role} principals should be added to the user's WikiSession. To determine which roles should be |
| * injected, the Authorizer is queried for the roles it knows about by calling {@link org.apache.wiki.auth.Authorizer#getRoles()}. Then, |
| * each role returned by the Authorizer is tested by calling {@link org.apache.wiki.auth.Authorizer#isUserInRole(WikiSession, Principal)}. |
| * If this check fails, and the Authorizer is of type WebAuthorizer, AuthenticationManager checks the role again by calling |
| * {@link org.apache.wiki.auth.authorize.WebAuthorizer#isUserInRole(javax.servlet.http.HttpServletRequest, Principal)}). |
| * Any roles that pass the test are injected into the Subject by firing appropriate authentication events. |
| * |
| * @since 2.3 |
| */ |
| public interface Authorizer { |
| |
| /** |
| * Returns an array of role Principals this Authorizer knows about. This method will always return an array; an implementing class may |
| * choose to return an zero-length array if it has no ability to identify the roles under its control. |
| * |
| * @return an array of Principals representing the roles |
| */ |
| Principal[] getRoles(); |
| |
| /** |
| * Looks up and returns a role Principal matching a given String. If a matching role cannot be found, this method returns |
| * <code>null</code>. Note that it may not always be feasible for an Authorizer implementation to return a role Principal. |
| * |
| * @param role the name of the role to retrieve |
| * @return the role Principal |
| */ |
| Principal findRole( String role ); |
| |
| /** |
| * Initializes the authorizer. |
| * |
| * @param engine the current wiki engine |
| * @param props the wiki engine initialization properties |
| * @throws WikiSecurityException if the Authorizer could not be initialized |
| */ |
| void initialize( Engine engine, Properties props ) throws WikiSecurityException; |
| |
| /** |
| * Determines whether the Subject associated with a WikiSession is in a particular role. This method takes two parameters: the |
| * WikiSession containing the subject and the desired role ( which may be a Role or a Group). If either parameter is <code>null</code>, |
| * this method must return <code>false</code>. |
| * |
| * @param session the current WikiSession |
| * @param role the role to check |
| * @return <code>true</code> if the user is considered to be in the role, <code>false</code> otherwise |
| */ |
| boolean isUserInRole( WikiSession session, Principal role ); |
| |
| } |