<?xml version="1.0" encoding="UTF-8"?>
<!--

    Copyright (c) 2018 Oracle and/or its affiliates. All rights reserved.

    This program and the accompanying materials are made available under the
    terms of the Eclipse Public License v. 2.0, which is available at
    http://www.eclipse.org/legal/epl-2.0.

    This Source Code may also be made available under the following Secondary
    Licenses when the conditions for such availability set forth in the
    Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
    version 2 with the GNU Classpath Exception, which is available at
    https://www.gnu.org/software/classpath/license.html.

    SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0

-->

<?xml-stylesheet type="text/xsl" href="https://raw.githubusercontent.com/eclipse-ee4j/jakartaee-tck/master/internal/docs/xsl/spec_assertions.xsl"?>

<spec>
	<next-available-id>346</next-available-id>
	<previous-id>1</previous-id>
	<technology>SecurityAPI</technology>
	<id>Security API 1.0</id>
	<name>Java EE Security API</name>
	<version>1.0</version>	
	<location-names>
		<chapters>
			<chapter id="" name="">
				<sections>
					<section id="" name=""/>
				</sections>
			</chapter>
		</chapters>
	</location-names>
	<assertions>
	    <assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
			<id>Security:SPEC:2.2-1</id>
			<description>validateRequest() will be invoked before the doFilter() method of any servlet filter or the service() method of any servlet in the application for requests</description>      			   
			<location chapter="2" section="2"/>    
		</assertion>
		<assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
			<id>Security:SPEC:2.2-2</id>
			<description>in addition, in response to application code calling the authenticate() method on the HttpServletRequest.</description>      			   
			<location chapter="2" section="2"/>    
		</assertion>
		<assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
			<id>Security:SPEC:2.2-3</id>
			<description>secureResponse() will be invoked after the doFilter() method of any servlet filter or the service() method of any servlet in the application for requests to constrained as well as to unconstrained resources, but only if any of these two methods have indeed been invoked.</description>      			   
			<location chapter="2" section="2"/>    
		</assertion>
		<assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
			<id>Security:SPEC:2.2-4</id>
			<description>cleanSubject() will be invoked in response to the application calling the logout() method on the
HttpServletRequest</description>      			   
			<location chapter="2" section="2"/>    
		</assertion>
		<assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
			<id>Security:SPEC:2.2-5</id>
			<description>The validateRequest() method is provided to allow a caller to authenticate. An implementation of this method can inspect the HTTP request to extract a credential or other information, or it can write to the HTTP response to, for example, redirect a caller to an OAuth provider, or return an error response. </description>      			   
			<location chapter="2" section="2"/>    
		</assertion>
		<assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
			<id>Security:SPEC:2.2-6</id>
			<description>After a credential has been obtained and validated, the result of the validation can be communicated to the container using the HttpMessageContext parameter, which is described in more detail below.</description>      			   
			<location chapter="2" section="2"/>    
		</assertion>
		<assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
			<id>Security:SPEC:2.3-1</id>
			<description>An HttpAuthenticationMechanism must be a CDI bean.</description>      			   
			<location chapter="2" section="3"/>    
		</assertion>
		<assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
			<id>Security:SPEC:2.3-2</id>
			<description>An HttpAuthenticationMechanism is assumed to be normal scoped.</description>      			   
			<location chapter="2" section="3"/>    
		</assertion>
		<assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
			<id>Security:SPEC:2.3-3</id>
			<description>It MUST be possible for the definition of an HttpAuthenticationMechanism to exist within the application archive. </description>      			   
			<location chapter="2" section="3"/>    
		</assertion>
		<assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
			<id>Security:SPEC:2.3-4</id>
			<description>The container MAY override an application’s chosen HttpAuthenticationMechanism with one selected by the container, but SHOULD do so only if explicitly configured to.

