org.glassfish.security.services.api.authorization.AuthorizationService Maven / Gradle / Ivy
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 2012 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
* or packager/legal/LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at packager/legal/LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
* exception as provided by Oracle in the GPL Version 2 section of the License
* file that accompanied this code.
*
* Modifications:
* If applicable, add the following below the License Header, with the fields
* enclosed by brackets [] replaced by your own identifying information:
* "Portions Copyright [year] [name of copyright owner]"
*
* Contributor(s):
* If you wish your version of this file to be governed by only the CDDL or
* only the GPL Version 2, indicate your decision by adding "[Contributor]
* elects to include this software in this distribution under the [CDDL or GPL
* Version 2] license." If you don't indicate a single choice of license, a
* recipient has the option to distribute your version of this file under
* either the CDDL, the GPL Version 2 or to extend the choice of license to
* its licensees as provided above. However, if you add GPL Version 2 code
* and therefore, elected the GPL Version 2 license, then the option applies
* only if the new code is made subject to such option by the copyright
* holder.
*/
package org.glassfish.security.services.api.authorization;
import java.net.URI;
import java.security.Permission;
import java.util.List;
import javax.security.auth.Subject;
import org.glassfish.security.services.api.SecurityService;
import org.jvnet.hk2.annotations.Contract;
/**
* The AuthorizationService interface provides methods that allow server and container
* to determine whether access should be allowed to a particular resource. It is intended for
* internal use, not for use by applications.
*/
@Contract
public interface AuthorizationService extends SecurityService {
/**
* Determines whether the given Subject has been granted the specified Permission
* by delegating to the configured java.security.Policy object. This method is
* a high-level convenience method that tests for a Subject-based permission
* grant without reference to the AccessControlContext of the caller.
*
* In addition, this method isolates the query from the underlying Policy configuration
* model. It could, for example, multiplex queries across multiple instances of Policy
* configured in an implementation-specific way such that different threads, or different
* applications, query different Policy objects. The initial implementation simply
* delegates to the configured Policy as defined by Java SE.
*
* @param subject The Subject for which permission is being tested.
* @param permission The Permission being queried.
* @return True or false, depending on whether the specified Permission
* is granted to the Subject by the configured Policy.
* @throws IllegalArgumentException Given null or illegal subject or permission
*/
public boolean isPermissionGranted(Subject subject, Permission permission);
/**
* Determines whether the given Subject is authorized to access the given resource,
* specified by a URI.
*
* @param subject The Subject being tested.
* @param resource URI of the resource being tested.
* @return True or false, depending on whether the access is authorized.
* @throws IllegalArgumentException Given null or illegal subject or resource
* @throws IllegalStateException Service was not initialized.
*/
public boolean isAuthorized(Subject subject, URI resource);
/**
* Determines whether the given Subject is authorized to access the given resource,
* specified by a URI.
*
* @param subject The Subject being tested.
* @param resource URI of the resource being tested.
* @param action The action, with respect to the resource parameter,
* for which authorization is desired. To check authorization for all actions,
* action is represented by null or "*".
* @return True or false, depending on whether the access is authorized.
* @throws IllegalArgumentException Given null or illegal subject or resource
* @throws IllegalStateException Service was not initialized.
*/
public boolean isAuthorized(Subject subject, URI resource, String action);
/**
* The primary authorization method. The isAuthorized() methods call this method
* after converting their arguments into the appropriate attribute collection type.
* It returns a full AzResult, including authorization status, decision, and
* obligations.
*
* This method performs two steps prior to invoking the configured AuthorizationProvider
* to evaluate the request: First, it acquires the current AzEnvironment attributes by
* calling the Security Context service. Second, it calls the Role Mapping service to
* determine which roles the subject has, and adds the resulting role attributes into
* the AzSubject.
*
* @param subject The attributes collection representing the Subject for which an authorization
* decision is requested.
* @param resource The attributes collection representing the resource for which access is
* being requested.
* @param action The attributes collection representing the action, with respect to the resource,
* for which access is being requested. A null action is interpreted as all
* actions, however all actions may also be represented by the AzAction instance.
* See {@link org.glassfish.security.services.api.authorization.AzAction}.
* @return The AzResult indicating the result of the access decision.
* @throws IllegalArgumentException Given null or illegal subject or resource
* @throws IllegalStateException Service was not initialized.
*/
public AzResult getAuthorizationDecision(AzSubject subject, AzResource resource, AzAction action);
/**
* Converts a Java Subject into a typed attributes collection.
*
* @param subject The Subject to convert.
* @return The resulting AzSubject.
* @throws IllegalArgumentException Given null or illegal subject
*/
public AzSubject makeAzSubject(Subject subject);
/**
* Converts a resource, expressed as a URI, into a typed attributes collection.
*
* Query parameters in the given URI are appended to this
* AzResource instance attributes collection.
*
* @param resource The URI to convert.
* @return The resulting AzResource.
* @throws IllegalArgumentException Given null or illegal resource
*/
public AzResource makeAzResource(URI resource);
/**
* Converts an action, expressed as a String, into a typed attributes collection.
*
* @param action The action to convert. null or "*" represents all actions.
* @return The resulting AzAction.
*/
public AzAction makeAzAction(String action);
// TODO: What if multiple providers? Rollback/closeWithoutChange? Would delete remove an existing PolicyDeploymentContext?
/**
* Finds an existing PolicyDeploymentContext, or create a new one if one does not
* already exist for the specified appContext. The context will be returned in
* an "open" state, and will stay that way until commit() or delete() is called.
*
* @param appContext The application context for which the PolicyDeploymentContext
* is desired.
* @return The resulting PolicyDeploymentContext,
* null if the configured providers do not support this feature.
* @throws IllegalStateException Service was not initialized.
*/
public PolicyDeploymentContext findOrCreateDeploymentContext(String appContext);
/**
* This interface represents a PolicyDeploymentContext as returned by the Authorization
* Service's findOrCreateDeploymentContext() method. The PolicyDeploymentContext is used
* to configure authorization policy for an application (or server administration) context.
* It represents the body of policy that applies to the given context.
*
* A PolicyDeploymentContext is always in one of three states: open, closed/inService,
* or deleted. When returned by the Authorization service, a context is in an open state.
* Policies can be added or deleted while in the open state, but the context is not
* in service. Upon calling commit(), the context is closed and the policies are place
* in service. Upon calling delete(), the context is taken out of service and the policies
* are deleted from the Authorization Provider.
*/
public interface PolicyDeploymentContext {
public void addRolePolicy(String role, String resource, String action);
public void addUncheckedPolicy(String resource, String action);
public void addExcludedPolicy(String resource, String action);
public void removeRolePolicy(String role);
public void removeRolePolicies();
public void removeUncheckedPolicies();
public void removeExcludedPolicies();
public void commit();
public void delete();
}
/**
* Appends the given {@link org.glassfish.security.services.api.authorization.AzAttributeResolver}
* instance to the internal ordered list of AzAttributeResolver instances,
* if not currently in the list based on
* {@link org.glassfish.security.services.api.authorization.AzAttributeResolver#equals}.
*
* @param resolver The AzAttributeResolver instance to append.
* @return true if the AzAttributeResolver was added,
* false if the AzAttributeResolver was already in the list.
* @throws IllegalArgumentException Given AzAttributeResolver was null.
*/
public boolean appendAttributeResolver(AzAttributeResolver resolver);
/**
* Replaces the internal list of AttributeResolver instances
* with the given list. If multiple equivalent instances exist in the given list,
* only the first such instance will be inserted.
*
* @param resolverList Replacement list of AzAttributeResolver instances
* @throws IllegalArgumentException Given AzAttributeResolver list was null.
*/
public void setAttributeResolvers(List resolverList);
/**
* Determines the current list of AttributeResolver instances,
* in execution order.
*
* @return The current list of AttributeResolver instances,
* in execution order.
*/
public List getAttributeResolvers();
/**
* Removes all AttributeResolver instances from the current
* internal list of AttributeResolver instances.
*
* @return true if any AttributeResolver instances were removed,
* false if the list was empty.
*/
public boolean removeAllAttributeResolvers();
}