Updates to add/update content and improve structure and formatting

Author: wmhopkins

src/main/doc/authenticationMechanism.asciidoc

@@ -0,0 +1,185 @@
+////
+//
+// ORACLE AMERICA, INC. IS WILLING TO LICENSE THIS SPECIFICATION TO YOU ONLY UPON THE
+// CONDITION THAT YOU ACCEPT ALL OF THE TERMS CONTAINED IN THIS LICENSE AGREEMENT
+// ("AGREEMENT"). PLEASE READ THE TERMS AND CONDITIONS OF THIS AGREEMENT CAREFULLY. BY
+// DOWNLOADING THIS SPECIFICATION, YOU ACCEPT THE TERMS AND CONDITIONS OF THIS AGREEMENT.
+// IF YOU ARE NOT WILLING TO BE BOUND BY THEM, SELECT THE "DECLINE" BUTTON AT THE BOTTOM OF
+// THIS PAGE AND THE DOWNLOADING PROCESS WILL NOT CONTINUE.
+// 
+// Specification: JSR-375 Java EE Security API ("Specification")
+// Version: 1.0
+// Status: Proposed Final Draft
+// Release: July 2017
+// 
+// Copyright 2017 Oracle America, Inc.
+// 500 Oracle Parkway, Redwood City, California 94065, U.S.A.
+// 
+// All rights reserved.
+// 
+// NOTICE
+// The Specification is protected by copyright and the information described therein may be protected by
+// one or more U.S. patents, foreign patents, or pending applications. Except as provided under the
+// following license, no part of the Specification may be reproduced in any form by any means without the
+// prior written authorization of Oracle America, Inc. ("Oracle") and its licensors, if any. Any use of the
+// Specification and the information described therein will be governed by the terms and conditions of this
+// Agreement.
+// 
+// Subject to the terms and conditions of this license, including your compliance with Paragraphs 1 and 2
+// below, Oracle hereby grants you a fully-paid, non-exclusive, non-transferable, limited license (without
+// the right to sublicense) under Oracle's intellectual property rights to:
+// 
+// 1.Review the Specification for the purposes of evaluation. This includes: (i) developing implementations
+// of the Specification for your internal, non-commercial use; (ii) discussing the Specification with any third
+// party; and (iii) excerpting brief portions of the Specification in oral or written communications which
+// discuss the Specification provided that such excerpts do not in the aggregate constitute a significant
+// portion of the Technology.
+// 
+// 2.Distribute implementations of the Specification to third parties for their testing and evaluation use,
+// provided that any such implementation:
+// (i) does not modify, subset, superset or otherwise extend the Licensor Name Space, or include any
+// public or protected packages, classes, Java interfaces, fields or methods within the Licensor Name Space
+// other than those required/authorized by the Specification or Specifications being implemented;
+// (ii) is clearly and prominently marked with the word "UNTESTED" or "EARLY ACCESS" or
+// "INCOMPATIBLE" or "UNSTABLE" or "BETA" in any list of available builds and in proximity to every link
+// initiating its download, where the list or link is under Licensee's control; and
+// (iii) includes the following notice:
+// "This is an implementation of an early-draft specification developed under the Java Community Process
+// (JCP) and is made available for testing and evaluation purposes only. The code is not compatible with
+// any specification of the JCP."
+// 
+// The grant set forth above concerning your distribution of implementations of the specification is
+// contingent upon your agreement to terminate development and distribution of your "early draft"
+// implementation as soon as feasible following final completion of the specification. If you fail to do so,
+// the foregoing grant shall be considered null and void.
+// 
+// No provision of this Agreement shall be understood to restrict your ability to make and distribute to
+// third parties applications written to the Specification.
+// 
+// Other than this limited license, you acquire no right, title or interest in or to the Specification or any
+// other Oracle intellectual property, and the Specification may only be used in accordance with the license
+// terms set forth herein. This license will expire on the earlier of: (a) two (2) years from the date of
+// Release listed above; (b) the date on which the final version of the Specification is publicly released; or
+// (c) the date on which the Java Specification Request (JSR) to which the Specification corresponds is
+// withdrawn. In addition, this license will terminate immediately without notice from Oracle if you fail to
+// comply with any provision of this license. Upon termination, you must cease use of or destroy the
+// Specification.
+// 
+// "Licensor Name Space" means the public class or interface declarations whose names begin with "java",
+// "javax", "com.oracle" or their equivalents in any subsequent naming convention adopted by Oracle
+// through the Java Community Process, or any recognized successors or replacements thereof
+// 
+// TRADEMARKS
+// No right, title, or interest in or to any trademarks, service marks, or trade names of Oracle or Oracle's
+// licensors is granted hereunder. Oracle, the Oracle logo, and Java are trademarks or registered
+// trademarks of Oracle America, Inc. in the U.S. and other countries.
+// 
+// DISCLAIMER OF WARRANTIES
+// THE SPECIFICATION IS PROVIDED "AS IS" AND IS EXPERIMENTAL AND MAY CONTAIN DEFECTS OR
+// DEFICIENCIES WHICH CANNOT OR WILL NOT BE CORRECTED BY ORACLE. ORACLE MAKES NO
+// REPRESENTATIONS OR WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO,
+// WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT
+// THAT THE CONTENTS OF THE SPECIFICATION ARE SUITABLE FOR ANY PURPOSE OR THAT ANY PRACTICE
+// OR IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS,
+// COPYRIGHTS, TRADE SECRETS OR OTHER RIGHTS. This document does not represent any commitment to
+// release or implement any portion of the Specification in any product.
+// 
+// THE SPECIFICATION COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES
+// ARE PERIODICALLY ADDED TO THE INFORMATION THEREIN; THESE CHANGES WILL BE INCORPORATED
+// INTO NEW VERSIONS OF THE SPECIFICATION, IF ANY. ORACLE MAY MAKE IMPROVEMENTS AND/OR
+// CHANGES TO THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THE SPECIFICATION AT ANY
+// TIME. Any use of such changes in the Specification will be governed by the then-current license for the
+// applicable version of the Specification.
+// 
+// LIMITATION OF LIABILITY
+// TO THE EXTENT NOT PROHIBITED BY LAW, IN NO EVENT WILL ORACLE OR ITS LICENSORS BE LIABLE FOR
+// ANY DAMAGES, INCLUDING WITHOUT LIMITATION, LOST REVENUE, PROFITS OR DATA, OR FOR SPECIAL,
+// INDIRECT, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND REGARDLESS
+// OF THE THEORY OF LIABILITY, ARISING OUT OF OR RELATED TO ANY FURNISHING, PRACTICING,
+// MODIFYING OR ANY USE OF THE SPECIFICATION, EVEN IF ORACLE AND/OR ITS LICENSORS HAVE BEEN
+// ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+// 
+// You will hold Oracle (and its licensors) harmless from any claims based on your use of the Specification
+// for any purposes other than the limited right of evaluation as described above, and from any claims that
+// later versions or releases of any Specification furnished to you are incompatible with the Specification
+// provided to you under this license.
+// 
+// RESTRICTED RIGHTS LEGEND
+// If this Software is being acquired by or on behalf of the U.S. Government or by a U.S. Government prime
+// contractor or subcontractor (at any tier), then the Government's rights in the Software and
+// accompanying documentation shall be only as set forth in this license; this is in accordance with 48
+// C.F.R. 227.7201 through 227.7202-4 (for Department of Defense (DoD) acquisitions) and with 48 C.F.R.
+// 2.101 and 12.212 (for non-DoD acquisitions).
+// 
+// REPORT
+// You may wish to report any ambiguities, inconsistencies or inaccuracies you may find in connection with
+// your evaluation of the Specification ("Feedback"). To the extent that you provide Oracle with any
+// Feedback, you hereby: (i) agree that such Feedback is provided on a non-proprietary and non-
+// confidential basis, and (ii) grant Oracle a perpetual, non-exclusive, worldwide, fully paid-up, irrevocable
+// license, with the right to sublicense through multiple levels of sublicensees, to incorporate, disclose, and
+// use without limitation the Feedback for any purpose related to the Specification and future versions,
+// implementations, and test suites thereof.
+// 
+// GENERAL TERMS
+// Any action related to this Agreement will be governed by California law and controlling U.S. federal law.
+// The U.N. Convention for the International Sale of Goods and the choice of law rules of any jurisdiction
+// will not apply.
+// 
+// The Specification is subject to U.S. export control laws and may be subject to export or import
+// regulations in other countries. Licensee agrees to comply strictly with all such laws and regulations and
+// acknowledges that it has the responsibility to obtain such licenses to export, re-export or import as may
+// be required after delivery to Licensee.
+// 
+// This Agreement is the parties' entire agreement relating to its subject matter. It supersedes all prior or
+// contemporaneous oral or written communications, proposals, conditions, representations and
+// warranties and prevails over any conflicting or additional terms of any quote, order, acknowledgment,
+// or other communication between the parties relating to its subject matter during the term of this
+// Agreement. No modification to this Agreement will be binding, unless in writing and signed by an
+// authorized representative of each party.
+//
+////
+
+:numbered!:
+["bibliography",sectnum="0"]
+
+== Bibliography
+
+The following documents are referenced by this specification.
+
+[CDI12]::
+JSR-346, "Contexts and Dependency Injection for the Java EE platform", version 1.2, Maintenance Release +
+https://jcp.org/aboutJava/communityprocess/mrel/jsr346/index.html
+
+[EL30]::
+JSR-341, "Expression Language", version 3.0 +
+https://jcp.org/aboutJava/communityprocess/final/jsr341/index.html
+
+[JACC]::
+JSR-115, "Java Authorization Contract for Containers", version 1.5, Maintenance Release 3 +
+https://jcp.org/aboutJava/communityprocess/mrel/jsr115/index3.html
+
+[JASPIC]::
+JSR-196, "Java Authentication SPI for Containers", version 1.0, Maintenance Release 2 +
+https://jcp.org/aboutJava/communityprocess/mrel/jsr196/index2.html
+
+[RFC2119]::
+RFC 2119, "Key words for use in RFCs to Indicate Requirement Level" +
+https://tools.ietf.org/html/rfc2119
+
+[RFC7617]::
+RFC 7617, "The 'Basic' HTTP Authentication Scheme" +
+https://tools.ietf.org/html/rfc7617
+
+[SECAPI]::
+JSR-375, "Java EE Security API", version 1.0 +
+https://jcp.org/en/jsr/detail?id=375
+
+[SERVLET31]::
+JSR-340, "Java Servlet Specification", version 3.1 +
+https://jcp.org/aboutJava/communityprocess/final/jsr340/index.html
+
+[SHIROTERM]::
+"Apache Shiro Terminology" +
+https://shiro.apache.org/terminology.html
+
+:numbered:

