Updates related to principal handling

Author: wmhopkins

src/main/doc/authenticationMechanism.asciidoc

@@ -202,7 +202,11 @@ The _secureResponse()_ method is provided to allow post processing on the respon
 
 The _cleanSubject()_ is provided to allow for cleanup after a caller is logged out. For example, an authentication mechanism that stores state within a cookie can remove that cookie here.
 
-The _HttpMessageContext_ interface defines methods that an _HttpAuthenticationMechanism_ can invoke to communicate with the JASPIC _ServerAuthModule_ (bridge module) that invokes it. The _HttpMessageContextWrapper_ provides an implementation of the interface, and can be used, in a manner similar to _HttpServletRequestWrapper_, to provide custom behavior. See javadoc for a detailed description of _HttpMessageContext_ and _HttpMessageContextWrapper_. See below for more on the JASPIC bridge module.
+The _HttpMessageContext_ interface defines methods that an _HttpAuthenticationMechanism_ can invoke to communicate with the JASPIC _ServerAuthModule_ (bridge module) that invokes it. The container MUST provide an implementation of the interface that supports the necessary container integrations.
+
+The _HttpMessageContextWrapper_ class implements a wrapper can be used, in a manner similar to _HttpServletRequestWrapper_, to provide custom behavior.
+
+See javadoc for a detailed description of _HttpMessageContext_ and _HttpMessageContextWrapper_. See below for more on the JASPIC bridge module.
 
 === Installation and Configuration
 

src/main/doc/concepts.asciidoc

@@ -184,3 +184,15 @@ An application server MAY provide a default mapping from caller principal names
 This specification defines a principal type called _CallerPrincipal_ to represent the identity of an application caller. Historically, application servers have used different principal types to represent an application's callers, and various Java EE specifications (e.g., JASPIC), provide abstractions to accomodate, "the container's representation of the caller principal".
 
 This specification RECOMMENDS that Java EE application servers that rely on container-specific caller principal types derive those types by extending _CallerPrincipal_, so that portable applications can rely on a consistent representation of the caller principal.
+
+However, we also distinguish here between a "container caller principal" and an "application caller principal", and explicitly allow for each to be represented by a different _Principal_ type.
+
+The container caller principal is a _Principal_ that the container uses to represent a caller's identity. An implementation of this specification MAY choose any _Principal_ type for this purpose. The type chosen may carry additional information, or provide unique behaviors.
+
+An application caller principal is a _Principal_ that an application, or an implementation of, e.g., an _HttpAuthenticationMechanism_, uses to represent a caller's identity. An application MAY choose any _Principal_ type for that purpose. The type chosen may carry additional information, or provide unique behaviors.
+
+Because both containers and applications can have legitimate requirements for specific _Principal_ types to represent a caller, and those types may differ, it MUST be possible for the container to establish both the container's and the application's caller principal as the caller's identity; for example, by including both in a Subject representing the caller.
+
+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.

src/main/doc/license.asciidoc

@@ -157,8 +157,7 @@ Status: Public Review +
 Release: May 2017
 
 Copyright 2017 Oracle America, Inc. +
-500 Oracle Parkway, Redwood City, California 94065, U.S.A.
-
+500 Oracle Parkway, Redwood City, California 94065, U.S.A. +
 All rights reserved.
 
 NOTICE +

src/main/doc/securityContext.asciidoc

@@ -161,10 +161,19 @@ The _SecurityContext_ interface defines two methods that allow the application t
 ----
 Principal getCallerPrincipal();
 
+<T extends Principal>
+Set<T> getPrincipalsByType(Class<T> pType);
+
 boolean isCallerInRole(String role);
 ----
 
-The _getCallerPrincipal()_ method retrieves the _Principal_ representing the caller. 
+The _getCallerPrincipal()_ method retrieves the _Principal_ representing the caller. This is the container-specific representation of the caller principal, and the type may differ from the type of the caller principal originally established by an _HttpAuthenticationMechanism_. This method returns null for an unauthenticated caller. (Note that this behavior differs from the behavior of _EJBContext.getCallerPrincipal()_, which returns a principal with an null/empty name for an unauthenticated caller.)
+
+The _getPrincipalsByType()_ method retrieves all principals of the given type. This method can be used to retrieve an application-specific caller principal established during authentication. This method is primarily useful in the case that the container's caller principal is a different type than the application caller principal, and the application needs specific information behavior available only from the application principal. This method returns an empty _Set_ if the caller is unauthenticated, or if the requested type is not found.
+
+Where both a container caller principal and an application caller principal are present, the value returned by _getName()_ MUST be the same for both principals.
+
+See the <<concepts.asciidoc#concepts,Concepts>> chapter for more information on principal handling.
 
 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()_), and MUST be consistent with the result implied by other specifications that prescribe role-mapping behavior.