If the container does not override the application, it MUST place in service any HttpAuthenticationMechanism that is provided, either directly or via annotation, by the application.</description>      			   
			<location chapter="2" section="3"/>    
		</assertion>
		<assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
			<id>Security:SPEC:2.3-5</id>
			<description>The container MUST supply a "bridge" ServerAuthModule that integrates HttpAuthenticationMechanism with JASPIC.</description>      			   
			<location chapter="2" section="3"/>    
		</assertion>
		<assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
			<id>Security:SPEC:2.3-6</id>
			<description>The bridge module MUST look up the correct HttpAuthenticationMechanism using CDI, then delegate to the HttpAuthenticationMechanism when the bridge module’s methods are invoked.</description>      			   
			<location chapter="2" section="3"/>    
		</assertion>
		<assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
			<id>Security:SPEC:2.3-7</id>
			<description>Since the method signatures and return values of the two interfaces are similar, but not the same, the bridge module MUST convert back and forth.</description>      			   
			<location chapter="2" section="3"/>    
		</assertion>
		<assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
			<id>Security:SPEC:2.4-1</id>
			<description>BASIC - Authenticates according to the mechanism as described in 13.6.1, "HTTP Basic Authentication", in [SERVLET31]. See also RFC 7617, "The 'Basic' HTTP Authentication Scheme" [RFC7617]. This bean is activated and configured via the @BasicAuthenticationMechanismDefinition annotation.</description>      			   
			<location chapter="2" section="4"/>    
		</assertion>
		<assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
			<id>Security:SPEC:2.4-2</id>
			<description>FORM - Authenticates according to the mechanism as described in 13.6.3, "Form Based Authentication", in [SERVLET31]. This bean is activated and configured via the @FormAuthenticationMechanismDefinition annotation.</description>      			   
			<location chapter="2" section="4"/>    
		</assertion>
        <assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
                <id>Security:SPEC:2.4-3</id>
                <description>Custom FORM - A variant on FORM, with the difference that continuing the authentication dialog as described in [SERVLET31], section 13.6.3, step 3, and further clarified in section 13.6.3.1, does not happen by posting back to j_security_check, but by invoking SecurityContext.authenticate() with the credentials the application collected. This bean is activated and configured via the @CustomFormAuthenticationMechanismDefinition annotation.</description>
                <location chapter="2" section="4"/>
        </assertion>
        <assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
                <id>Security:SPEC:2.4-4</id>
                <description>All of these beans MUST have the qualifier @Default and the scope @ApplicationScoped, as defined by the CDI specification.</description>
                <location chapter="2" section="4"/>
        </assertion>
        <assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
                <id>Security:SPEC:2.4-5</id>
                <description>All of the built-in beans MUST support authentication using IdentityStore</description>
                <location chapter="2" section="4"/>
        </assertion>
        <assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
                <id>Security:SPEC:2.4.6-1</id>
                <description>AutoApplySession Annotation</description>
                <location chapter="2" section="4.6"/>
        </assertion>
        <assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
                <id>Security:SPEC:2.5-1</id>
                <description>This specification mandates that when a ServerAuthModule is called by the Servlet container, CDI services (such as the BeanManager) MUST be fully available, and all scopes that are defined to be active during the service() method of a servlet, or during the doFilter() method of a servlet filter, MUST be active. </description>
                <location chapter="2" section="5"/>
        </assertion>
        <assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
                <id>Security:SPEC:2.5-2</id>
                <description>Specifically this means that the request, session, and application scopes MUST be active, and that a ServerAuthModule method such as validateRequest() MUST be able to obtain a reference to the CDI BeanManager programmatically (for example, by doing a JNDI lookup), and MUST be able to use that reference to obtain a valid request-scoped, session-scoped, or application-scoped bean. </description>
                <location chapter="2" section="5"/>
        </assertion>
		<assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
			<id>Security:SPEC:3.1-1</id>
			<description> The IdentityStoreHandler interface defines a mechanism for invoking on IdentityStore to validate a user credential.
			</description>      			   
			<location chapter="3" section="1"/>    
		</assertion>
 		<assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
			<id>Security:SPEC:3.1-2</id>
			<description> An IdentityStoreHandler can also orchestrate an authentication across multiple IdentityStore instances, returning an aggregated result.
                        </description>      			    
			<location chapter="3" section="1"/>    
		</assertion>
		<assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
			<id>Security:SPEC:3.1-3</id>
			<description> A default IdentityStoreHandler implementation is supplied by the container
                        </description>      			    
			<location chapter="3" section="1"/>    
		</assertion>
		<assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
			<id>Security:SPEC:3.1-4</id>
			<description> but applications can also supply their own implementation. 
		        </description>      			    
			<location chapter="3" section="1"/>    
		</assertion>
		<assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
			<id>Security:SPEC:3.2-1</id>
			<description>An implementation of IdentityStore can choose to handle either or both of these methods, depending on its capabilities and configuration. It indicates which methods it handles through the set of values returned by its validationTypes() method</description>      			   
			<location chapter="3" section="2"/>    
		</assertion>
			<assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
			<id>Security:SPEC:3.2.1-1</id>
			<description>Only the caller principal is required to be present for a successful validation.</description>      			    
			<location chapter="3" section="2.1"/>    
		</assertion>
		<assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
			<id>Security:SPEC:3.2.1-2</id>
			<description>VALID: Validation succeeded and the user is authenticated. The caller principal and groups (if any) are available ONLY with this result status.</description>      			    
			<location chapter="3" section="2.1"/>    
		</assertion>
		<assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
			<id>Security:SPEC:3.2.1-3</id>
			<description>INVALID: Validation failed. The supplied Credential was invalid, or the corresponding user was not found in the user store.</description>      			    
			<location chapter="3" section="2.1"/>    
		</assertion>
		<assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
			<id>Security:SPEC:3.2.1-4</id>
			<description>NOT_VALIDATED: Validation was not attempted, because the IdentityStore does not handle the supplied Credential type.</description>      			   
			<location chapter="3" section="2.1"/>    
		</assertion>
			<assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
			<id>Security:SPEC:3.2.1-5</id>
			<description>for example, validate(Credential) would delegate to the following method of ExampleIdentityStore if passed a UsernamePasswordCredential</description>      			    
			<location chapter="3" section="2.1"/>    
		</assertion>
		<assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
			<id>Security:SPEC:3.2.2-1</id>
			<description>The getCallerGroups() method supports aggregation of identity stores, where one identity store is used to authenticate users, but one or more other stores are used to retrieve additional groups. In such a scenario, it is necessary to query identity stores without validating the caller’s credential against the stores.</description>      			    
			<location chapter="3" section="2.2"/>    
		</assertion>
		<assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
			<id>Security:SPEC:3.2.2-2</id>
			<description>Note that getCallerGroups() is not intended as a general purpose API for retrieving user groups. It should be called only by an IdentityStoreHandler, in the course of orchestrating a validate() call across multiple identity stores.</description>      			    
			<location chapter="3" section="2.2"/>    
		</assertion>
		<assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
			<id>Security:SPEC:3.2.2-4</id>
			<description>As a result, it is never necessary to call getCallerGroups() when there is only one IdentityStore, because the same groups are returned by the validate() method.</description>      			    
			<location chapter="3" section="2.2"/>    
		</assertion>
		<assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
			<id>Security:SPEC:3.2.3-1</id>
			<description>The priority() method allows an IdentityStore to be configured with an ordinal number indicating the order in which it should be consulted when multiple IdentityStores are present (more precisely, when multiple enabled CDI Beans with type IdentityStore are available). Lower numbers represent higher priority, so an IdentityStore with a lower priority value is called before an IdentityStore with a higher priority value.</description>      			    
			<location chapter="3" section="2.3"/>    
		</assertion>
		<assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
			<id>Security:SPEC:3.2.3-2</id>
			<description>The validationTypes() method returns a Set of enum constants of type ValidationType, indicating the purposes for which an IdentityStore should be used</description>      			    
			<location chapter="3" section="2.3"/>    
		</assertion>
		<assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
			<id>Security:SPEC:3.2.4-1</id>
			<description>The purpose of the IdentityStoreHandler is to allow for multiple identity stores to logically act as a
