Mutual TLS Authentication - Plugin

<!DOCTYPE html> <html lang="en-US" itemscope itemtype="http://schema.org/Article"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">  <script src="https://cdn.cookielaw.org/scripttemplates/otSDKStub.js" type="text/javascript" charset="UTF-8" data-domain-script="2c4de954-6bec-4e93-8086-64cb113f151a"> </script> <script type="text/javascript"> function OptanonWrapper() { } </script>   <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src= 'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer', 'GTM-NL48VKT');</script>  <meta charset="utf-8"> <meta http-equiv="X-UA-Compatible" content="IE=edge"> <meta name="viewport" content="width=device-width, initial-scale=1"> <title>Mutual TLS Authentication - Plugin | Kong Docs</title> <meta name="description" content="Documentation for Kong, the Cloud Connectivity Company for APIs and Microservices."> <meta name="author" content="KongHQ"> <meta property="og:title" content="Mutual TLS Authentication - Plugin | Kong Docs"> <meta property="og:site_name" content="Kong Docs">  <meta property="og:url" content="https://docs.konghq.com"> <meta property="og:description" content="Documentation for Kong, the Cloud Connectivity Company for APIs and Microservices."> <meta property="og:type" content="website"> <meta property="og:locale" content="en_US"> <meta property="og:image" content="https://docs.konghq.com/assets/images/share.png"> <meta name="twitter:card" content="summary_large_image"> <meta name="twitter:site" content="@thekonginc"> <meta name="twitter:creator" content="@thekonginc"> <meta name="twitter:url" content="https://docs.konghq.com"> <meta name="twitter:description" content="Documentation for Kong, the Cloud Connectivity Company for APIs and Microservices."> <meta name="twitter:image" content="https://docs.konghq.com/assets/images/share.png"> <meta property="fb:admins" content="227304446"> <meta property="fb:admins" content="576641408"> <meta name="google-site-verification" content="CrU3zp02dNKTe8NSAipL4NCPkrIjDXG8fViTZ-MIzP4"> <script type="application/ld+json"> { "@context": "http://schema.org", "@type": "Organization", "name": "KongHQ", "url": "https://docs.konghq.com", "logo": "https://docs.konghq.com/assets/images/logo.png", "sameAs": [ "https://www.facebook.com/konginc", "https://twitter.com/thekonginc", "https://plus.google.com/+mashape" ] } </script>  <link rel="dns-prefetch" href="https://cloud.typography.com"> <link rel="dns-prefetch" href="https://dev.visualwebsiteoptimizer.com"> <link rel="dns-prefetch" href="https://cdn.segment.com"> <link rel="icon" type="image/x-icon" href="/assets/images/favicon.ico"> <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@docsearch/css@3"> <link rel="canonical" href="https://docs.konghq.com/hub/kong-inc/mtls-auth/"> <link rel="alternate" hreflang="x-default" href="https://docs.konghq.com/hub/kong-inc/mtls-auth/"> <link rel="alternate" hreflang="ja" href="https://docs.jp.konghq.com/hub/kong-inc/mtls-auth/"> <meta name="robots" content="follow,index">  <script src="https://kit.fontawesome.com/1332a92967.js" crossorigin="anonymous"> </script> <script src="/vite/assets/application-D8sXFsvE.js" crossorigin="anonymous" type="module"></script> <link href="/vite/assets/_commonjsHelpers-Cpj98o6Y.js" rel="modulepreload" as="script" crossorigin="anonymous"> <link rel="stylesheet" href="/vite/assets/application-C5Quk452.css" media="screen"> </head> <body id="" data-spy="scroll" data-target="#scroll-sidebar" data-offset="350">  <noscript><iframe src="https://www.googletagmanager.com/ns.html?id=GTM-NL48VKT" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>  <header class="navbar-v2 closed"> <a class="skip-main" href="#main">Skip to content</a>    <div class="navbar-content"> <a href="https://konghq.com" class="navbar-brand col col-xl-auto" target="_blank" rel="noopener noreferrer"> <img src="/assets/images/logos/konglogo-dark-theme.svg" alt="Kong Logo" id="kong-logo"> </a> <span class="logo-divider">|</span> <a href="/" class="navbar-brand col col-xl-auto"> <img src="/assets/images/logos/docslogo-dark-theme.svg" alt="Kong Docs Logo" id="kong-docs-logo"> </a> <div class="separator mobile"></div> <div class="search-input-wrapper" id="getkong-algolia-search-input"> </div> <div class="search-results-wrapper"></div> <div class="navbar-items" role="navigation" aria-label="Main menu"> <ul class="navbar-items" role="menubar"> <li id="top-module-list" aria-haspopup="true" role="menuitem" aria-expanded="false" class="navbar-item main-menu-item with-submenu active"> <span tabindex="0" id="docs-link" class="main-menu-item-title">Docs</span> <span class="caret"></span> <ul class="navbar-item-submenu" role="menu"> <div class="submenu-section"> <li role="menuitem" class="docs-dropdown-li"> <a href="/api/" class="docs-dropdown-li__link" tabindex="-1"> <div class="docs-dropdown-li__card"> <span class="heading">Explore the API Specs</span> <div class="docs-dropdown-li__card-link"> <img src="/assets/images/landing-page/view-all-api-specs.png" alt="View all API Specs"> <span class="docs-dropdown-li__card-image"> View all API Specs <img src="/assets/images/landing-page/arrow-right.svg" alt="View all API Specs arrow image"> </span> </div> </div> </a> </li> <li role="menuitem" class="docs-dropdown-li" tabindex="-1"> <div class="docs-dropdown-li__section"> <div class="docs-dropdown-li__section-title"> <span class="heading">Documentation</span> </div> <div class="docs-dropdown-li__section-items"> <a class="item item-all" href="/api/" tabindex="-1"> <div class="item__description"> <div class="item__description-title">API Specs</div> </div> </a> <a class="item" href="/gateway/latest/" tabindex="-1"> <div class="item__description"> <div class="item__description-title">Kong Gateway</div> <div class="item__description-desc">Lightweight, fast, and flexible cloud-native API gateway</div> </div> </a> <a class="item" href="/konnect/" tabindex="-1"> <div class="item__description"> <div class="item__description-title">Kong Konnect</div> <div class="item__description-desc">Single platform for SaaS end-to-end connectivity</div> </div> </a> <a class="item" href="/gateway/latest/ai-gateway/" tabindex="-1"> <div class="item__description"> <div class="item__description-title">Kong AI Gateway</div> <div class="item__description-desc">Multi-LLM AI Gateway for GenAI infrastructure</div> </div> </a> <a class="item" href="/mesh/latest/" tabindex="-1"> <div class="item__description"> <div class="item__description-title">Kong Mesh</div> <div class="item__description-desc">Enterprise service mesh based on Kuma and Envoy</div> </div> </a> <a class="item" href="/deck/" tabindex="-1"> <div class="item__description"> <div class="item__description-title">decK</div> <div class="item__description-desc">Helps manage Kong’s configuration in a declarative fashion</div> </div> </a> <a class="item" href="/kubernetes-ingress-controller/latest/" tabindex="-1"> <div class="item__description"> <div class="item__description-title">Kong Ingress Controller</div> <div class="item__description-desc">Works inside a Kubernetes cluster and configures Kong to proxy traffic</div> </div> </a> <a class="item" href="/gateway-operator/latest/" tabindex="-1"> <div class="item__description"> <div class="item__description-title">Kong Gateway Operator</div> <div class="item__description-desc">Manage your Kong deployments on Kubernetes using YAML Manifests</div> </div> </a> <a class="item" href="https://docs.insomnia.rest/" tabindex="-1" target="_blank" rel="noopener nofollow noreferrer "> <div class="item__description"> <div class="item__description-title">Insomnia</div> <div class="item__description-desc">Collaborative API development platform</div> </div> </a> </div> </div> </li> </div> </ul> </li> <li role="menuitem" aria-haspopup="true" aria-expanded="false" class="navbar-item main-menu-item with-submenu navbar-item-hub"> <span id="plugin-link" class="main-menu-item-title" tabindex="0">Plugin Hub</span> <span class="caret"></span> <ul class="navbar-item-submenu" role="menu"> <div class="submenu-section"> <li role="menuitem" class="docs-dropdown-li"> <a href="/hub/" class="docs-dropdown-li__link" tabindex="-1"> <div class="docs-dropdown-li__card"> <span class="heading">Explore the Plugin Hub</span> <div class="docs-dropdown-li__card-link"> <img src="/assets/images/landing-page/view-all-plugins.svg" alt="View all plugins"> <span class="docs-dropdown-li__card-image"> View all plugins <img src="/assets/images/landing-page/arrow-right.svg" alt="View all plugins arrow image"> </span> </div> </div> </a> </li> <li role="menuitem" class="docs-dropdown-li"> <div class="docs-dropdown-li__section"> <div class="docs-dropdown-li__section-title"> <span class="heading">Functionality</span> <a href="/hub/" class="view-all" tabindex="-1"> View all <img src="/assets/images/landing-page/arrow-right.svg" alt="View all arrow image"> </a> </div> <div class="docs-dropdown-li__section-items"> <a class="item item-all" href="/hub/" tabindex="-1"> <div class="item__description"> <div class="item__description-title">View all plugins</div> </div> </a> <a class="item" href="/hub/?category=ai" tabindex="-1"> <div> <img src="/assets/images/nav/hub/ai.svg" alt="AI's icon"> </div> <div class="item__description"> <div class="item__description-title">AI</div> <div class="item__description-desc">Govern, secure, and control AI traffic with multi-LLM AI Gateway plugins</div> </div> </a> <a class="item" href="/hub/?category=authentication" tabindex="-1"> <div> <img src="/assets/images/nav/hub/lock_person.svg" alt="Authentication's icon"> </div> <div class="item__description"> <div class="item__description-title">Authentication</div> <div class="item__description-desc">Protect your services with an authentication layer</div> </div> </a> <a class="item" href="/hub/?category=security" tabindex="-1"> <div> <img src="/assets/images/nav/hub/shield.svg" alt="Security's icon"> </div> <div class="item__description"> <div class="item__description-title">Security</div> <div class="item__description-desc">Protect your services with additional security layer</div> </div> </a> <a class="item" href="/hub/?category=traffic-control" tabindex="-1"> <div> <img src="/assets/images/nav/hub/route.svg" alt="Traffic Control's icon"> </div> <div class="item__description"> <div class="item__description-title">Traffic Control</div> <div class="item__description-desc">Manage, throttle and restrict inbound and outbound API traffic</div> </div> </a> <a class="item" href="/hub/?category=serverless" tabindex="-1"> <div> <img src="/assets/images/nav/hub/serverless.svg" alt="Serverless's icon"> </div> <div class="item__description"> <div class="item__description-title">Serverless</div> <div class="item__description-desc">Invoke serverless functions in combination with other plugins</div> </div> </a> <a class="item" href="/hub/?category=analytics-monitoring" tabindex="-1"> <div> <img src="/assets/images/nav/hub/bar_chart.svg" alt="Analytics & Monitoring's icon"> </div> <div class="item__description"> <div class="item__description-title">Analytics & Monitoring</div> <div class="item__description-desc">Visualize, inspect and monitor APIs and microservices traffic</div> </div> </a> <a class="item" href="/hub/?category=transformations" tabindex="-1"> <div> <img src="/assets/images/nav/hub/swap_horiz.svg" alt="Transformations's icon"> </div> <div class="item__description"> <div class="item__description-title">Transformations</div> <div class="item__description-desc">Transform request and responses on the fly on Kong</div> </div> </a> <a class="item" href="/hub/?category=logging" tabindex="-1"> <div> <img src="/assets/images/nav/hub/list_alt.svg" alt="Logging's icon"> </div> <div class="item__description"> <div class="item__description-title">Logging</div> <div class="item__description-desc">Log request and response data using the best transport for your infrastructure</div> </div> </a> </div> </div> </li> </div> </ul> </li> <li role="menuitem" class="main-menu-item"> <a href="https://support.konghq.com/" class="navbar-item" target="_blank" rel="noopener nofollow noreferrer ">Support</a> </li> <li role="menuitem" class="main-menu-item"> <a href="https://konghq.com/community/" class="navbar-item" target="_blank" rel="noopener noreferrer">Community</a> </li> <li role="menuitem" class="main-menu-item"> <a href="https://education.konghq.com" class="navbar-item" target="_blank" rel="noopener nofollow noreferrer ">Kong Academy</a> </li> </ul> <a id="top-cta" href="https://konghq.com/contact-sales?utm_source=docs.konghq.com" class="navbar-button" target="_blank" rel="noopener nofollow noreferrer "> Get a Demo </a> <a id="konnect-cta" href="https://konghq.com/products/kong-konnect/register?utm_medium=referral&utm_source=docs&utm_campaign=gateway-konnect&utm_content=top-nav" class="navbar-button" target="_blank" rel="noopener nofollow noreferrer "> Start Free Trial </a> </div> <div id="navbar-menu-toggle-button" class="small-screen-button" aria-label="Toggle navigation"> <div></div> <div></div> <div></div> </div> </div> </header>  <div class="search-selector">Plugin Hub</div> <div class="page v2 hub" data-url="/hub/kong-inc/mtls-auth/"> <div class="page--header-background"></div> <div class="container"> <header class="page-header"> <div class="page-header--nav"> <i class="sidebar-toggle"></i> <ul class="breadcrumbs"> <li class="breadcrumb-item"> <a href="/hub/"> <img src="/assets/images/icons/hub-layout/icn-breadcrumbs.svg" alt="Plugin Hub icon"> </a> </li> <li class="breadcrumb-item"> <a href="/hub/?category=authentication">Authentication</a> </li> <li class="breadcrumb-item active"> <a href="/hub/kong-inc/mtls-auth/">Mutual TLS Authentication</a> </li> <li class="breadcrumb-item"> Introduction </li> <li class="breadcrumb-item active"> <a href="/hub/kong-inc/mtls-auth/">Overview</a> </li> </ul> <div class="github-links"> <div class="github-links--edit"> <a href="https://github.com/Kong/docs.konghq.com/edit/main/app/_hub/kong-inc/mtls-auth/overview/_index.md" target="_blank" rel="noopener nofollow noreferrer "> <img src="/assets/images/icons/third-party/logo-github-white.svg" alt="github-edit-page">Edit this page </a> </div> <div class="github-links--issues"> <a href="https://github.com/Kong/docs.konghq.com/issues/" target="_blank" rel="noopener nofollow noreferrer "> <img src="/assets/images/icons/documentation/icn-monitoring-white.svg" alt="report-issue">Report an issue</a> </div> </div> </div> <div class="page-header--info"> <div class="page-header--info-icon"> <img src="/assets/images/icons/hub/kong-inc_mtls-auth.png" alt="header icon"> </div> <div class="page-header--info-meta"> <div class="meta--title"> <h1 id="main" tabindex="-1">Mutual TLS Authentication</h1> <div> <div class="versions-dropdown dropdown"> <button class="dropdown-button" id="version-dropdown" type="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> Gateway Version 3.9.x <em>(latest)</em> <span class="caret"></span> </button> <ul class="dropdown-menu dropdown-menu-right" id="version-list" role="menu" aria-labelledby="version-dropdown"> <li class=""> <a href="/hub/kong-inc/mtls-auth/unreleased/"> unreleased </a> </li> <li class="active"> <a href="/hub/kong-inc/mtls-auth/"> 3.9.x <em>(latest)</em> </a> </li> <li class=""> <a href="/hub/kong-inc/mtls-auth/3.8.x/"> 3.8.x </a> </li> <li class=""> <a href="/hub/kong-inc/mtls-auth/3.7.x/"> 3.7.x </a> </li> <li class=""> <a href="/hub/kong-inc/mtls-auth/3.6.x/"> 3.6.x </a> </li> <li class=""> <a href="/hub/kong-inc/mtls-auth/3.5.x/"> 3.5.x </a> </li> <li class=""> <a href="/hub/kong-inc/mtls-auth/3.4.x/"> 3.4.x </a> </li> <li class=""> <a href="/hub/kong-inc/mtls-auth/3.3.x/"> 3.3.x </a> </li> <li class=""> <a href="/hub/kong-inc/mtls-auth/3.2.x/"> 3.2.x </a> </li> <li class=""> <a href="/hub/kong-inc/mtls-auth/3.1.x/"> 3.1.x </a> </li> <li class=""> <a href="/hub/kong-inc/mtls-auth/2.8.x/"> 2.8.x </a> </li> </ul> </div> </div> </div> <div class="meta--content"> <div class="meta--content-title"><span>By Kong Inc.</span></div> <div class="meta--content-badges"> <a href="https://konghq.com/pricing" target="_blank" class="badge konnect" aria-label="available in Konnect" rel="noopener nofollow noreferrer "> </a> <a href="https://konghq.com/pricing" target="_blank" class="badge enterprise" aria-label="available with Kong Gateway Enterprise subscription" rel="noopener nofollow noreferrer "> </a> </div> </div> </div> </div> </header> <aside class="docs-sidebar"> <i class="fa fa-times close-sidebar"></i> <ul class="sidebar-container" role="tree" aria-label="Plugin's Documentation"> <li class="sidebar-item plugin-hub" role="none"> <span role="treeitem" class="sidebar-label"> <a class="sidebar-link" tabindex="-1" href="/hub/"> <img src="/assets/images/icons/hub-layout/icn-breadcrumbs.svg" alt=""> Plugin Hub </a> </span> </li> <li class="sidebar-item" role="none"> <span role="treeitem" class="sidebar-label" aria-expanded="false" aria-owns="id-1-introduction-subtree"> <img src="/assets/images/icons/hub-layout/icn-overview.svg" alt=""> Introduction <button class="sidebar-tree-toggle" aria-label="toggle Introduction subtree" tabindex="-1"> <i class="fa fa-chevron-down"></i> </button> </span> <ul class="items" id="id-1-introduction-subtree" role="group" aria-label="Introduction"> <li class="sidebar-item" role="none"> <span role="treeitem" class="sidebar-label"> <a class="sidebar-link" tabindex="-1" href="/hub/kong-inc/mtls-auth/"> Overview </a> </span> </li> </ul> </li> <li class="sidebar-item" role="none"> <span role="treeitem" class="sidebar-label"> <a class="sidebar-link" tabindex="-1" href="/hub/kong-inc/mtls-auth/configuration/"> <img src="/assets/images/icons/hub-layout/icn-configuration.svg" alt=""> Configuration reference </a> </span> </li> <li class="sidebar-item" role="none"> <span role="treeitem" class="sidebar-label" aria-expanded="false" aria-owns="id-3-using-the-plugin-subtree"> <img src="/assets/images/icons/hub-layout/icn-how-to.svg" alt=""> Using the plugin <button class="sidebar-tree-toggle" aria-label="toggle Using the plugin subtree" tabindex="-1"> <i class="fa fa-chevron-down"></i> </button> </span> <ul class="items" id="id-3-using-the-plugin-subtree" role="group" aria-label="Using the plugin"> <li class="sidebar-item" role="none"> <span role="treeitem" class="sidebar-label"> <a class="sidebar-link" tabindex="-1" href="/hub/kong-inc/mtls-auth/how-to/basic-example/"> Basic config examples </a> </span> </li> <li class="sidebar-item" role="none"> <span role="treeitem" class="sidebar-label"> <a class="sidebar-link" tabindex="-1" href="/hub/kong-inc/mtls-auth/how-to/add-cert-authorities/"> Add Certificate Authorities </a> </span> </li> <li class="sidebar-item" role="none"> <span role="treeitem" class="sidebar-label"> <a class="sidebar-link" tabindex="-1" href="/hub/kong-inc/mtls-auth/how-to/manual-mapping-cert-consumers/"> Manual Mappings Between Certificate and Consumer Objects </a> </span> </li> </ul> </li> <li class="sidebar-item" role="none"> <span role="treeitem" class="sidebar-label"> <a class="sidebar-link" tabindex="-1" href="/hub/kong-inc/mtls-auth/changelog/"> <img src="/assets/images/icons/hub-layout/icn-changelog.svg" alt=""> Changelog </a> </span> </li> <li> <a id="konnect-cta" href="https://konghq.com/products/kong-konnect/register?utm_medium=referral&utm_source=docs&utm_campaign=gateway-konnect&utm_content=mtls-auth" class="sidebar-button" target="_blank" rel="noopener nofollow noreferrer "> Try it in Konnect </a> </li> </ul> </aside> <aside class="docs-toc" id="plugin-toc"> <i class="fa fa-times close-sidebar"></i> <i class="fa fa-chevron-right collapse-toc"></i> <i class="far fa-list-alt expand-toc"></i> <div class="docs-toc-title"> <img src="/assets/images/icons/hub-layout/icn-on-this-page.svg" alt="On this page"><a href="#">On this page</a> </div> <ul> <li> <a href="#how-does-the-mtls-plugin-work" class="active scroll-to">How does the mTLS plugin work?</a> <ul> <li><a href="#client-certificate-request" class="scroll-to">Client certificate request</a></li> <li><a href="#sending-the-ca-dns-during-tls-handshake" class="scroll-to">Sending the CA DNs during TLS handshake</a></li> <li><a href="#troubleshooting" class="scroll-to">Troubleshooting</a></li> </ul> </li> <li><a href="#get-started-with-the-mtls-authentication-plugin" class="scroll-to">Get started with the mTLS Authentication plugin</a></li> </ul> </aside> <div class="page-content-container v2" id="documentation"> <div class="page-content"> <div class="content show-anchor-links"> <blockquote> <p> <em>Looking for the plugin's configuration parameters? You can find them in the <a href="/hub/kong-inc/mtls-auth/configuration/">Mutual TLS Authentication configuration reference</a> doc.</em> </p> </blockquote> <p>This plugin lets you add mutual TLS authentication based on a client-supplied or a server-supplied certificate, and on the configured trusted certificate authority (CA) list.</p> <p>The mTLS plugin automatically maps certificates to consumers based on the common name field.</p> <h2 id="how-does-the-mtls-plugin-work">How does the mTLS plugin work?</h2> <p>To authenticate a consumer with mTLS, it must provide a valid certificate and complete a mutual TLS handshake with Kong Gateway.</p> <p>The plugin validates the certificate provided against the configured CA list based on the requested route or service:</p> <ul> <li>If the certificate is not trusted or has expired, the response is <code class="language-plaintext highlighter-rouge">HTTP 401 TLS certificate failed verification</code>.</li> <li>If consumer did not present a valid certificate (this includes requests not sent to the HTTPS port), then the response is <code class="language-plaintext highlighter-rouge">HTTP 401 No required TLS certificate was sent</code>. The exception is if the <code class="language-plaintext highlighter-rouge">config.anonymous</code> option is configured on the plugin, in which case the anonymous consumer is used and the request is allowed to proceed.</li> </ul> <h3 id="client-certificate-request">Client certificate request</h3> <p>Client certificates are requested in the <code class="language-plaintext highlighter-rouge">ssl_certificate_by_lua</code> phase where Kong Gateway does not have access to <code class="language-plaintext highlighter-rouge">route</code> and <code class="language-plaintext highlighter-rouge">workspace</code> information. Due to this information gap, Kong Gateway asks for the client certificate by default on every handshake if the <code class="language-plaintext highlighter-rouge">mtls-auth</code> plugin is configured on any route or service. In most cases, the failure of the client to present a client certificate is not going to affect subsequent proxying if that route or service does not have the <code class="language-plaintext highlighter-rouge">mtls-auth</code> plugin applied. The exception is where the client is a desktop browser, which prompts the end user to choose the client cert to send and lead to user experience issues rather than proxy behavior problems.</p> <p>To improve this situation, Kong Gateway builds an in-memory map of SNIs from the configured Kong Gateway routes that should present a client certificate. To limit client certificate requests during handshake while ensuring the client certificate is requested when needed, the in-memory map is dependent on the routes in Kong Gateway having the SNIs attribute set. If any routes don’t have SNIs set, Kong Gateway must request the client certificate during every TLS handshake:</p> <ul> <li> <strong>Plugin is applied globally</strong>: mTLS auth is applied on every request irrespective of workspace</li> <li> <strong>Plugin is applied at the service level</strong>: If one or more of the routes <em>do not</em> have SNIs set, mTLS auth is applied on every request irrespective of workspace.</li> <li> <strong>Plugin is applied at the route level</strong>: If one or more of the routes <em>do not</em> have SNIs set, applied on every request irrespective of workspace.</li> <li> <strong>Plugin is applied at the route level and all routes have SNIs set</strong>: mTLS is applied on specific requests only.</li> </ul> <p>SNIs must be set for all routes that mutual TLS authentication uses.</p> <h3 id="sending-the-ca-dns-during-tls-handshake">Sending the CA DNs during TLS handshake</h3> <p>By default, Kong Gateway doesn’t send the CA DN list during the TLS handshake. More specifically, the <code class="language-plaintext highlighter-rouge">certificate_authorities</code> field in the CertificateRequest message is empty.</p> <p>In some cases, the client may need this <code class="language-plaintext highlighter-rouge">certificate_authorities</code> to guide certificate selection. Setting <code class="language-plaintext highlighter-rouge">config.send_ca_dn</code> to <code class="language-plaintext highlighter-rouge">true</code> adds the CA certificates configured in the <code class="language-plaintext highlighter-rouge">config.ca_certificate</code> to the lists of the corresponding SNIs.</p> <p>As mentioned in <a href="#client-certificate-request">Client certificate request</a>, due to the phase gap, Kong Gateway doesn’t know the route information in the <code class="language-plaintext highlighter-rouge">ssl_certificate_by_lua</code> phase, which is decided in the later <code class="language-plaintext highlighter-rouge">access</code> phase. Therefore Kong Gateway builds an in-memory map of SNIs. The CA DN list will eventually be associated with the SNIs. If multiple <code class="language-plaintext highlighter-rouge">mtls-auth</code> plugins with different <code class="language-plaintext highlighter-rouge">config.ca_certificate</code> are associated to the same SNI, their CA DNs are merged. For example:</p> <ul> <li>When the plugin is enabled in the <strong>global</strong> workspace scope, the CA DNs are associated with a special SNI, <code class="language-plaintext highlighter-rouge">\*</code>.</li> <li>When the plugin is applied at the <strong>service</strong> level, the CA DNs are associated with every SNI of every route to this service. If a route has no SNIs set, then the CA DNs are associated with a special SNI, <code class="language-plaintext highlighter-rouge">\*</code>.</li> <li>When the plugin is applied at the <strong>route</strong> level, the CA DNs are associated with every SNI configured on this route. If the route has no SNIs set, then the CA DNs are associated with a special SNI, <code class="language-plaintext highlighter-rouge">\*</code>.</li> </ul> <p>During the mTLS handshake, if the client sends a SNI in the ClientHello message and the SNI is found in the in-memory map of SNIs, then the corresponding CA DN list is sent in CertificateRequest message.</p> <p>If the client doesn’t send SNIs in the ClientHello message or the SNI sent is unknown to Kong Gateway, then the CA DN list associated with <code class="language-plaintext highlighter-rouge">\*</code> is sent only when the client certificate is requested.</p> <h3 id="troubleshooting">Troubleshooting</h3> <p>When authentication fails, the client does not have access to any details that explain the failure. The security reason for this omission is to prevent malicious reconnaissance. Instead, the details are recorded inside Kong’s error logs under the <code class="language-plaintext highlighter-rouge">[mtls-auth]</code> filter.</p> <h2 id="get-started-with-the-mtls-authentication-plugin">Get started with the mTLS Authentication plugin</h2> <ul> <li> <a href="/hub/kong-inc/mtls-auth/how-to/add-cert-authorities/">Add certificate authorities</a>: To use this plugin, you must add certificate authority (CA) certificates. Set them up before configuring the plugin.</li> <li><a href="/hub/kong-inc/mtls-auth/configuration/">Configuration reference</a></li> <li><a href="/hub/kong-inc/mtls-auth/how-to/basic-example/">Basic configuration example</a></li> <li><a href="/hub/kong-inc/mtls-auth/how-to/manual-mapping-cert-consumers/">Create manual mappings between certificate and consumer objects</a></li> </ul> <div class="book-nav-container"> <hr> <div class="book-nav next"> <span class="direction">Next</span> <a href="/hub/kong-inc/mtls-auth/configuration/">Mutual TLS Authentication Configuration</a> </div> </div> </div> </div> </div> </div> <div id="scroll-to-top-button"> <i class="fas fa-chevron-up"></i> </div> <div class="feedback-widget-container"> <input id="feedback-widget-checkbox" type="checkbox"> <label for="feedback-widget-checkbox"> <img src="/assets/images/icons/feedback-widget.svg" alt="Feedback widget"> </label> <div class="feedback-container"> <div class="feedback-thankyou"> Thank you for your feedback. </div> <div class="feedback-comment"> <textarea id="feedback-comment-text" rows="3" placeholder="Please let us know what we can improve on this page..."></textarea> <div class="feedback-comment-buttons"> <button id="feedback-comment-button-back">Back</button> <button id="feedback-comment-button-submit" class="button-primary">Submit</button> </div> </div> <div class="feedback-options"> <div class="feedback-options-title">Was this page useful?</div> <div class="feedback-options-buttons"> <i data-feedback-result="yes" class="feedback-options-button far fa-thumbs-up"></i> <i data-feedback-result="no" class="feedback-options-button far fa-thumbs-down"></i> </div> </div> </div> </div> </div> <div id="image-modal" data-image-expand-disabled=""> <div class="image-modal-backdrop"></div> <div class="image-container"> <img src="" alt=""> <i class="fa fa-times"></i> </div> </div> <footer class="marketing-footer--light-gray"> <section> <ul class="newsletter"> <li class="logo-wrapper"> <div class="logo"> <img src="/assets/images/logos/konglogo-light-theme-primary.svg" alt="Kong"> </div> <div class="footer-title">Powering the API world</div> <p> Increase developer productivity, security, and performance at scale with the unified platform for API management, service mesh, and ingress controller. </p> <div class="footer-form-container"> <form id="subscribe-form" method="POST" action="/assets/javascripts/subscribe.js"> <input required id="subscribe-input" type="email" name="email" placeholder="Email" aria-required="true" aria-invalid="false"> <input id="footer-form-button" type="submit" form="subscribe-form" value="Subscribe"> </form> <div id="form-response"></div> </div> </li> <li class="footer-columns"> <ul class="footer-columns-product-list"> <li> <nav> <div class="footer-category">Products</div> <ul> <li> <a href="https://konghq.com/products/kong-konnect" target="_blank" rel="noopener nofollow noreferrer ">Kong Konnect</a> </li> <li> <a href="https://konghq.com/products/kong-enterprise" target="_blank" rel="noopener nofollow noreferrer ">Kong Gateway Enterprise</a> </li> <li> <a href="https://konghq.com/products/kong-gateway" target="_blank" rel="noopener nofollow noreferrer ">Kong Gateway</a> </li> <li> <a href="https://konghq.com/products/kong-mesh" target="_blank" rel="noopener nofollow noreferrer ">Kong Mesh</a> </li> <li> <a href="https://konghq.com/products/kong-ingress-controller" target="_blank" rel="noopener nofollow noreferrer ">Kong Ingress Controller</a> </li> <li> <a href="https://insomnia.rest/" target="_blank" rel="noopener nofollow noreferrer noopener nofollow noreferrer">Kong Insomnia</a> </li> <li> <a href="https://konghq.com/product-updates" target="_blank" rel="noopener nofollow noreferrer ">Product Updates</a> </li> <li> <a href="https://konghq.com/contact-sales" target="_blank" rel="noopener nofollow noreferrer ">Get Started</a> </li> </ul> </nav> </li> <li> <nav> <div class="footer-category">Documentation</div> <ul> <li> <a href="/konnect/">Kong Konnect Docs</a> </li> <li> <a href="/gateway/latest/">Kong Gateway Docs</a> </li> <li> <a href="/gateway/latest/kong-enterprise/">Kong Gateway Enterprise Docs</a> </li> <li> <a href="/mesh/latest/">Kong Mesh Docs</a> </li> <li> <a href="https://docs.insomnia.rest/" target="_blank" rel="noopener nofollow noreferrer noopener nofollow noreferrer">Kong Insomnia Docs</a> </li> <li> <a href="/hub/">Kong Konnect Plugin Hub</a> </li> </ul> </nav> </li> <li> <nav> <div class="footer-category">Open Source</div> <ul> <li> <a href="https://konghq.com/install/#kong-community" target="_blank" rel="noopener nofollow noreferrer ">Kong Gateway</a> </li> <li> <a href="https://kuma.io/" target="_blank" rel="noopener nofollow noreferrer noopener nofollow noreferrer">Kuma</a> </li> <li> <a href="https://insomnia.rest/" target="_blank" rel="noopener nofollow noreferrer noopener nofollow noreferrer">Insomnia</a> </li> <li> <a href="https://konghq.com/community" target="_blank" rel="noopener nofollow noreferrer ">Kong Community</a> </li> </ul> </nav> </li> <li> <nav> <div class="footer-category">Company</div> <ul> <li> <a href="https://konghq.com/company/about-us" target="_blank" rel="noopener nofollow noreferrer ">About Kong</a> </li> <li> <a href="https://konghq.com/customers" target="_blank" rel="noopener nofollow noreferrer ">Customers</a> </li> <li> <a href="https://konghq.com/company/careers" target="_blank" rel="noopener nofollow noreferrer ">Careers</a> </li> <li> <a href="https://konghq.com/press-room" target="_blank" rel="noopener nofollow noreferrer ">Press</a> </li> <li> <a href="https://konghq.com/events" target="_blank" rel="noopener nofollow noreferrer ">Events</a> </li> <li> <a href="https://konghq.com/company/contact-us" target="_blank" rel="noopener nofollow noreferrer ">Contact</a> </li> </ul> </nav> </li> </ul> </li> </ul> </section> <section class="legal"> <div class="container d-flex"> <div class="social"> <div class="social-link"> <a href="https://www.facebook.com/konghq/" title="Facebook" target="_blank" rel="noopener nofollow noreferrer "><i aria-label="Facebook" class="fa fa-facebook-official" aria-hidden="true"></i></a> </div> <div class="social-link"> <a href="https://twitter.com/thekonginc" title="Twitter" target="_blank" rel="noopener nofollow noreferrer "><i aria-label="Twitter" class="fa fa-twitter" aria-hidden="true"></i></a> </div> <div class="social-link"> <a href="https://www.meetup.com/topics/kong/all/" title="Meetup" target="_blank" rel="noopener nofollow noreferrer "><i aria-label="Meetup" class="fa fa-meetup" aria-hidden="true"></i></a> </div> <div class="social-link"> <a href="https://linkedin.com/company/278819" title="LinkedIn" target="_blank" rel="noopener nofollow noreferrer "><i aria-label="GitHub" class="fa fa-linkedin" aria-hidden="true"></i></a> </div> <div class="social-link"> <a href="https://github.com/kong/kong" target="_blank" class="btn-gh" title="GitHub" rel="noopener nofollow noreferrer "> <i class="fa fa-github" aria-hidden="true" aria-label="GitHub"></i> </a> </div> </div> <ul> <li> <span class="mashape-footer-content"> <a href="https://konghq.com/legal/terms-of-use" target="_blank" rel="noopener nofollow noreferrer ">Terms</a><b>•</b> <a href="https://konghq.com/legal/privacy-policy" target="_blank" rel="noopener nofollow noreferrer ">Privacy</a><b>•</b> <a href="https://konghq.com/compliance" target="_blank" rel="noopener nofollow noreferrer ">Trust and Compliance</a> </span> </li> </ul> <div> <span>© Kong Inc. 2025 </span> </div> </div> </section> </footer> <script> var anchorForId = function (id) { var anchor = document.createElement("a"); anchor.className = "header-link"; anchor.href = "#" + id; anchor.innerHTML = "<i class=\"fa fa-link\"></i>"; anchor.title = `${id} Permalink`; return anchor; }; document.onreadystatechange = function () { if (this.readyState === "complete") { var className = ".show-anchor-links h1, .show-anchor-links h2, .show-anchor-links h3, " + ".show-anchor-links h4, .show-anchor-links h5, .show-anchor-links h6"; var headers = document.querySelectorAll(className); for (var i = 0; i < headers.length; i++) { var header = headers[i]; if (typeof header.id !== "undefined" && header.id !== "") { header.prepend(anchorForId(header.id)); } } } }; </script> <script> !function(){var i="analytics",analytics=window[i]=window[i]||[];if(!analytics.initialize)if(analytics.invoked)window.console&&console.error&&console.error("Segment snippet included twice.");else{analytics.invoked=!0;analytics.methods=["trackSubmit","trackClick","trackLink","trackForm","pageview","identify","reset","group","track","ready","alias","debug","page","screen","once","off","on","addSourceMiddleware","addIntegrationMiddleware","setAnonymousId","addDestinationMiddleware","register"];analytics.factory=function(e){return function(){if(window[i].initialized)return window[i][e].apply(window[i],arguments);var n=Array.prototype.slice.call(arguments);if(["track","screen","alias","group","page","identify"].indexOf(e)>-1){var c=document.querySelector("link[rel='canonical']");n.push({__t:"bpc",c:c&&c.getAttribute("href")||void 0,p:location.pathname,u:location.href,s:location.search,t:document.title,r:document.referrer})}n.unshift(e);analytics.push(n);return analytics}};for(var n=0;n<analytics.methods.length;n++){var key=analytics.methods[n];analytics[key]=analytics.factory(key)}analytics.load=function(key,n){var t=document.createElement("script");t.type="text/javascript";t.async=!0;t.setAttribute("data-global-segment-analytics-key",i);t.src="https://cdn.segment.com/analytics.js/v1/" + key + "/analytics.min.js";var r=document.getElementsByTagName("script")[0];r.parentNode.insertBefore(t,r);analytics._loadOptions=n};analytics._writeKey="X7EZTdbdUKQ8M6x42SHHPWiEhjsfs1EQ";;analytics.SNIPPET_VERSION="5.2.0"; analytics.load("X7EZTdbdUKQ8M6x42SHHPWiEhjsfs1EQ"); analytics.page(); }}(); </script> <div id="fb-root"></div> <script id="github-bjs" src="https://buttons.github.io/buttons.js" async defer></script> <script type="text/javascript"> var _vwo_code = (function() { var account_id = 125292, settings_tolerance = 2000, library_tolerance = 2500, use_existing_jquery = true, // DO NOT EDIT BELOW THIS LINE f = false, d = document; return { use_existing_jquery: function() { return use_existing_jquery; }, library_tolerance: function() { return library_tolerance; }, finish: function() { if (!f) { f = true; var a = d.getElementById('_vis_opt_path_hides'); if (a) a.parentNode.removeChild(a); } }, finished: function() { return f; }, load: function(a) { var b = d.createElement('script'); b.src = a; b.type = 'text/javascript'; b.innerText; b.onerror = function() { _vwo_code.finish(); }; d.getElementsByTagName('head')[0].appendChild(b); }, init: function() { settings_timer = setTimeout( '_vwo_code.finish()', settings_tolerance ); this.load( '//dev.visualwebsiteoptimizer.com/j.php?a=' + account_id + '&u=' + encodeURIComponent(d.URL) + '&r=' + Math.random() ); var a = d.createElement('style'), b = '', h = d.getElementsByTagName('head')[0]; a.setAttribute('id', '_vis_opt_path_hides'); a.setAttribute('type', 'text/css'); if (a.styleSheet) a.styleSheet.cssText = b; else a.appendChild(d.createTextNode(b)); h.appendChild(a); return settings_timer; } }; })(); _vwo_settings_timer = _vwo_code.init(); </script> <script src="https://cdn.jsdelivr.net/npm/@docsearch/js@3"></script> <script type="text/javascript"> docsearch({ appId: '05Y6TLHNFZ', apiKey: '80483bfe28d9fd036a11a6f6a06454f8', indexName: 'konghq', container: '#getkong-algolia-search-input', disableUserPersonalization: true, placeholder: 'Search the docs...', // Override selected event to allow for local environment navigation transformItems(items) { return items.map((item) => { var modifiedUrl = window.location.protocol + '//' + window.location.host + item.url.split('docs.konghq.com')[1]; return { ...item, url: modifiedUrl }; }); }, translations: { button: { buttonText: 'Search the docs..', buttonAriaLabel: 'Search the docs...' } }, resultsFooterComponent({ state }) { var facetParameters = {}; facetParameters = {"version[0]":"latest","product[0]":"Plugin Hub"}; var queryParams = new URLSearchParams(facetParameters); queryParams.set('query', state.query); return { // The HTML `tag` type: 'a', ref: undefined, constructor: undefined, key: state.query, // Its props props: { href: `/search/?${queryParams.toString()}`, target: '_blank', // Raw text rendered in the HTML element children: 'See more >' }, __v: null, }; }, searchParameters: { optionalFilters: ['product:Kong Konnect<score=1>', 'product:Kong Gateway<score=2>', 'product:Plugin Hub<score=3>'], facetFilters: [ 'version:latest'] } }); </script> <script> (function() { if (typeof window === 'undefined') return; if (typeof window.signals !== 'undefined') return; var script = document.createElement('script'); script.src = 'https://cdn.cr-relay.com/v1/site/993c7a0d-caec-465c-be46-2d3a78ab60c5/signals.js'; script.async = true; window.signals = Object.assign( [], ['page', 'identify', 'form'].reduce(function (acc, method){ acc[method] = function () { signals.push([method, arguments]); return signals; }; return acc; }, {}) ); document.head.appendChild(script); })(); </script> </body> </html>

CINXE.COM

Mutual TLS Authentication - Plugin | Kong Docs