blob: f5f7a95d05918a8c857ec638eb7e624a95ea2607 [file] [log] [blame]
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Apache TomEE</title>
<meta name="description"
content="Apache TomEE is a lightweight, yet powerful, JavaEE Application server with feature rich tooling." />
<meta name="keywords" content="tomee,asf,apache,javaee,jee,shade,embedded,test,junit,applicationcomposer,maven,arquillian" />
<meta name="author" content="Luka Cvetinovic for Codrops" />
<link rel="icon" href="../../../favicon.ico">
<link rel="icon" type="image/png" href="../../../favicon.png">
<meta name="msapplication-TileColor" content="#80287a">
<meta name="theme-color" content="#80287a">
<link rel="stylesheet" type="text/css" href="../../../css/normalize.css">
<link rel="stylesheet" type="text/css" href="../../../css/bootstrap.css">
<link rel="stylesheet" type="text/css" href="../../../css/owl.css">
<link rel="stylesheet" type="text/css" href="../../../css/animate.css">
<link rel="stylesheet" type="text/css" href="../../../fonts/font-awesome-4.1.0/css/font-awesome.min.css">
<link rel="stylesheet" type="text/css" href="../../../fonts/eleganticons/et-icons.css">
<link rel="stylesheet" type="text/css" href="../../../css/jqtree.css">
<link rel="stylesheet" type="text/css" href="../../../css/idea.css">
<link rel="stylesheet" type="text/css" href="../../../css/cardio.css">
<script type="text/javascript">
<!-- Matomo -->
var _paq = window._paq = window._paq || [];
/* tracker methods like "setCustomDimension" should be called before "trackPageView" */
/* We explicitly disable cookie tracking to avoid privacy issues */
_paq.push(['disableCookies']);
_paq.push(['trackPageView']);
_paq.push(['enableLinkTracking']);
(function () {
var u = "//matomo.privacy.apache.org/";
_paq.push(['setTrackerUrl', u + 'matomo.php']);
_paq.push(['setSiteId', '5']);
var d = document, g = d.createElement('script'), s = d.getElementsByTagName('script')[0];
g.async = true;
g.src = u + 'matomo.js';
s.parentNode.insertBefore(g, s);
})();
<!-- End Matomo Code -->
</script>
</head>
<body>
<div class="preloader">
<img src="../../../img/loader.gif" alt="Preloader image">
</div>
<nav class="navbar">
<div class="container">
<div class="row"> <div class="col-md-12">
<!-- Brand and toggle get grouped for better mobile display -->
<div class="navbar-header">
<button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#bs-example-navbar-collapse-1">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="/" title="Apache TomEE">
<span>
<img
src="../../../img/apache_tomee-logo.svg"
onerror="this.src='../../../img/apache_tomee-logo.jpg'"
height="50"
>
</span>
</a>
</div>
<!-- Collect the nav links, forms, and other content for toggling -->
<div class="collapse navbar-collapse" id="bs-example-navbar-collapse-1">
<ul class="nav navbar-nav navbar-right main-nav">
<li><a href="../../../docs.html">Documentation</a></li>
<li><a href="../../../community/index.html">Community</a></li>
<li><a href="../../../security/security.html">Security</a></li>
<li><a class="btn btn-accent accent-orange no-shadow" href="../../../download.html">Downloads</a></li>
</ul>
</div>
<!-- /.navbar-collapse -->
</div></div>
</div>
<!-- /.container-fluid -->
</nav>
<div id="main-block" class="container main-block">
<div class="row title">
<div class="col-md-12">
<div class='page-header'>
<h1>TomEE MicroProfile JWT</h1>
</div>
</div>
</div>
<div class="row">
<div class="col-md-12">
<div id="preamble">
<div class="sectionbody">
<div class="paragraph">
<p>Apache TomEE supports <a href="https://download.eclipse.org/microprofile/microprofile-jwt-auth-2.0/microprofile-jwt-auth-spec-2.0.html">MicroProfile JWT 2.0</a>, which allows applications to be secured using JWTs.
JWTs may be either:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Signed (<a href="https://www.rfc-editor.org/rfc/rfc7515">JWS</a>) tokens, verified via a public key you configure</p>
</li>
<li>
<p>Encrypted (<a href="https://www.rfc-editor.org/rfc/rfc7516">JWE</a>) tokens, decrypted via a private key you configure</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Key types supported:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>RSA</p>
</li>
<li>
<p>Elliptic curve (EC)</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Key formats supported:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>PEM PKCS1 and PKCS8</p>
</li>
<li>
<p>JWK and JWKS</p>
</li>
<li>
<p>OpenSSH Public Key (<code>.pub</code> and <code>authorized_keys</code>)</p>
</li>
<li>
<p>SSH 2 Public Key</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Signature algorithms supported:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>RS256</p>
</li>
<li>
<p>RS384</p>
</li>
<li>
<p>RS512</p>
</li>
<li>
<p>ES256</p>
</li>
<li>
<p>ES384</p>
</li>
<li>
<p>ES512</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Decryption algorithms supported:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>RSA-OAEP</p>
</li>
<li>
<p>RSA-OAEP-256</p>
</li>
<li>
<p>ECDH-ES</p>
</li>
<li>
<p>ECDH-ES+A128KW</p>
</li>
<li>
<p>ECDH-ES+A192KW</p>
</li>
<li>
<p>ECDH-ES+A256KW</p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_microprofile_jwt_configuration_properties">MicroProfile JWT Configuration Properties</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Specifying the keys for verifying or decrypting JWTs is done via a <code>META-INF/microprofile-config.properties</code> and the following MP JWT 2.0 Configuration Properties.</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 20%;">
<col style="width: 20%;">
<col style="width: 60%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Property</th>
<th class="tableblock halign-left valign-top">Type</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>mp.jwt.verify.publickey</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The contents of any valid public key file. Allows the public key to be inlined into the <code>microprofile-config.properties</code> withou the need for separate files.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>mp.jwt.verify.publickey.location</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The location of any valid public key file. Can be specified as a relative path on disk, relative path on the classpath, or valid URL such a <code>file:</code>, <code>http:</code>, or <code>https:</code>. Custom URLs are supported as long as there is a corresponding <code>java.net.URLStreamHandler</code> installed in the JVM.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>mp.jwt.decrypt.key.location</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The location of any valid private key file. Can be specified as a relative path on disk, relative path on the classpath, or valid URL such a <code>file:</code>, <code>http:</code>, or <code>https:</code>. Custom URLs are supported as long as there is a corresponding <code>java.net.URLStreamHandler</code> installed in the JVM.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>mp.jwt.token.header</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The name of the HTTP Request header where clients will JWTs. The default value is <code>Authorization</code>, but may be any header name including a customer header. Specifying a value of <code>Cookie</code> will enable JWTs to be passed to the server as HTTP Cookies.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>mp.jwt.token.cookie</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">When <code>mp.jwt.token.header=Cookie</code> the value of <code>mp.jwt.token.cookie</code> specifies the exact cookie name holding the JWT. The default is <code>Bearer</code>.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>mp.jwt.verify.audiences</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">A comma delimited list of allowable values for the JWT <code>aud</code> claim. When specified, a JWT with an <code>aud</code> that does not apper in the allowed list will result in an HTTP <code>401</code>. When not specified, all <code>aud</code> values are accepted including no <code>aud</code> at all.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>mp.jwt.verify.issuer</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The expected value of the <code>iss</code> JWT claim. When specified, a JWT with an <code>iss</code> that does not match the configured value will result in an HTTP <code>401</code>. When not specified, any <code>iss</code> values are accepted including no <code>iss</code> at all.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>mp.jwt.verify.publickey.algorithm</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The expected value of the <code>alg</code> JWT header. When specified, a JWT with an <code>alg</code> that does not match the configured value will result in an HTTP <code>401</code> and no signature check will occur. When not specified, any of the supported signature algorithms are considered applicable.</p></td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="sect1">
<h2 id="_tomee_jwt_configuration_properties">TomEE JWT Configuration Properties</h2>
<div class="sectionbody">
<div class="paragraph">
<p>In addition to the standard MicroProfile JWT configuration properties above, the <code>META-INF/microprofile-config.properties</code> may contain any of the following TomEE-specific configuration properties.</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 20%;">
<col style="width: 20%;">
<col style="width: 60%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Property</th>
<th class="tableblock halign-left valign-top">Type</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>mp.jwt.tomee.allow.no-exp</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Disables enforcing the <code>exp</code> time of the JWT. Useful if JWTs are also verified by an API Gateway or proxy before reaching the server. The default value is <code>false</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>tomee.jwt.verify.publickey.cache</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Enables public keys to be supplied after deployment has occurred or refreshed periodically at runtime. Useful for when keys are supplied via an <code>http</code> or <code>https</code> URL. Setting <code>tomee.jwt.verify.publickey.cache=true</code> is required for any of the subsequent <code>tomee.jwt.verify.publickey.cache.*</code> properties to take effect. Default value is <code>true</code> or <code>http</code> or <code>https</code> URLs and <code>false</code> for all other key locations.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>tomee.jwt.verify.publickey.cache.initialRetryDelay</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="../configuring-durations.html">Duration</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Should the first attempt to load keys fail, this setting specifies how long we should wait before trying again. An exponential backoff will occur and the delay will double on each subsequent retry. This allows retrying to be very aggressive in the event of a temporary issue, but prevents overloading the server supplying the keys. The default value is <code>2 seconds</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>tomee.jwt.verify.publickey.cache.maxRetryDelay</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="../configuring-durations.html">Duration</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Allows the retry attempts to eventually reach a fixed rate after a certain maximum delay is reached. This property disables the exponential backoff once the specified maximum delay is reached. All subsequent retries will happen at the interval specifed. To disable exponential backoff entirely, set <code>initialRetryDelay</code> and <code>maxRetryDelay</code> to the same value. The default value is <code>1 hour</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>tomee.jwt.verify.publickey.cache.accessTimeout</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="../configuring-durations.html">Duration</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the maximum time incoming HTTP Requests with JWTs will block and wait for keys when no keys are available. If specified time is reached, callers will recieve a HTTP <code>401</code>. The default value is <code>30 seconds</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>tomee.jwt.verify.publickey.cache.refreshInterval</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="../configuring-durations.html">Duration</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Specifies how frequently TomEE should check the configured location for new keys. Should any refresh fail or result in no valid keys, the keys currently in use are not replaced and no subsequent attempts are made until the next refresh interval. The default value is <code>1 day</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>tomee.jwt.decrypt.key.cache</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Enables private keys to be supplied after deployment has occurred or refreshed periodically at runtime. Useful for when keys are supplied via an <code>http</code> or <code>https</code> URL. Setting <code>tomee.jwt.decrypt.key.cache=true</code> is required for any of the subsequent <code>tomee.jwt.decrypt.key.cache.*</code> properties to take effect. Default value is <code>true</code> or <code>http</code> or <code>https</code> URLs and <code>false</code> for all other key locations.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>tomee.jwt.decrypt.key.cache.initialRetryDelay</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="../configuring-durations.html">Duration</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Should the first attempt to load keys fail, this setting specifies how long we should wait before trying again. An exponential backoff will occur and the delay will double on each subsequent retry. This allows retrying to be very aggressive in the event of a temporary issue, but prevents overloading the server supplying the keys. The default value is <code>2 seconds</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>tomee.jwt.decrypt.key.cache.maxRetryDelay</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="../configuring-durations.html">Duration</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Allows the retry attempts to eventually reach a fixed rate after a certain maximum delay is reached. This property disables the exponential backoff once the specified maximum delay is reached. All subsequent retries will happen at the interval specifed. To disable exponential backoff entirely, set <code>initialRetryDelay</code> and <code>maxRetryDelay</code> to the same value. The default value is <code>1 hour</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>tomee.jwt.decrypt.key.cache.accessTimeout</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="../configuring-durations.html">Duration</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Specifies the maximum time incoming HTTP Requests with JWTs will block and wait for keys when no keys are available. If specified time is reached, callers will recieve a HTTP <code>401</code>. The default value is <code>30 seconds</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>tomee.jwt.decrypt.key.cache.refreshInterval</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="../configuring-durations.html">Duration</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Specifies how frequently TomEE should check the configured location for new keys. Should any refresh fail or result in no valid keys, the keys currently in use are not replaced and no subsequent attempts are made until the next refresh interval. The default value is <code>1 day</code></p></td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
</div>
<div style="margin-bottom: 30px;"></div>
<footer>
<div class="container">
<div class="row">
<div class="col-sm-6 text-center-mobile">
<h3 class="white">Be simple. Be certified. Be Tomcat.</h3>
<h5 class="light regular light-white">"A good application in a good server"</h5>
<ul class="social-footer">
<li><a href="https://www.facebook.com/ApacheTomEE/"><i class="fa fa-facebook"></i></a></li>
<li><a href="https://twitter.com/apachetomee"><i class="fa fa-twitter"></i></a></li>
</ul>
<h5 class="light regular light-white">
<a href="../../../privacy-policy.html" class="white">Privacy Policy</a>
</h5>
</div>
<div class="col-sm-6 text-center-mobile">
<div class="row opening-hours">
<div class="col-sm-3 text-center-mobile">
<h5><a href="../../../latest/docs/" class="white">Documentation</a></h5>
<ul class="list-unstyled">
<li><a href="../../../latest/docs/admin/configuration/index.html" class="regular light-white">How to configure</a></li>
<li><a href="../../../latest/docs/admin/file-layout.html" class="regular light-white">Dir. Structure</a></li>
<li><a href="../../../latest/docs/developer/testing/index.html" class="regular light-white">Testing</a></li>
<li><a href="../../../latest/docs/admin/cluster/index.html" class="regular light-white">Clustering</a></li>
</ul>
</div>
<div class="col-sm-3 text-center-mobile">
<h5><a href="../../../latest/examples/" class="white">Examples</a></h5>
<ul class="list-unstyled">
<li><a href="../../../latest/examples/simple-cdi-interceptor.html" class="regular light-white">CDI Interceptor</a></li>
<li><a href="../../../latest/examples/rest-cdi.html" class="regular light-white">REST with CDI</a></li>
<li><a href="../../../latest/examples/ejb-examples.html" class="regular light-white">EJB</a></li>
<li><a href="../../../latest/examples/jsf-managedBean-and-ejb.html" class="regular light-white">JSF</a></li>
</ul>
</div>
<div class="col-sm-3 text-center-mobile">
<h5><a href="../../../community/index.html" class="white">Community</a></h5>
<ul class="list-unstyled">
<li><a href="../../../community/contributors.html" class="regular light-white">Contributors</a></li>
<li><a href="../../../community/social.html" class="regular light-white">Social</a></li>
<li><a href="../../../community/sources.html" class="regular light-white">Sources</a></li>
</ul>
</div>
<div class="col-sm-3 text-center-mobile">
<h5><a href="../../../security/index.html" class="white">Security</a></h5>
<ul class="list-unstyled">
<li><a href="https://apache.org/security" target="_blank" class="regular light-white">Apache Security</a></li>
<li><a href="https://apache.org/security/projects.html" target="_blank" class="regular light-white">Security Projects</a></li>
<li><a href="https://cve.mitre.org" target="_blank" class="regular light-white">CVE</a></li>
</ul>
</div>
</div>
</div>
</div>
<div class="row bottom-footer text-center-mobile">
<div class="col-sm-12 light-white">
<p>Copyright &copy; 1999-2022 The Apache Software Foundation, Licensed under the Apache License, Version 2.0. Apache TomEE, TomEE, Apache, the Apache feather logo, and the Apache TomEE project logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.</p>
</div>
</div>
</div>
</footer>
<!-- Holder for mobile navigation -->
<div class="mobile-nav">
<ul>
<li><a hef="../../../latest/docs/admin/index.html">Administrators</a>
<li><a hef="../../../latest/docs/developer/index.html">Developers</a>
<li><a hef="../../../latest/docs/advanced/index.html">Advanced</a>
<li><a hef="../../../community/index.html">Community</a>
</ul>
<a href="#" class="close-link"><i class="arrow_up"></i></a>
</div>
<!-- Scripts -->
<script src="../../../js/jquery-1.11.1.min.js"></script>
<script src="../../../js/owl.carousel.min.js"></script>
<script src="../../../js/bootstrap.min.js"></script>
<script src="../../../js/wow.min.js"></script>
<script src="../../../js/typewriter.js"></script>
<script src="../../../js/jquery.onepagenav.js"></script>
<script src="../../../js/tree.jquery.js"></script>
<script src="../../../js/highlight.pack.js"></script>
<script src="../../../js/main.js"></script>
</body>
</html>