javax.security.enterprise.SecurityContext Maven / Gradle / Ivy
Show all versions of jboss-javaee-all-8.0
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 2015-2017 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://oss.oracle.com/licenses/CDDL+GPL-1.1
* or 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 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 javax.security.enterprise;
import java.security.Principal;
import java.util.Set;
import javax.ejb.SessionContext;
import javax.security.enterprise.authentication.mechanism.http.AuthenticationParameters;
import javax.security.enterprise.authentication.mechanism.http.HttpAuthenticationMechanism;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
/**
* The SecurityContext provides an access point for programmatic security; an injectable type that is intended to be
* used by application code to query and interact with the Java EE Security API.
*
*
* Unless otherwise indicated, this type must be usable in all Java EE containers, specifically the Servlet
* and EJB containers.
*
*
*/
public interface SecurityContext {
/**
* Retrieve the platform-specific java.security.Principal that represents
* the name of authenticated caller, or null if the current caller is not authenticated.
*
* @return Principal representing the name of the current authenticated user, or null if not authenticated.
*/
Principal getCallerPrincipal();
/**
* Retrieve all Principals of the given type from the authenticated caller's Subject,
* or an empty set if the current caller is not authenticated, or if the specified type
* isn't found in the Subject.
*
* This can be used to retrieve application-specific
* Principals when the platform's representation of the caller uses a different principal type.
*
* The returned Set is not backed by the Subject's internal Principal Set.
* A new Set is created and returned for each method invocation.
* Modifications to the returned Set will not affect the internal Principal Set.
*
* @param pType Class object representing the type of Principal to return.
*
* @return Set of Principals of the given type, or an empty set.
*/
Set getPrincipalsByType(Class pType);
/**
* Checks whether the authenticated caller is included in the specified logical application "role".
* If the caller is not authenticated, this always returns false.
*
*
* This method can not be used to test for roles that are mapped to specific named Servlets or
* named EJB beans. For a Servlet an example of this would be the role-name nested in a
* security-role-ref element nested in a servlet element in web.xml.
*
*
* Should code in either such Servlet or EJB bean wish to take such mapped (aka referenced, linked) roles into
* account, the facilities for that specific container should be used instead. For instance for Servlet that would
* be {@link HttpServletRequest#isUserInRole(String)} and for EJB beans that would be
* {@link SessionContext#isCallerInRole(String)}.
*
*
* @param role a String specifying the name of the logical application role
* @return true if the authenticated caller is in the given role, false if the caller is not authentication or
* is not in the given role.
*/
boolean isCallerInRole(String role);
/**
* Checks whether the caller has access to the provided "web resource" using the given methods,
* as specified by section 13.8 of the Servlet specification.
*
*
* A caller has access if the web resource is either not protected (constrained), or when it is protected by a role
* and the caller is in that role.
*
* @param resource the name of the web resource to test access for. This is a URLPatternSpec that
* identifies the application specific web resources to which the permission pertains. For a full specification of this
* pattern see {@link javax.security.jacc.WebResourcePermission#WebResourcePermission(String, String)}.
* @param methods one or more methods to check for whether the caller has access to the web resource using one of those methods.
*
* @return true if the caller has access to the web resource using one of the given methods, false otherwise.
*/
boolean hasAccessToWebResource(String resource, String... methods);
/**
* Signal to the container (programmatically trigger) that it should start or continue a web/HTTP based authentication dialog with
* the caller.
*
*
* Programmatically triggering means that the container responds as if the caller had attempted to access a constrained resource
* and acts by invoking a configured authentication mechanism (such as the {@link HttpAuthenticationMechanism}).
*
*
* Whether the authentication dialog is to be started or continued depends on the (logical) state of the authentication dialog. If
* such dialog is currently in progress, a call to this method will continue it. If such dialog is not in progress a new one will be
* started. A new dialog can be forced to be started regardless of one being in progress or not by providing a value of
* true for the {@link AuthenticationParameters#newAuthentication} parameter with this call.
*
*
* This method requires an {@link HttpServletRequest} and {@link HttpServletResponse} argument to be passed in, and
* can therefore only be used in a valid Servlet context.
*
* @param request The HttpServletRequest associated with the current web resource invocation.
* @param response The HttpServletResponse associated with the given HttpServletRequest.
* @param parameters The parameters that are provided along with a programmatic authentication request, for instance the credentials.
* collected by the application for continuing an authentication dialog.
*
* @return The state of the authentication mechanism after being triggered by this call
*/
AuthenticationStatus authenticate(HttpServletRequest request, HttpServletResponse response, AuthenticationParameters parameters);
}