kanidm/docs/v1.0.0rc3/integrations/ldap.html
2023-02-17 07:24:03 +00:00

355 lines
24 KiB
HTML

<!DOCTYPE HTML>
<html lang="en" class="sidebar-visible no-js light">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>LDAP - Kanidm Administration</title>
<!-- Custom HTML head -->
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#ffffff" />
<link rel="shortcut icon" href="../favicon.png">
<link rel="stylesheet" href="../css/variables.css">
<link rel="stylesheet" href="../css/general.css">
<link rel="stylesheet" href="../css/chrome.css">
<link rel="stylesheet" href="../css/print.css" media="print">
<!-- Fonts -->
<link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
<link rel="stylesheet" href="../fonts/fonts.css">
<!-- Highlight.js Stylesheets -->
<link rel="stylesheet" href="../highlight.css">
<link rel="stylesheet" href="../tomorrow-night.css">
<link rel="stylesheet" href="../ayu-highlight.css">
<!-- Custom theme stylesheets -->
</head>
<body>
<div id="body-container">
<!-- Provide site root to javascript -->
<script>
var path_to_root = "../";
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
</script>
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
var theme = localStorage.getItem('mdbook-theme');
var sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') && theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
</script>
<!-- Set the theme before any content is loaded, prevents flash -->
<script>
var theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
var html = document.querySelector('html');
html.classList.remove('no-js')
html.classList.remove('light')
html.classList.add(theme);
html.classList.add('js');
</script>
<!-- Hide / unhide sidebar before it is displayed -->
<script>
var html = document.querySelector('html');
var sidebar = 'hidden';
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
}
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<div class="sidebar-scrollbox">
<ol class="chapter"><li class="chapter-item expanded "><a href="../intro.html"><strong aria-hidden="true">1.</strong> Introduction to Kanidm</a></li><li class="chapter-item expanded "><a href="../installing_the_server.html"><strong aria-hidden="true">2.</strong> Installing the Server</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../choosing_a_domain_name.html"><strong aria-hidden="true">2.1.</strong> Choosing a Domain Name</a></li><li class="chapter-item expanded "><a href="../prepare_the_server.html"><strong aria-hidden="true">2.2.</strong> Preparing for your Deployment</a></li><li class="chapter-item expanded "><a href="../server_configuration.html"><strong aria-hidden="true">2.3.</strong> Server Configuration and Install</a></li><li class="chapter-item expanded "><a href="../server_update.html"><strong aria-hidden="true">2.4.</strong> Server Updates</a></li><li class="chapter-item expanded "><a href="../security_hardening.html"><strong aria-hidden="true">2.5.</strong> Platform Security Hardening</a></li></ol></li><li class="chapter-item expanded "><a href="../client_tools.html"><strong aria-hidden="true">3.</strong> Client Tools</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../installing_client_tools.html"><strong aria-hidden="true">3.1.</strong> Installing client tools</a></li></ol></li><li class="chapter-item expanded "><li class="part-title">Administration</li><li class="chapter-item expanded "><a href="../administrivia.html"><strong aria-hidden="true">4.</strong> Administration</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../accounts_and_groups.html"><strong aria-hidden="true">4.1.</strong> Accounts and Groups</a></li><li class="chapter-item expanded "><a href="../backup_restore.html"><strong aria-hidden="true">4.2.</strong> Backup and Restore</a></li><li class="chapter-item expanded "><a href="../database_maint.html"><strong aria-hidden="true">4.3.</strong> Database Maintenance</a></li><li class="chapter-item expanded "><a href="../domain_rename.html"><strong aria-hidden="true">4.4.</strong> Domain Rename</a></li><li class="chapter-item expanded "><a href="../monitoring.html"><strong aria-hidden="true">4.5.</strong> Monitoring the platform</a></li><li class="chapter-item expanded "><a href="../password_quality.html"><strong aria-hidden="true">4.6.</strong> Password Quality and Badlisting</a></li><li class="chapter-item expanded "><a href="../posix_accounts.html"><strong aria-hidden="true">4.7.</strong> POSIX Accounts and Groups</a></li><li class="chapter-item expanded "><a href="../ssh_key_dist.html"><strong aria-hidden="true">4.8.</strong> SSH Key Distribution</a></li><li class="chapter-item expanded "><a href="../recycle_bin.html"><strong aria-hidden="true">4.9.</strong> The Recycle Bin</a></li></ol></li><li class="chapter-item expanded "><a href="../troubleshooting.html"><strong aria-hidden="true">5.</strong> Troubleshooting</a></li><li class="chapter-item expanded "><a href="../frequently_asked_questions.html"><strong aria-hidden="true">6.</strong> Frequently Asked Questions</a></li><li class="chapter-item expanded "><a href="../glossary.html"><strong aria-hidden="true">7.</strong> Glossary of Technical Terms</a></li><li class="chapter-item expanded affix "><li class="part-title">Services</li><li class="chapter-item expanded "><a href="../integrations/oauth2.html"><strong aria-hidden="true">8.</strong> Oauth2</a></li><li class="chapter-item expanded "><a href="../integrations/pam_and_nsswitch.html"><strong aria-hidden="true">9.</strong> PAM and nsswitch</a></li><li class="chapter-item expanded "><a href="../integrations/radius.html"><strong aria-hidden="true">10.</strong> RADIUS</a></li><li class="chapter-item expanded "><a href="../integrations/ldap.html" class="active"><strong aria-hidden="true">11.</strong> LDAP</a></li><li class="chapter-item expanded affix "><li class="part-title">Synchronisation</li><li class="chapter-item expanded "><a href="../sync/concepts.html"><strong aria-hidden="true">12.</strong> Concepts</a></li><li class="chapter-item expanded "><a href="../sync/freeipa.html"><strong aria-hidden="true">13.</strong> FreeIPA</a></li><li class="chapter-item expanded affix "><li class="part-title">Integration Examples</li><li class="chapter-item expanded "><a href="../examples/k8s_ingress_example.html"><strong aria-hidden="true">14.</strong> Kubernetes Ingress</a></li><li class="chapter-item expanded "><a href="../integrations/traefik.html"><strong aria-hidden="true">15.</strong> Traefik</a></li><li class="chapter-item expanded affix "><li class="part-title">For Developers</li><li class="chapter-item expanded "><a href="../DEVELOPER_README.html"><strong aria-hidden="true">16.</strong> Developer Guide</a></li><li class="chapter-item expanded "><div><strong aria-hidden="true">17.</strong> Design Documents</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="../developers/designs/access_profiles_rework_2022.html"><strong aria-hidden="true">17.1.</strong> Access Profiles 2022</a></li><li class="chapter-item expanded "><a href="../developers/designs/access_profiles_and_security.html"><strong aria-hidden="true">17.2.</strong> Access Profiles Original</a></li><li class="chapter-item expanded "><a href="../developers/designs/rest_interface.html"><strong aria-hidden="true">17.3.</strong> REST Interface</a></li></ol></li><li class="chapter-item expanded "><a href="../developers/python.html"><strong aria-hidden="true">18.</strong> Python Module</a></li><li class="chapter-item expanded "><a href="../developers/radius.html"><strong aria-hidden="true">19.</strong> RADIUS Integration</a></li><li class="chapter-item expanded "><a href="../packaging.html"><strong aria-hidden="true">20.</strong> Packaging</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../packaging_debs.html"><strong aria-hidden="true">20.1.</strong> Debian/Ubuntu</a></li></ol></li></ol>
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
</nav>
<div id="page-wrapper" class="page-wrapper">
<div class="page">
<div id="menu-bar-hover-placeholder"></div>
<div id="menu-bar" class="menu-bar sticky bordered">
<div class="left-buttons">
<button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</button>
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
<i class="fa fa-paint-brush"></i>
</button>
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
</ul>
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
<i class="fa fa-search"></i>
</button>
</div>
<h1 class="menu-title">Kanidm Administration</h1>
<div class="right-buttons">
<a href="../print.html" title="Print this book" aria-label="Print this book">
<i id="print-button" class="fa fa-print"></i>
</a>
<a href="https://github.com/kanidm/kanidm" title="Git repository" aria-label="Git repository">
<i id="git-repository-button" class="fa fa-github"></i>
</a>
<a href="https://github.com/kanidm/kanidm/edit/master/kanidm_book/src/integrations/ldap.md" title="Suggest an edit" aria-label="Suggest an edit">
<i id="git-edit-button" class="fa fa-edit"></i>
</a>
</div>
</div>
<div id="search-wrapper" class="hidden">
<form id="searchbar-outer" class="searchbar-outer">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
</form>
<div id="searchresults-outer" class="searchresults-outer hidden">
<div id="searchresults-header" class="searchresults-header"></div>
<ul id="searchresults">
</ul>
</div>
</div>
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
<script>
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
</script>
<div id="content" class="content">
<main>
<h1 id="ldap"><a class="header" href="#ldap">LDAP</a></h1>
<p>While many applications can support external authentication and identity services through Oauth2,
not all services can. Lightweight Directory Access Protocol (LDAP) has been the &quot;lingua franca&quot; of
authentication for many years, with almost every application in the world being able to search and
bind to LDAP. As many organisations still rely on LDAP, Kanidm can host a read-only LDAP interface
for these legacy applications.</p>
<!-- deno-fmt-ignore-start -->
<table>
<tr>
<td rowspan=2><img src="../images/kani-warning.png" alt="Kani Warning" /></td>
<td><strong>Warning!</strong></td>
</tr>
<tr>
<td>The LDAP server in Kanidm is not a fully RFC-compliant LDAP server. This is intentional, as Kanidm wants to cover the common use cases - simple bind and search.</td>
</tr>
</table>
<!-- deno-fmt-ignore-end -->
<h2 id="what-is-ldap"><a class="header" href="#what-is-ldap">What is LDAP</a></h2>
<p>LDAP is a protocol to read data from a directory of information. It is not a server, but a way to
communicate to a server. There are many famous LDAP implementations such as Active Directory, 389
Directory Server, DSEE, FreeIPA, and many others. Because it is a standard, applications can use an
LDAP client library to authenticate users to LDAP, given &quot;one account&quot; for many applications - an
IDM just like Kanidm!</p>
<h2 id="data-mapping"><a class="header" href="#data-mapping">Data Mapping</a></h2>
<p>Kanidm cannot be mapped 100% to LDAP's objects. This is because LDAP types are simple key-values on
objects which are all UTF8 strings (or subsets thereof) based on validation (matching) rules. Kanidm
internally implements complex data types such as tagging on SSH keys, or multi-value credentials.
These can not be represented in LDAP.</p>
<p>Many of the structures in Kanidm do not correlate closely to LDAP. For example Kanidm only has a GID
number, where LDAP's schemas define both a UID number and a GID number.</p>
<p>Entries in the database also have a specific name in LDAP, related to their path in the directory
tree. Kanidm is a flat model, so we have to emulate some tree-like elements, and ignore others.</p>
<p>For this reason, when you search the LDAP interface, Kanidm will make some mapping decisions.</p>
<ul>
<li>The Kanidm domain name is used to generate the DN of the suffix.</li>
<li>The domain_info object becomes the suffix root.</li>
<li>All other entries are direct subordinates of the domain_info for DN purposes.</li>
<li>Distinguished Names (DNs) are generated from the spn, name, or uuid attribute.</li>
<li>Bind DNs can be remapped and rewritten, and may not even be a DN during bind.</li>
<li>The '*' and '+' operators can not be used in conjunction with attribute lists in searches.</li>
</ul>
<p>These decisions were made to make the path as simple and effective as possible, relying more on the
Kanidm query and filter system than attempting to generate a tree-like representation of data. As
almost all clients can use filters for entry selection we don't believe this is a limitation for the
consuming applications.</p>
<h2 id="security"><a class="header" href="#security">Security</a></h2>
<h3 id="tls"><a class="header" href="#tls">TLS</a></h3>
<p>StartTLS is not supported due to security risks. LDAPS is the only secure method of communicating to
any LDAP server. Kanidm, when configured with certificates, will use them for LDAPS (and will not
listen on a plaintext LDAP port).</p>
<h3 id="writes"><a class="header" href="#writes">Writes</a></h3>
<p>LDAP's structure is too simplistic for writing to the complex entries that Kanidm internally
contains. As a result, writes are rejected for all users via the LDAP interface.</p>
<h3 id="access-controls"><a class="header" href="#access-controls">Access Controls</a></h3>
<p>LDAP only supports password authentication. As LDAP is used heavily in POSIX environments the LDAP
bind for any DN will use its configured posix password.</p>
<p>As the POSIX password is not equivalent in strength to the primary credentials of Kanidm (which may
be multi-factor authentication, MFA), the LDAP bind does not grant rights to elevated read
permissions. All binds have the permissions of &quot;Anonymous&quot; even if the anonymous account is locked.</p>
<p>The exception is service accounts which can use api-tokens during an LDAP bind for elevated read
permissions.</p>
<h2 id="server-configuration"><a class="header" href="#server-configuration">Server Configuration</a></h2>
<p>To configure Kanidm to provide LDAP, add the argument to the <code>server.toml</code> configuration:</p>
<pre><code class="language-toml">ldapbindaddress = &quot;127.0.0.1:3636&quot;
</code></pre>
<p>You should configure TLS certificates and keys as usual - LDAP will re-use the Web server TLS
material.</p>
<h2 id="showing-ldap-entries-and-attribute-maps"><a class="header" href="#showing-ldap-entries-and-attribute-maps">Showing LDAP Entries and Attribute Maps</a></h2>
<p>By default Kanidm is limited in what attributes are generated or remapped into LDAP entries.
However, the server internally contains a map of extended attribute mappings for application
specific requests that must be satisfied.</p>
<p>An example is that some applications expect and require a 'CN' value, even though Kanidm does not
provide it. If the application is unable to be configured to accept &quot;name&quot; it may be necessary to
use Kanidm's mapping feature. Currently these are compiled into the server, so you may need to open
an issue with your requirements for attribute maps.</p>
<p>To show what attribute maps exists for an entry you can use the attribute search term '+'.</p>
<pre><code class="language-bash"># To show Kanidm attributes
ldapsearch ... -x '(name=admin)' '*'
# To show all attribute maps
ldapsearch ... -x '(name=admin)' '+'
</code></pre>
<p>Attributes that are in the map can be requested explicitly, and this can be combined with requesting
Kanidm native attributes.</p>
<pre><code class="language-bash">ldapsearch ... -x '(name=admin)' cn objectClass displayname memberof
</code></pre>
<h2 id="service-accounts"><a class="header" href="#service-accounts">Service Accounts</a></h2>
<p>If you have
<a href="../accounts_and_groups.html#using-api-tokens-with-service-accounts">issued api tokens for a service account</a>
they can be used to gain extended read permissions for those service accounts.</p>
<p>Api tokens can also be used to gain extended search permissions with LDAP. To do this you can bind
with a dn of <code>dn=token</code> and provide the api token in the password.</p>
<blockquote>
<p><strong>NOTE</strong> The <code>dn=token</code> keyword is guaranteed to not be used by any other entry, which is why it
was chosen as the keyword to initiate api token binds.</p>
</blockquote>
<pre><code class="language-bash">ldapwhoami -H ldaps://URL -x -D &quot;dn=token&quot; -w &quot;TOKEN&quot;
ldapwhoami -H ldaps://idm.example.com -x -D &quot;dn=token&quot; -w &quot;...&quot;
# u: demo_service@idm.example.com
</code></pre>
<h2 id="example"><a class="header" href="#example">Example</a></h2>
<p>Given a default install with domain &quot;example.com&quot; the configured LDAP DN will be
&quot;dc=example,dc=com&quot;.</p>
<pre><code class="language-toml"># from server.toml
ldapbindaddress = &quot;[::]:3636&quot;
</code></pre>
<p>This can be queried with:</p>
<pre><code class="language-bash">LDAPTLS_CACERT=ca.pem ldapsearch \
-H ldaps://127.0.0.1:3636 \
-b 'dc=example,dc=com' \
-x '(name=test1)'
# test1@example.com, example.com
dn: spn=test1@example.com,dc=example,dc=com
objectclass: account
objectclass: memberof
objectclass: object
objectclass: person
displayname: Test User
memberof: spn=group240@example.com,dc=example,dc=com
name: test1
spn: test1@example.com
entryuuid: 22a65b6c-80c8-4e1a-9b76-3f3afdff8400
</code></pre>
<p>It is recommended that client applications filter accounts that can login with <code>(class=account)</code> and
groups with <code>(class=group)</code>. If possible, group membership is defined in RFC2307bis or Active
Directory style. This means groups are determined from the &quot;memberof&quot; attribute which contains a DN
to a group.</p>
<p>LDAP binds can use any unique identifier of the account. The following are all valid bind DNs for
the object listed above (if it was a POSIX account, that is).</p>
<pre><code class="language-bash">ldapwhoami ... -x -D 'name=test1'
ldapwhoami ... -x -D 'spn=test1@example.com'
ldapwhoami ... -x -D 'test1@example.com'
ldapwhoami ... -x -D 'test1'
ldapwhoami ... -x -D '22a65b6c-80c8-4e1a-9b76-3f3afdff8400'
ldapwhoami ... -x -D 'spn=test1@example.com,dc=example,dc=com'
ldapwhoami ... -x -D 'name=test1,dc=example,dc=com'
</code></pre>
<p>Most LDAP clients are very picky about TLS, and can be very hard to debug or display errors. For
example these commands:</p>
<pre><code class="language-bash">ldapsearch -H ldaps://127.0.0.1:3636 -b 'dc=example,dc=com' -x '(name=test1)'
ldapsearch -H ldap://127.0.0.1:3636 -b 'dc=example,dc=com' -x '(name=test1)'
ldapsearch -H ldap://127.0.0.1:3389 -b 'dc=example,dc=com' -x '(name=test1)'
</code></pre>
<p>All give the same error:</p>
<pre><code class="language-bash">ldap_sasl_bind(SIMPLE): Can't contact LDAP server (-1)
</code></pre>
<p>This is despite the fact:</p>
<ul>
<li>The first command is a certificate validation error.</li>
<li>The second is a missing LDAPS on a TLS port.</li>
<li>The third is an incorrect port.</li>
</ul>
<p>To diagnose errors like this, you may need to add &quot;-d 1&quot; to your LDAP commands or client.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../integrations/radius.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next" href="../sync/concepts.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
<div style="clear: both"></div>
</nav>
</div>
</div>
<nav class="nav-wide-wrapper" aria-label="Page navigation">
<a rel="prev" href="../integrations/radius.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next" href="../sync/concepts.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
</nav>
</div>
<script>
window.playground_copyable = true;
</script>
<script src="../elasticlunr.min.js"></script>
<script src="../mark.min.js"></script>
<script src="../searcher.js"></script>
<script src="../clipboard.min.js"></script>
<script src="../highlight.js"></script>
<script src="../book.js"></script>
<!-- Custom JS scripts -->
</div>
</body>
</html>