single IdentityStore to the HttpAuthenticationMechanism.</description>      			   
			<location chapter="3" section="2.4"/>    
		</assertion>
			<assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
			<id>Security:SPEC:3.2.4-2</id>
			<description>A compliant implementation of this specification MUST provide a default implementation of the IdentityStoreHandler that is an enabled CDI bean with qualifier @Default, and scope @ApplicationScoped, as defined by the CDI specification.</description>      			    
			<location chapter="3" section="2.4"/>    
		</assertion>
		<assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
			<id>Security:SPEC:3.2.4-3</id>
			<description>If a call to validate() returns a result with status INVALID, remember it, in case no IdentityStore returns a VALID result.</description>      			    
			<location chapter="3" section="2.4"/>    
		</assertion>
		<assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
			<id>Security:SPEC:3.2.4-4</id>
			<description>If a call to validate() returns a result with status VALID, remember this result and stop calling validate().</description>      			    
			<location chapter="3" section="2.4"/>    
		</assertion>
		<assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
			<id>Security:SPEC:3.2.4-5</id>
			<description>If a result was previously returned with status INVALID, return that result.</description>      			   
			<location chapter="3" section="2.4"/>    
		</assertion>
			<assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
			<id>Security:SPEC:3.2.4-6</id>
			<description>Otherwise, return a result with status NOT_VALIDATED.</description>      			    
			<location chapter="3" section="2.4"/>    
		</assertion>
		<assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
			<id>Security:SPEC:3.2.4-7</id>
			<description>Add any groups returned in the CredentialValidationResult to the set of groups, if and only if the identity store that returned the VALID result declared the PROVIDE_GROUPS validation type.</description>      			    
			<location chapter="3" section="2.4"/>    
		</assertion>
		<assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
			<id>Security:SPEC:3.2.4-8</id>
			<description>Call the getCallerGroups() method on all available IdentityStore beans that declared only the PROVIDE_GROUPS validation type, in the order induced by the return value of the getPriority() method of each IdentityStore, passing in the CredentialValidationResult obtained during the previous phase. Add the groups returned by each call to the set of accumulated groups.</description>      			    
			<location chapter="3" section="2.4"/>    
		</assertion>
		<assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
			<id>Security:SPEC:3.3-1</id>
			<description>Installation of an IdentityStore depends on the CDI specification. That is, an IdentityStore is considered installed and available for usage when it’s available to the CDI runtime as an enabled Bean. An IdentityStore is assumed to be normal scoped.</description>      			   
			<location chapter="3" section="3"/>    
		</assertion>
			<assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
			<id>Security:SPEC:3.3-2</id>
			<description>It MUST be possible for the definition of an IdentityStore to exist within the application archive.</description>      			    
			<location chapter="3" section="3"/>    
		</assertion>
		<assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
			<id>Security:SPEC:3.4-1</id>
			<description>LDAP—Supports caller data that is stored in an external LDAP server. This bean is activated and
