Google Git
Sign in
apache / tomee-site-pub / 294f8729efbe13f29a64f7a60a72b67641434a45 / . / tomee-8.0 / javadoc / javax / security / enterprise / authentication / mechanism / http / HttpAuthenticationMechanism.html
blob: 4fa58830b3f5302f5cfe5c3e97a96639f02f2aea [file] [log] [blame]
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!-- NewPage -->
<html lang="en">
<head>
<title>HttpAuthenticationMechanism</title>
<link rel="stylesheet" type="text/css" href="../../../../../../stylesheet.css" title="Style">
<script type="text/javascript" src="../../../../../../script.js"></script>
</head>
<body>
<script type="text/javascript"><!--
try {
if (location.href.indexOf('is-external=true') == -1) {
parent.document.title="HttpAuthenticationMechanism";
}
}
catch(err) {
}
//-->
var methods = {"i0":18,"i1":18,"i2":6};
var tabs = {65535:["t0","All Methods"],2:["t2","Instance Methods"],4:["t3","Abstract Methods"],16:["t5","Default Methods"]};
var altColor = "altColor";
var rowColor = "rowColor";
var tableTab = "tableTab";
var activeTableTab = "activeTableTab";
</script>
<noscript>
<div>JavaScript is disabled on your browser.</div>
</noscript>
<!-- ========= START OF TOP NAVBAR ======= -->
<div class="topNav"><a name="navbar.top">
<!-- -->
</a>
<div class="skipNav"><a href="#skip.navbar.top" title="Skip navigation links">Skip navigation links</a></div>
<a name="navbar.top.firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li><a href="../../../../../../overview-summary.html">Overview</a></li>
<li><a href="package-summary.html">Package</a></li>
<li class="navBarCell1Rev">Class</li>
<li><a href="package-tree.html">Tree</a></li>
<li><a href="../../../../../../deprecated-list.html">Deprecated</a></li>
<li><a href="../../../../../../index-all.html">Index</a></li>
<li><a href="../../../../../../help-doc.html">Help</a></li>
</ul>
</div>
<div class="subNav">
<ul class="navList">
<li><a href="../../../../../../javax/security/enterprise/authentication/mechanism/http/FormAuthenticationMechanismDefinition.html" title="annotation in javax.security.enterprise.authentication.mechanism.http"><span class="typeNameLink">Prev&nbsp;Class</span></a></li>
<li><a href="../../../../../../javax/security/enterprise/authentication/mechanism/http/HttpAuthenticationMechanismWrapper.html" title="class in javax.security.enterprise.authentication.mechanism.http"><span class="typeNameLink">Next&nbsp;Class</span></a></li>
</ul>
<ul class="navList">
<li><a href="../../../../../../index.html?javax/security/enterprise/authentication/mechanism/http/HttpAuthenticationMechanism.html" target="_top">Frames</a></li>
<li><a href="HttpAuthenticationMechanism.html" target="_top">No&nbsp;Frames</a></li>
</ul>
<ul class="navList" id="allclasses_navbar_top">
<li><a href="../../../../../../allclasses-noframe.html">All&nbsp;Classes</a></li>
</ul>
<div>
<script type="text/javascript"><!--
allClassesLink = document.getElementById("allclasses_navbar_top");
if(window==top) {
allClassesLink.style.display = "block";
}
else {
allClassesLink.style.display = "none";
}
//-->
</script>
</div>
<div>
<ul class="subNavList">
<li>Summary:&nbsp;</li>
<li>Nested&nbsp;|&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li>Constr&nbsp;|&nbsp;</li>
<li><a href="#method.summary">Method</a></li>
</ul>
<ul class="subNavList">
<li>Detail:&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li>Constr&nbsp;|&nbsp;</li>
<li><a href="#method.detail">Method</a></li>
</ul>
</div>
<a name="skip.navbar.top">
<!-- -->
</a></div>
<!-- ========= END OF TOP NAVBAR ========= -->
<!-- ======== START OF CLASS DATA ======== -->
<div class="header">
<div class="subTitle">javax.security.enterprise.authentication.mechanism.http</div>
<h2 title="Interface HttpAuthenticationMechanism" class="title">Interface HttpAuthenticationMechanism</h2>
</div>
<div class="contentContainer">
<div class="description">
<ul class="blockList">
<li class="blockList">
<dl>
<dt>All Known Implementing Classes:</dt>
<dd><a href="../../../../../../org/apache/tomee/security/cdi/BasicAuthenticationMechanism.html" title="class in org.apache.tomee.security.cdi">BasicAuthenticationMechanism</a>, <a href="../../../../../../org/apache/tomee/security/cdi/DefaultAuthenticationMechanism.html" title="class in org.apache.tomee.security.cdi">DefaultAuthenticationMechanism</a>, <a href="../../../../../../org/apache/tomee/security/cdi/FormAuthenticationMechanism.html" title="class in org.apache.tomee.security.cdi">FormAuthenticationMechanism</a>, <a href="../../../../../../javax/security/enterprise/authentication/mechanism/http/HttpAuthenticationMechanismWrapper.html" title="class in javax.security.enterprise.authentication.mechanism.http">HttpAuthenticationMechanismWrapper</a></dd>
</dl>
<hr>
<br>
<pre>public interface <span class="typeNameLabel">HttpAuthenticationMechanism</span></pre>
<div class="block"><code>HttpAuthenticationMechanism</code> is a mechanism for obtaining a caller's
credentials in some way, using the HTTP protocol where necessary.
<p>
This is used to help in securing Servlet endpoints, including
endpoints that may be build on top of Servlet like JAX-RS endpoints and JSF views.
It specifically <b>is not</b> used for endpoints such as remote EJB beans or (JMS) message driven beans.
<p>
A <code>HttpAuthenticationMechanism</code> is essentially a Servlet specific and CDI enabled version of
the <code>ServerAuthModule</code> that adheres to the Servlet Container Profile. See the JASPIC spec for further
details on this.
<p>
Implementations of this class can notify the Servlet container about a successful authentication by using the
<a href="../../../../../../javax/security/enterprise/authentication/mechanism/http/HttpMessageContext.html#notifyContainerAboutLogin-java.security.Principal-java.util.Set-"><code>HttpMessageContext.notifyContainerAboutLogin(java.security.Principal, java.util.Set)</code></a> method.
<p>
Implementations are expected and encouraged to delegate the actual credential validation and/or retrieval of the
caller name with optional groups to an <a href="../../../../../../javax/security/enterprise/identitystore/IdentityStore.html" title="interface in javax.security.enterprise.identitystore"><code>IdentityStore</code></a>. This is however <b>not</b> required and implementations
can either do the validation checks for authentication completely autonomously, or delegate only certain aspects of
the process to the store (e.g. use the store only for retrieving the groups an authenticated user is in).</div>
</li>
</ul>
</div>
<div class="summary">
<ul class="blockList">
<li class="blockList">
<!-- ========== METHOD SUMMARY =========== -->
<ul class="blockList">
<li class="blockList"><a name="method.summary">
<!-- -->
</a>
<h3>Method Summary</h3>
<table class="memberSummary" border="0" cellpadding="3" cellspacing="0" summary="Method Summary table, listing methods, and an explanation">
<caption><span id="t0" class="activeTableTab"><span>All Methods</span><span class="tabEnd">&nbsp;</span></span><span id="t2" class="tableTab"><span><a href="javascript:show(2);">Instance Methods</a></span><span class="tabEnd">&nbsp;</span></span><span id="t3" class="tableTab"><span><a href="javascript:show(4);">Abstract Methods</a></span><span class="tabEnd">&nbsp;</span></span><span id="t5" class="tableTab"><span><a href="javascript:show(16);">Default Methods</a></span><span class="tabEnd">&nbsp;</span></span></caption>
<tr>
<th class="colFirst" scope="col">Modifier and Type</th>
<th class="colLast" scope="col">Method and Description</th>
</tr>
<tr id="i0" class="altColor">
<td class="colFirst"><code>default void</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../../../javax/security/enterprise/authentication/mechanism/http/HttpAuthenticationMechanism.html#cleanSubject-javax.servlet.http.HttpServletRequest-javax.servlet.http.HttpServletResponse-javax.security.enterprise.authentication.mechanism.http.HttpMessageContext-">cleanSubject</a></span>(<a href="../../../../../../javax/servlet/http/HttpServletRequest.html" title="interface in javax.servlet.http">HttpServletRequest</a>&nbsp;request,
<a href="../../../../../../javax/servlet/http/HttpServletResponse.html" title="interface in javax.servlet.http">HttpServletResponse</a>&nbsp;response,
<a href="../../../../../../javax/security/enterprise/authentication/mechanism/http/HttpMessageContext.html" title="interface in javax.security.enterprise.authentication.mechanism.http">HttpMessageContext</a>&nbsp;httpMessageContext)</code>
<div class="block">Remove mechanism specific principals and credentials from the subject and any other state the mechanism
might have used.</div>
</td>
</tr>
<tr id="i1" class="rowColor">
<td class="colFirst"><code>default <a href="../../../../../../javax/security/enterprise/AuthenticationStatus.html" title="enum in javax.security.enterprise">AuthenticationStatus</a></code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../../../javax/security/enterprise/authentication/mechanism/http/HttpAuthenticationMechanism.html#secureResponse-javax.servlet.http.HttpServletRequest-javax.servlet.http.HttpServletResponse-javax.security.enterprise.authentication.mechanism.http.HttpMessageContext-">secureResponse</a></span>(<a href="../../../../../../javax/servlet/http/HttpServletRequest.html" title="interface in javax.servlet.http">HttpServletRequest</a>&nbsp;request,
<a href="../../../../../../javax/servlet/http/HttpServletResponse.html" title="interface in javax.servlet.http">HttpServletResponse</a>&nbsp;response,
<a href="../../../../../../javax/security/enterprise/authentication/mechanism/http/HttpMessageContext.html" title="interface in javax.security.enterprise.authentication.mechanism.http">HttpMessageContext</a>&nbsp;httpMessageContext)</code>
<div class="block">Secure the response, optionally.</div>
</td>
</tr>
<tr id="i2" class="altColor">
<td class="colFirst"><code><a href="../../../../../../javax/security/enterprise/AuthenticationStatus.html" title="enum in javax.security.enterprise">AuthenticationStatus</a></code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../../../javax/security/enterprise/authentication/mechanism/http/HttpAuthenticationMechanism.html#validateRequest-javax.servlet.http.HttpServletRequest-javax.servlet.http.HttpServletResponse-javax.security.enterprise.authentication.mechanism.http.HttpMessageContext-">validateRequest</a></span>(<a href="../../../../../../javax/servlet/http/HttpServletRequest.html" title="interface in javax.servlet.http">HttpServletRequest</a>&nbsp;request,
<a href="../../../../../../javax/servlet/http/HttpServletResponse.html" title="interface in javax.servlet.http">HttpServletResponse</a>&nbsp;response,
<a href="../../../../../../javax/security/enterprise/authentication/mechanism/http/HttpMessageContext.html" title="interface in javax.security.enterprise.authentication.mechanism.http">HttpMessageContext</a>&nbsp;httpMessageContext)</code>
<div class="block">Authenticate an HTTP request.</div>
</td>
</tr>
</table>
</li>
</ul>
</li>
</ul>
</div>
<div class="details">
<ul class="blockList">
<li class="blockList">
<!-- ============ METHOD DETAIL ========== -->
<ul class="blockList">
<li class="blockList"><a name="method.detail">
<!-- -->
</a>
<h3>Method Detail</h3>
<a name="validateRequest-javax.servlet.http.HttpServletRequest-javax.servlet.http.HttpServletResponse-javax.security.enterprise.authentication.mechanism.http.HttpMessageContext-">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>validateRequest</h4>
<pre><a href="../../../../../../javax/security/enterprise/AuthenticationStatus.html" title="enum in javax.security.enterprise">AuthenticationStatus</a>&nbsp;validateRequest(<a href="../../../../../../javax/servlet/http/HttpServletRequest.html" title="interface in javax.servlet.http">HttpServletRequest</a>&nbsp;request,
<a href="../../../../../../javax/servlet/http/HttpServletResponse.html" title="interface in javax.servlet.http">HttpServletResponse</a>&nbsp;response,
<a href="../../../../../../javax/security/enterprise/authentication/mechanism/http/HttpMessageContext.html" title="interface in javax.security.enterprise.authentication.mechanism.http">HttpMessageContext</a>&nbsp;httpMessageContext)
throws <a href="../../../../../../javax/security/enterprise/AuthenticationException.html" title="class in javax.security.enterprise">AuthenticationException</a></pre>
<div class="block">Authenticate an HTTP request.
<p>
This method is called in response to an HTTP client request for a resource, and is always invoked
<strong>before</strong> any <a href="../../../../../../javax/servlet/Filter.html" title="interface in javax.servlet"><code>Filter</code></a> or <a href="../../../../../../javax/servlet/http/HttpServlet.html" title="class in javax.servlet.http"><code>HttpServlet</code></a>. Additionally this method is called
in response to <a href="../../../../../../javax/servlet/http/HttpServletRequest.html#authenticate-javax.servlet.http.HttpServletResponse-"><code>HttpServletRequest.authenticate(HttpServletResponse)</code></a>
<p>
Note that by default this method is <strong>always</strong> called for every request, independent of whether
the request is to a protected or non-protected resource, or whether a caller was successfully authenticated
before within the same HTTP session or not.
<p>
A CDI/Interceptor spec interceptor can be used to prevent calls to this method if needed.
See <a href="../../../../../../javax/security/enterprise/authentication/mechanism/http/AutoApplySession.html" title="annotation in javax.security.enterprise.authentication.mechanism.http"><code>AutoApplySession</code></a> and <a href="../../../../../../javax/security/enterprise/authentication/mechanism/http/RememberMe.html" title="annotation in javax.security.enterprise.authentication.mechanism.http"><code>RememberMe</code></a> for two examples.</div>
<dl>
<dt><span class="paramLabel">Parameters:</span></dt>
<dd><code>request</code> - contains the request the client has made</dd>
<dd><code>response</code> - contains the response that will be send to the client</dd>
<dd><code>httpMessageContext</code> - context for interacting with the container</dd>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>the completion status of the processing performed by this method</dd>
<dt><span class="throwsLabel">Throws:</span></dt>
<dd><code><a href="../../../../../../javax/security/enterprise/AuthenticationException.html" title="class in javax.security.enterprise">AuthenticationException</a></code> - when the processing failed</dd>
</dl>
</li>
</ul>
<a name="secureResponse-javax.servlet.http.HttpServletRequest-javax.servlet.http.HttpServletResponse-javax.security.enterprise.authentication.mechanism.http.HttpMessageContext-">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>secureResponse</h4>
<pre>default&nbsp;<a href="../../../../../../javax/security/enterprise/AuthenticationStatus.html" title="enum in javax.security.enterprise">AuthenticationStatus</a>&nbsp;secureResponse(<a href="../../../../../../javax/servlet/http/HttpServletRequest.html" title="interface in javax.servlet.http">HttpServletRequest</a>&nbsp;request,
<a href="../../../../../../javax/servlet/http/HttpServletResponse.html" title="interface in javax.servlet.http">HttpServletResponse</a>&nbsp;response,
<a href="../../../../../../javax/security/enterprise/authentication/mechanism/http/HttpMessageContext.html" title="interface in javax.security.enterprise.authentication.mechanism.http">HttpMessageContext</a>&nbsp;httpMessageContext)
throws <a href="../../../../../../javax/security/enterprise/AuthenticationException.html" title="class in javax.security.enterprise">AuthenticationException</a></pre>
<div class="block">Secure the response, optionally.
<p>
This method is called to allow for any post processing to be done on the request, and is always invoked
<strong>after</strong> any <a href="../../../../../../javax/servlet/Filter.html" title="interface in javax.servlet"><code>Filter</code></a> or <a href="../../../../../../javax/servlet/http/HttpServlet.html" title="class in javax.servlet.http"><code>HttpServlet</code></a>.
<p>
Note that this method is only called when a (Servlet) resource has indeed been invoked, i.e. if a previous call
to <code>validateRequest</code> that was invoked before any <a href="../../../../../../javax/servlet/Filter.html" title="interface in javax.servlet"><code>Filter</code></a> or <a href="../../../../../../javax/servlet/http/HttpServlet.html" title="class in javax.servlet.http"><code>HttpServlet</code></a> returned SUCCESS.</div>
<dl>
<dt><span class="paramLabel">Parameters:</span></dt>
<dd><code>request</code> - contains the request the client has made</dd>
<dd><code>response</code> - contains the response that will be send to the client</dd>
<dd><code>httpMessageContext</code> - context for interacting with the container</dd>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>the completion status of the processing performed by this method</dd>
<dt><span class="throwsLabel">Throws:</span></dt>
<dd><code><a href="../../../../../../javax/security/enterprise/AuthenticationException.html" title="class in javax.security.enterprise">AuthenticationException</a></code> - when the processing failed</dd>
</dl>
</li>
</ul>
<a name="cleanSubject-javax.servlet.http.HttpServletRequest-javax.servlet.http.HttpServletResponse-javax.security.enterprise.authentication.mechanism.http.HttpMessageContext-">
<!-- -->
</a>
<ul class="blockListLast">
<li class="blockList">
<h4>cleanSubject</h4>
<pre>default&nbsp;void&nbsp;cleanSubject(<a href="../../../../../../javax/servlet/http/HttpServletRequest.html" title="interface in javax.servlet.http">HttpServletRequest</a>&nbsp;request,
<a href="../../../../../../javax/servlet/http/HttpServletResponse.html" title="interface in javax.servlet.http">HttpServletResponse</a>&nbsp;response,
<a href="../../../../../../javax/security/enterprise/authentication/mechanism/http/HttpMessageContext.html" title="interface in javax.security.enterprise.authentication.mechanism.http">HttpMessageContext</a>&nbsp;httpMessageContext)</pre>
<div class="block">Remove mechanism specific principals and credentials from the subject and any other state the mechanism
might have used.
<p>
This method is called in response to <a href="../../../../../../javax/servlet/http/HttpServletRequest.html#logout--"><code>HttpServletRequest.logout()</code></a> and gives the authentication mechanism
the option to remove any state associated with an earlier established authenticated identity. For example, an
authentication mechanism that stores state within a cookie can send remove that cookie here.</div>
<dl>
<dt><span class="paramLabel">Parameters:</span></dt>
<dd><code>request</code> - contains the request the client has made</dd>
<dd><code>response</code> - contains the response that will be send to the client</dd>
<dd><code>httpMessageContext</code> - context for interacting with the container</dd>
</dl>
</li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
</div>
<!-- ========= END OF CLASS DATA ========= -->
<!-- ======= START OF BOTTOM NAVBAR ====== -->
<div class="bottomNav"><a name="navbar.bottom">
<!-- -->
</a>
<div class="skipNav"><a href="#skip.navbar.bottom" title="Skip navigation links">Skip navigation links</a></div>
<a name="navbar.bottom.firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li><a href="../../../../../../overview-summary.html">Overview</a></li>
<li><a href="package-summary.html">Package</a></li>
<li class="navBarCell1Rev">Class</li>
<li><a href="package-tree.html">Tree</a></li>
<li><a href="../../../../../../deprecated-list.html">Deprecated</a></li>
<li><a href="../../../../../../index-all.html">Index</a></li>
<li><a href="../../../../../../help-doc.html">Help</a></li>
</ul>
</div>
<div class="subNav">
<ul class="navList">
<li><a href="../../../../../../javax/security/enterprise/authentication/mechanism/http/FormAuthenticationMechanismDefinition.html" title="annotation in javax.security.enterprise.authentication.mechanism.http"><span class="typeNameLink">Prev&nbsp;Class</span></a></li>
<li><a href="../../../../../../javax/security/enterprise/authentication/mechanism/http/HttpAuthenticationMechanismWrapper.html" title="class in javax.security.enterprise.authentication.mechanism.http"><span class="typeNameLink">Next&nbsp;Class</span></a></li>
</ul>
<ul class="navList">
<li><a href="../../../../../../index.html?javax/security/enterprise/authentication/mechanism/http/HttpAuthenticationMechanism.html" target="_top">Frames</a></li>
<li><a href="HttpAuthenticationMechanism.html" target="_top">No&nbsp;Frames</a></li>
</ul>
<ul class="navList" id="allclasses_navbar_bottom">
<li><a href="../../../../../../allclasses-noframe.html">All&nbsp;Classes</a></li>
</ul>
<div>
<script type="text/javascript"><!--
allClassesLink = document.getElementById("allclasses_navbar_bottom");
if(window==top) {
allClassesLink.style.display = "block";
}
else {
allClassesLink.style.display = "none";
}
//-->
</script>
</div>
<div>
<ul class="subNavList">
<li>Summary:&nbsp;</li>
<li>Nested&nbsp;|&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li>Constr&nbsp;|&nbsp;</li>
<li><a href="#method.summary">Method</a></li>
</ul>
<ul class="subNavList">
<li>Detail:&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li>Constr&nbsp;|&nbsp;</li>
<li><a href="#method.detail">Method</a></li>
</ul>
</div>
<a name="skip.navbar.bottom">
<!-- -->
</a></div>
<!-- ======== END OF BOTTOM NAVBAR ======= -->
</body>
</html>