mart-w/kanidm
1
0
Fork 0
mirror of https://github.com/kanidm/kanidm.git synced 2025-02-24 21:17:01 +01:00
Code Issues Actions 10 Packages Projects Releases Wiki Activity
kanidm/docs/v1.1.0-alpha.5/sync/freeipa.html
Firstyear 3c180ed320 deploy: def8f3f1bd
2022-12-22 08:19:07 +00:00

303 lines
21 KiB
HTML
Raw Blame History

<!DOCTYPE HTML>
<html lang="en" class="sidebar-visible no-js light">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>FreeIPA - 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>
<!-- 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="../frequently_asked_questions.html"><strong aria-hidden="true">2.</strong> Frequently Asked Questions</a></li><li class="chapter-item expanded "><a href="../installing_the_server.html"><strong aria-hidden="true">3.</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">3.1.</strong> Choosing a Domain Name</a></li><li class="chapter-item expanded "><a href="../prepare_the_server.html"><strong aria-hidden="true">3.2.</strong> Preparing for your Deployment</a></li><li class="chapter-item expanded "><a href="../server_configuration.html"><strong aria-hidden="true">3.3.</strong> Server Configuration and Install</a></li><li class="chapter-item expanded "><a href="../server_update.html"><strong aria-hidden="true">3.4.</strong> Server Updates</a></li><li class="chapter-item expanded "><a href="../security_hardening.html"><strong aria-hidden="true">3.5.</strong> Platform Security Hardening</a></li></ol></li><li class="chapter-item expanded "><a href="../client_tools.html"><strong aria-hidden="true">4.</strong> Client Tools</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../installing_client_tools.html"><strong aria-hidden="true">4.1.</strong> Installing client tools</a></li></ol></li><li class="chapter-item expanded "><a href="../administrivia.html"><strong aria-hidden="true">5.</strong> Administration</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../accounts_and_groups.html"><strong aria-hidden="true">5.1.</strong> Accounts and Groups</a></li><li class="chapter-item expanded "><a href="../backup_restore.html"><strong aria-hidden="true">5.2.</strong> Backup and Restore</a></li><li class="chapter-item expanded "><a href="../database_maint.html"><strong aria-hidden="true">5.3.</strong> Database Maintenance</a></li><li class="chapter-item expanded "><a href="../domain_rename.html"><strong aria-hidden="true">5.4.</strong> Domain Rename</a></li><li class="chapter-item expanded "><a href="../monitoring.html"><strong aria-hidden="true">5.5.</strong> Monitoring the platform</a></li><li class="chapter-item expanded "><a href="../password_quality.html"><strong aria-hidden="true">5.6.</strong> Password Quality and Badlisting</a></li><li class="chapter-item expanded "><a href="../posix_accounts.html"><strong aria-hidden="true">5.7.</strong> POSIX Accounts and Groups</a></li><li class="chapter-item expanded "><a href="../ssh_key_dist.html"><strong aria-hidden="true">5.8.</strong> SSH Key Distribution</a></li><li class="chapter-item expanded "><a href="../recycle_bin.html"><strong aria-hidden="true">5.9.</strong> The Recycle Bin</a></li><li class="chapter-item expanded "><a href="../why_tls.html"><strong aria-hidden="true">5.10.</strong> Why TLS?</a></li></ol></li><li class="chapter-item expanded "><a href="../troubleshooting.html"><strong aria-hidden="true">6.</strong> Troubleshooting</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"><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" class="active"><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/sync/freeipa.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="synchronising-from-freeipa"><a class="header" href="#synchronising-from-freeipa">Synchronising from FreeIPA</a></h1>
<p>FreeIPA is a popular opensource LDAP and Kerberos provider, aiming to be &quot;Active Directory&quot; for
Linux.</p>
<p>Kanidm is able to synchronise from FreeIPA for the purposes of coexistence or migration.</p>
<h2 id="installing-the-freeipa-sync-tool"><a class="header" href="#installing-the-freeipa-sync-tool">Installing the FreeIPA Sync Tool</a></h2>
<p>See <a href="../installing_client_tools.html">installing the client tools</a>.</p>
<h2 id="configure-the-freeipa-sync-tool"><a class="header" href="#configure-the-freeipa-sync-tool">Configure the FreeIPA Sync Tool</a></h2>
<p>The sync tool is a bridge between FreeIPA and Kanidm, meaning that the tool must be configured to
communicate to both sides.</p>
<p>Like other components of Kanidm, the FreeIPA sync tool will read your /etc/kanidm/config if present
to understand how to connect to Kanidm.</p>
<p>The sync tool specific components are configured in it's own configuration file.</p>
<pre><code>
# The sync account token as generated by &quot;system sync generate-token&quot;.
sync_token = &quot;eyJhb...&quot;
# A cron-like expression of when to run when in scheduled mode. The format is:
# sec min hour day of month month day of week year
#
# The default of this value is &quot;0 */5 * * * * *&quot; which means &quot;run every 5 minutes&quot;.
# schedule = &quot;&quot;
# If you want to monitor the status of the scheduled sync tool (you should)
# then you can set a bind address here.
#
# If not set, defaults to no status listener.
# status_bind = &quot;&quot;
# The LDAP URI to FreeIPA. This MUST be LDAPS. You should connect to a unique single
# server in the IPA topology rather than via a load balancer or dns srv records. This
# is to prevent replication conflicts and issues due to how 389-ds content sync works.
ipa_uri = &quot;ldaps://specific-server.ipa.dev.kanidm.com&quot;
# Path to the IPA CA certificate in PEM format.
ipa_ca = &quot;/path/to/kanidm-ipa-ca.pem&quot;
# The DN of an account with content sync rights. By default cn=Directory Manager has
# this access.
ipa_sync_dn = &quot;cn=Directory Manager&quot;
ipa_sync_pw = &quot;directory manager password&quot;
# The basedn to examine.
ipa_sync_base_dn = &quot;dc=ipa,dc=dev,dc=kanidm,dc=com&quot;
# The sync tool can alter or exclude entries. These are mapped by their syncuuid
# (not their ipa-object-uuid). The syncuuid is derived from nsUniqueId in 389-ds.
# This is chosen oven DN because DN's can change with modrdn where nsUniqueId is
# immutable and requires an entry to be deleted and recreated.
[ac60034b-3498-11ed-a50d-919b4b1a5ec0]
# my-problematic-entry
exclude = true
</code></pre>
<p>This example is located in <a href="https://github.com/kanidm/kanidm/blob/master/examples/kanidm-ipa-sync">examples/kanidm-ipa-sync</a>.</p>
<p>In addition to this, you must make some configuration changes to FreeIPA to enable synchronisation.</p>
<p>You can find the name of your 389 Directory Server instance with:</p>
<pre><code>dsconf --list
</code></pre>
<p>Using this you can show the current status of the retro changelog plugin to see if you need
to change it's configuration.</p>
<pre><code>dsconf &lt;instance name&gt; plugin retro-changelog show
dsconf slapd-DEV-KANIDM-COM plugin retro-changelog show
</code></pre>
<p>You must modify the retro changelog plugin to include the full scope of the database suffix so that
the sync tool can view the changes to the database. Currently dsconf can not modify the include-suffix
so you must do this manually.</p>
<p>You need to change the <code>nsslapd-include-suffix</code> to match your FreeIPA baseDN here. You can
access the basedn with:</p>
<pre><code>ldapsearch -H ldaps://&lt;IPA SERVER HOSTNAME/IP&gt; -x -b '' -s base namingContexts
# namingContexts: dc=ipa,dc=dev,dc=kanidm,dc=com
</code></pre>
<p>You should ignore <code>cn=changelog</code> and <code>o=ipaca</code> as these are system internal namingContexts. You
can then create an ldapmodify like the following.</p>
<pre><code>dn: cn=Retro Changelog Plugin,cn=plugins,cn=config
changetype: modify
replace: nsslapd-include-suffix
nsslapd-include-suffix: dc=ipa,dc=dev,dc=kanidm,dc=com
</code></pre>
<p>And apply it with:</p>
<pre><code>ldapmodify -f change.ldif -H ldaps://&lt;IPA SERVER HOSTNAME/IP&gt; -x -D 'cn=Directory Manager' -W
# Enter LDAP Password:
</code></pre>
<p>You must then reboot your FreeIPA server.</p>
<h2 id="running-the-sync-tool-manually"><a class="header" href="#running-the-sync-tool-manually">Running the Sync Tool Manually</a></h2>
<p>You can perform a dry run with the sync tool manually to check your configurations are
correct and that the tool can synchronise from FreeIPA.</p>
<pre><code>kanidm-ipa-sync [-c /path/to/kanidm/config] -i /path/to/kanidm-ipa-sync -n
kanidm-ipa-sync -i /etc/kanidm/ipa-sync -n
</code></pre>
<h2 id="running-the-sync-tool-automatically"><a class="header" href="#running-the-sync-tool-automatically">Running the Sync Tool Automatically</a></h2>
<p>The sync tool can be run on a schedule if you configure the <code>schedule</code> parameter, and provide
the option &quot;--schedule&quot; on the cli</p>
<pre><code>kanidm-ipa-sync [-c /path/to/kanidm/config] -i /path/to/kanidm-ipa-sync --schedule
</code></pre>
<h2 id="monitoring-the-sync-tool"><a class="header" href="#monitoring-the-sync-tool">Monitoring the Sync Tool</a></h2>
<p>When running in schedule mode, you may wish to monitor the sync tool for failures. Since failures
block the sync process, this is important to ensuring a smooth and reliable synchronisation process.</p>
<p>You can configure a status listener that can be monitored via tcp with the parameter <code>status_bind</code>.</p>
<p>An example of monitoring this with netcat is:</p>
<pre><code># status_bind = &quot;[::1]:12345&quot;
# nc ::1 12345
Ok
</code></pre>
<p>It's important to note no details are revealed via the status socket, and is purely for Ok or Err status
of the last sync.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../sync/concepts.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="../examples/k8s_ingress_example.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="../sync/concepts.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="../examples/k8s_ingress_example.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 -->
</body>
</html>
Reference in a new issue View git blame Copy permalink