configured via the @LdapIdentityStoreDefinition
annotation</description>      			    
			<location chapter="3" section="4"/>    
		</assertion>
		<assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
			<id>Security:SPEC:3.4-2</id>
			<description>Database — Supports caller data that is stored in an external database accessible via a DataSource bound to JNDI. This bean is activated and configured via the @DataBaseIdentityStoreDefinition annotation.</description>      			    
			<location chapter="3" section="4"/>    
		</assertion>
		<assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
			<id>Security:SPEC:3.4-3</id>
			<description>Each of these beans MUST have the qualifier @Default and the scope @ApplicationScoped, as defined by the CDI specification.</description>      			    
			<location chapter="3" section="4"/>    
		</assertion>
		<assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
			<id>Security:SPEC:4.2-1</id>
			<description>The getCallerPrincipal() method retrieves the Principal representing the caller.</description>      			   
			<location chapter="3" section="2"/>    
		</assertion>
			<assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
			<id>Security:SPEC:4.2-2</id>
			<description>The isCallerInRole() method takes a String argument that represents the role that is to be tested for. It is undefined by this specification how the role determination is made, but the result MUST be the same as if the corresponding container-specific call had been made (i.e., HttpServletRequest.isUserInRole(), EJBContext.isCallerInRole()),</description>      			    
			<location chapter="4" section="2"/>    
		</assertion>
		<assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
			<id>Security:SPEC:4.3-1</id>
			<description>The hasAccessToWebResource() method determines if the caller has access to the specified web resource for the specified HTTP methods, as determined by the security constraints configured for the application. </description>      			    
			<location chapter="4" section="3"/>    
		</assertion>
		<assertion required="true" impl-spec="false" defined-by="technology" status="active" testable="true">
			<id>Security:SPEC:4.4-1</id>
			<description>The authenticate() method allows an application to signal to the container that it should start the authentication process with the caller. </description>      			    
			<location chapter="4" section="4"/>    
		</assertion>
	</assertions>
</spec>
