CINXE.COM

<!doctype html> <html lang="en" prefix="og: https://ogp.me/ns#"> <head> <script async src="https://www.googletagmanager.com/gtag/js?id=G-0J2P9316N6"></script> <script> window.dataLayer = window.dataLayer || []; function gtag(){dataLayer.push(arguments);} gtag('js', new Date()); gtag('config', 'G-0J2P9316N6'); </script> <meta charset="utf-8"/> <title>Configuring trusted certificates - Keycloak</title> <meta name="twitter:card" content="summary_large"> <meta name="twitter:site" content="@keycloak"> <meta property="og:site_name" content="Keycloak"> <meta property="og:title" content="Configuring trusted certificates"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta name="description" property="og:description" content="How to configure the Keycloak Truststore to communicate through TLS."> <meta name="author" content="Keycloak Team"> <meta name="keywords" content="sso,idm,openid connect,saml,kerberos,ldap"> <link href="https://www.keycloak.org/resources/bootstrap/dist/css/bootstrap.min.css" rel="stylesheet"> <link href="https://www.keycloak.org/resources/@fortawesome/fontawesome-free/css/all.min.css" rel="stylesheet"> <link href="https://www.keycloak.org/resources/css/keycloak.css" rel="stylesheet"> <link rel="canonical" href="https://www.keycloak.org/server/keycloak-truststore"> <meta property="og:url" content="https://www.keycloak.org/server/keycloak-truststore"> <link rel="shortcut icon" href="https://www.keycloak.org/resources/favicon.ico"> <script src="https://www.keycloak.org/resources/bootstrap/dist/js/bootstrap.min.js" type="text/javascript"></script> <script src="https://www.keycloak.org/resources/tocbot/dist/tocbot.min.js" type="text/javascript"></script></head> <body> <header class="navbar navbar-expand-md bg-light shadow-sm"> <nav class="container-xxl flex-wrap flex-md-no-wrap navbar-light"> <a class="navbar-brand me-3 me-md-4 me-lg-5" href="https://www.keycloak.org/"> <img class="img-fluid" src="https://www.keycloak.org/resources/images/logo.svg" width="240" alt="Keycloak"/> </a> <a class="nav-link d-none d-sm-block d-md-none d-lg-block" href="https://github.com/keycloak/keycloak"><img src="https://img.shields.io/github/stars/keycloak/keycloak?label=GitHub%20Stars" style="height: 25px" alt="GitHub stars"/></a> <a class="nav-link d-block d-sm-none d-md-block d-lg-none" href="https://github.com/keycloak/keycloak"><img src="https://img.shields.io/github/stars/keycloak/keycloak?label=" style="height: 25px" alt="GitHub stars"/></a> <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarCollapse" aria-controls="navbarCollapse" aria-expanded="false" aria-label="Toggle navigation"> <span class="fa fa-bars fa-lg px-1 py-2"></span> </button> <div class="collapse navbar-collapse" id="navbarCollapse"> <ul class="navbar-nav flex-row flex-wrap bd-navbar-nav pt-2 py-md-0"> <li class="nav-item col-6 col-md-auto"> <a class="nav-link " href="https://www.keycloak.org/guides">Guides</a> </li> <li class="nav-item col-6 col-md-auto"> <a class="nav-link " href="https://www.keycloak.org/documentation">Docs</a> </li> <li class="nav-item col-6 col-md-auto"> <a class="nav-link " href="https://www.keycloak.org/downloads">Downloads</a> </li> <li class="nav-item col-6 col-md-auto"> <a class="nav-link " href="https://www.keycloak.org/community">Community</a> </li> <li class="nav-item col-6 col-md-auto"> <a class="nav-link " href="https://www.keycloak.org/blog">Blog</a> </li> </ul> </div> </nav> </header> <div class="container mt-5 kc-article"> <div class="row"> <div class="col-md-9 col-xl-10 col-sm-12"> <nav aria-label="breadcrumb"> <ol class="breadcrumb"> <li class="breadcrumb-item"><a href="https://www.keycloak.org/guides">Guides</a></li> <li class="breadcrumb-item"><a href="https://www.keycloak.org/guides#server">Server</a></li> <li class="breadcrumb-item active">Configuring trusted certificates</li> </ol> </nav> <div class="mb-4"> <h1>Configuring trusted certificates</h1> <span class="text-muted">How to configure the Keycloak Truststore to communicate through TLS.</span> </div> <div class="kc-asciidoc" id="guide-body"> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>When Keycloak communicates with external services or has an incoming connection through TLS, it has to validate the remote certificate in order to ensure it is connecting to a trusted server. This is necessary in order to prevent man-in-the-middle attacks.</p> </div> <div class="paragraph"> <p>The certificates of these clients or servers, or the CA that signed these certificates, must be put in a truststore. This truststore is then configured for use by Keycloak.</p> </div> </div> </div> <div class="sect1"> <h2 id="_configuring_the_system_truststore"><a class="anchor" href="#_configuring_the_system_truststore"></a>Configuring the System Truststore</h2> <div class="sectionbody"> <div class="paragraph"> <p>The existing Java default truststore certs will always be trusted. If you need additional certificates, which will be the case if you have self-signed or internal certificate authorities that are not recognized by the JRE, they can be included in the <code>conf/truststores</code> directory or subdirectories. The certs may be in PEM files, or PKCS12 files with extension <code>.p12</code>, <code>.pfx</code>, or <code>.pkcs12</code>. If in PKCS12, the certs must be unencrypted - meaning no password is expected.</p> </div> <div class="paragraph"> <p>If you need an alternative path, use the <code>--truststore-paths</code> option to specify additional files or directories where PEM or PKCS12 files are located. Paths are relative to where you launched Keycloak, so absolute paths are recommended instead. If a directory is specified, it will be recursively scanned for truststore files.</p> </div> <div class="paragraph"> <p>After all applicable certs are included, the truststore will be used as the system default truststore via the <code>javax.net.ssl</code> properties, and as the default for internal usage within Keycloak.</p> </div> <div class="paragraph"> <p>For example:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">bin/kc.[sh|bat] start --truststore-paths=/opt/truststore/myTrustStore.pfx,/opt/other-truststore/myOtherTrustStore.pem</code></pre> </div> </div> <div class="paragraph"> <p>It is still possible to directly set your own <code>javax.net.ssl</code> truststore System properties, but it’s recommended to use the <code>--truststore-paths</code> instead.</p> </div> </div> </div> <div class="sect1"> <h2 id="_hostname_verification_policy"><a class="anchor" href="#_hostname_verification_policy"></a>Hostname Verification Policy</h2> <div class="sectionbody"> <div class="paragraph"> <p>You may refine how hostnames are verified by TLS connections with the <code>tls-hostname-verifier</code> property.</p> </div> <div class="ulist"> <ul> <li> <p><code>DEFAULT</code> (the default) allows wildcards in subdomain names (e.g. *.foo.com) to match names with the same number of levels (e.g. a.foo.com, but not a.b.foo.com) - with rules and exclusions for public suffixes based upon <a href="https://publicsuffix.org/list/" class="bare">https://publicsuffix.org/list/</a></p> </li> <li> <p><code>ANY</code> means that the hostname is not verified.</p> </li> <li> <p><code>WILDCARD</code> (deprecated) allows wildcards in subdomain names (e.g. *.foo.com) to match anything, including multiple levels (e.g. a.b.foo.com). Use DEFAULT instead.</p> </li> <li> <p><code>STRICT</code> (deprecated) allows wildcards in subdomain names (e.g. *.foo.com) to match names with the same number of levels (e.g. a.foo.com, but not a.b.foo.com) - with some limited exclusions. Use DEFAULT instead.</p> <div class="paragraph"> <p>Please note that this setting does not apply to LDAP secure connections, which require strict hostname checking.</p> </div> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_relevant_options"><a class="anchor" href="#_relevant_options"></a>Relevant options</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch options"> <colgroup> <col style="width: 75%;"> <col style="width: 25%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top"></th> <th class="tableblock halign-left valign-top">Value</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph"> <p><span class="options-key"><code>tls-hostname-verifier</code></span></p> </div> <div class="paragraph"> <p><span class="options-description">The TLS hostname verification policy for out-going HTTPS and SMTP requests.</span></p> </div> <div class="openblock options-extended"> <div class="content"> <div class="paragraph"> <p><strong>CLI:</strong> <code>--tls-hostname-verifier</code><br> <strong>Env:</strong> <code>KC_TLS_HOSTNAME_VERIFIER</code></p> </div> </div> </div> <div class="paragraph"> <p>STRICT and WILDCARD have been deprecated, use DEFAULT instead. <strong>Deprecated values: <code>STRICT</code>, <code>WILDCARD</code></strong></p> </div></div></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>ANY</code>, <code>WILDCARD</code> (deprecated), <code>STRICT</code> (deprecated), <code>DEFAULT</code> (default)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph"> <p><span class="options-key"><code>truststore-paths</code></span></p> </div> <div class="paragraph"> <p><span class="options-description">List of pkcs12 (p12, pfx, or pkcs12 file extensions), PEM files, or directories containing those files that will be used as a system truststore.</span></p> </div> <div class="openblock options-extended"> <div class="content"> <div class="paragraph"> <p><strong>CLI:</strong> <code>--truststore-paths</code><br> <strong>Env:</strong> <code>KC_TRUSTSTORE_PATHS</code></p> </div> </div> </div></div></td> <td class="tableblock halign-left valign-top"></td> </tr> </tbody> </table> </div> </div> </div> </div> <div class="col-md-3 mt-4 col-xl-2 col-sm-12 bg-light"> <div class="sticky-top px-2 py-3"> <div class="mt-2 mb-2 fw-bold">On this page</div> <div id="js-toc"></div> <div class="mt-4"> <a href="https://github.com/keycloak/keycloak/tree/main/docs/guides/server/keycloak-truststore.adoc" target="_blank"><i class="fa fa-edit"></i> Edit this guide</a> </div> </div> </div> </div> </div> <script src="https://www.keycloak.org/resources/js/guide.js" type="text/javascript"></script> <div class="container mt-5"> <footer class="py-3 my-4 border-top"> <p class="text-center text-muted">Keycloak is a Cloud Native Computing Foundation incubation project</p> <div class="text-center"> <img alt="Cloud Native Computing Foundation" src="https://www.keycloak.org/resources/images/cncf_logo.png"/> </div> <p class="mt-4 text-center small text-muted">© Keycloak Authors 2024. © 2024 The Linux Foundation. All rights reserved. The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The Linux Foundation, please see our <a href="https://www.linuxfoundation.org/trademark-usage">Trademark Usage page</a>.</p> </footer> </div> </body> </html>