src/main/doc/bibliography.asciidoc

@@ -147,7 +147,7 @@ This chapter overview information and terminology related to this specification,
 
 === Terminology And Acronyms
 
-A common understanding of security-related terms is helpful for discussion or specification of security APIs. To that end, we incorporate by reference the excellent https://shiro.apache.org/terminology.html[Apache Shiro Terminology], and define some additional terms used in this document.
+A common understanding of security-related terms is helpful for discussion or specification of security APIs. To that end, we incorporate by reference the excellent Apache Shiro Terminology [https://shiro.apache.org/terminology.html[SHIROTERM]], and define some additional terms used in this document.
 
 Authentication Mechanism ::
 The mechanism by which authentication is performed. This mechanism interacts with the caller to obtain credentials and invokes an identity store to match the given credentials with a known user (identity). If a match is found, the Authentication Mechanism uses the found identity to populate attributes (principals) to build an authenticated Subject. If a match is not found, the Authentication Mechanism reports a failed authentication, the caller is not logged in, and is unable to be given authorization.
@@ -161,8 +161,11 @@ Abbreviation for _HttpAuthenticationMechanism_, an interface defined by this spe
 Identity Store::
 An Identity Store is a component that can access application-specific security data such as users, groups, roles, and permissions. It can be thought of as a security-specific DAO (Data Access Object). Synonyms: security provider, repository, store, login module (JAAS), identity manager, service provider, relying party, authenticator, user service. Identity Stores usually have a 1-to-1 correlation with a data source such as a relational database, LDAP directory, file system, or other similar resource. As such, implementations of the _IdentityStore_ interface use data source-specific APIs to discover authorization data (roles, permissions, etc), such as JDBC, File IO, Hibernate or JPA, or any other Data Access API.
 
+JACC::
+JSR-115, "Java Authorization Contract for Containers", version 1.5 [https://jcp.org/aboutJava/communityprocess/mrel/jsr115/index3.html[JACC]].
+
 JASPIC::
-The Java Authentication SPI for Containers (JSR-196).
+JSR-196, "Java Authentication SPI for Containers", version 1.0 [https://jcp.org/aboutJava/communityprocess/mrel/jsr196/index2.html[JASPIC]].
 
 SAM::
 Abbreviation for _ServerAuthModule_, an interface defined by JASPIC.
@@ -196,3 +199,26 @@ Because both containers and applications can have legitimate requirements for sp
 When both a container caller principal and an application caller principal are present, the value obtained by calling _getName()_ on both principals MUST be the same.
 
 When no specific application caller principal is supplied during authentication, the caller's identity should be represented by a single principal, the container's caller principal.
+
+==== Expression Language Support
+
+This specification defines a number of annotations:
+
+[source,java]
+----
+DatabaseIdentityStoreDefinition
+LdapIdentityStoreDefinition
+
+BasicAuthenticationMechanismDefinition
+CustomFormAuthenticationMechanismDefinition
+FormAuthenticationMechanismDefinition
+
+LoginToContinue
+RememberMe
+----
+
+Attributes on these annotations can be provided either as actual values, or as Expression Language 3.0 expressions. In cases where the return type of an attribute is not String, an "EL alternative" attribute is provided, with "Expression" appended to the name. If an "EL alternative" attribute has a non-empty value, it takes precedence over the attribute it's an alternative to, and must contain a valid EL expression that evaluates to the same type as the attribute it's an alternative to.
+
+For more information, see the package javadoc for the javax.security.enterprise package.
+ 
+Expression Language 3.0 is specified by JSR-341, "Expression Language", version 3.0 [https://jcp.org/aboutJava/communityprocess/final/jsr341/index.html[EL30]]