mirror of
https://github.com/kanidm/kanidm.git
synced 2025-02-23 20:47:01 +01:00
567 lines
38 KiB
HTML
567 lines
38 KiB
HTML
<!DOCTYPE HTML>
|
|
<html lang="en" class="sidebar-visible no-js light">
|
|
<head>
|
|
<!-- Book generated using mdBook -->
|
|
<meta charset="UTF-8">
|
|
<title>PAM and nsswitch - 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 = null;
|
|
if (document.body.clientWidth >= 1080) {
|
|
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
|
|
sidebar = sidebar || 'visible';
|
|
} else {
|
|
sidebar = 'hidden';
|
|
}
|
|
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="../security_hardening.html"><strong aria-hidden="true">2.4.</strong> Platform Security Hardening</a></li><li class="chapter-item expanded "><a href="../server_update.html"><strong aria-hidden="true">2.5.</strong> Server Updates</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="../authentication.html"><strong aria-hidden="true">4.2.</strong> Authentication and Credentials</a></li><li class="chapter-item expanded "><a href="../posix_accounts.html"><strong aria-hidden="true">4.3.</strong> POSIX Accounts and Groups</a></li><li class="chapter-item expanded "><a href="../backup_restore.html"><strong aria-hidden="true">4.4.</strong> Backup and Restore</a></li><li class="chapter-item expanded "><a href="../database_maint.html"><strong aria-hidden="true">4.5.</strong> Database Maintenance</a></li><li class="chapter-item expanded "><a href="../domain_rename.html"><strong aria-hidden="true">4.6.</strong> Domain Rename</a></li><li class="chapter-item expanded "><a href="../monitoring.html"><strong aria-hidden="true">4.7.</strong> Monitoring the platform</a></li><li class="chapter-item expanded "><a href="../password_quality.html"><strong aria-hidden="true">4.8.</strong> Password Quality and Badlisting</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 "><li class="part-title">Services</li><li class="chapter-item expanded "><a href="../integrations/pam_and_nsswitch.html" class="active"><strong aria-hidden="true">5.</strong> PAM and nsswitch</a></li><li class="chapter-item expanded "><a href="../ssh_key_dist.html"><strong aria-hidden="true">6.</strong> SSH Key Distribution</a></li><li class="chapter-item expanded "><a href="../integrations/oauth2.html"><strong aria-hidden="true">7.</strong> Oauth2</a></li><li class="chapter-item expanded "><a href="../integrations/ldap.html"><strong aria-hidden="true">8.</strong> LDAP</a></li><li class="chapter-item expanded "><a href="../integrations/radius.html"><strong aria-hidden="true">9.</strong> RADIUS</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">10.</strong> Concepts</a></li><li class="chapter-item expanded "><a href="../sync/freeipa.html"><strong aria-hidden="true">11.</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">12.</strong> Kubernetes Ingress</a></li><li class="chapter-item expanded "><a href="../integrations/traefik.html"><strong aria-hidden="true">13.</strong> Traefik</a></li><li class="chapter-item expanded affix "><li class="part-title">Support</li><li class="chapter-item expanded "><a href="../troubleshooting.html"><strong aria-hidden="true">14.</strong> Troubleshooting</a></li><li class="chapter-item expanded "><a href="../frequently_asked_questions.html"><strong aria-hidden="true">15.</strong> Frequently Asked Questions</a></li><li class="chapter-item expanded "><a href="../glossary.html"><strong aria-hidden="true">16.</strong> Glossary of Technical Terms</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">17.</strong> Developer Guide</a></li><li class="chapter-item expanded "><a href="../developers/faq.html"><strong aria-hidden="true">18.</strong> FAQ</a></li><li class="chapter-item expanded "><div><strong aria-hidden="true">19.</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">19.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">19.2.</strong> Access Profiles Original</a></li><li class="chapter-item expanded "><a href="../developers/designs/rest_interface.html"><strong aria-hidden="true">19.3.</strong> REST Interface</a></li><li class="chapter-item expanded "><a href="../developers/designs/elevated_priv_mode.html"><strong aria-hidden="true">19.4.</strong> Elevated Priv Mode</a></li><li class="chapter-item expanded "><a href="../developers/designs/oauth2_refresh_tokens.html"><strong aria-hidden="true">19.5.</strong> Oauth2 Refresh Tokens</a></li></ol></li><li class="chapter-item expanded "><a href="../developers/python.html"><strong aria-hidden="true">20.</strong> Python Module</a></li><li class="chapter-item expanded "><a href="../developers/radius.html"><strong aria-hidden="true">21.</strong> RADIUS Integration</a></li><li class="chapter-item expanded "><a href="../packaging.html"><strong aria-hidden="true">22.</strong> Packaging</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../packaging_debs.html"><strong aria-hidden="true">22.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/book/src/integrations/pam_and_nsswitch.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="pam-and-nsswitch"><a class="header" href="#pam-and-nsswitch">PAM and nsswitch</a></h1>
|
|
<p><a href="http://linux-pam.org">PAM</a> and <a href="https://en.wikipedia.org/wiki/Name_Service_Switch">nsswitch</a> are
|
|
the core mechanisms used by Linux and BSD clients to resolve identities from an IDM service like
|
|
Kanidm into accounts that can be used on the machine for various interactive tasks.</p>
|
|
<h2 id="the-unix-daemon"><a class="header" href="#the-unix-daemon">The UNIX Daemon</a></h2>
|
|
<p>Kanidm provides a UNIX daemon that runs on any client that wants to use PAM and nsswitch
|
|
integration. The daemon can cache the accounts for users who have unreliable networks, or who leave
|
|
the site where Kanidm is hosted. The daemon is also able to cache missing-entry responses to reduce
|
|
network traffic and main server load.</p>
|
|
<p>Additionally, running the daemon means that the PAM and nsswitch integration libraries can be small,
|
|
helping to reduce the attack surface of the machine. Similarly, a tasks daemon is available that can
|
|
create home directories on first login and supports several features related to aliases and links to
|
|
these home directories.</p>
|
|
<p>We recommend you install the client daemon from your system package manager:</p>
|
|
<pre><code class="language-bash"># OpenSUSE
|
|
zypper in kanidm-unixd-clients
|
|
# Fedora
|
|
dnf install kanidm-unixd-clients
|
|
</code></pre>
|
|
<p>You can check the daemon is running on your Linux system with:</p>
|
|
<pre><code class="language-bash">systemctl status kanidm-unixd
|
|
</code></pre>
|
|
<p>You can check the privileged tasks daemon is running with:</p>
|
|
<pre><code class="language-bash">systemctl status kanidm-unixd-tasks
|
|
</code></pre>
|
|
<blockquote>
|
|
<p><strong>NOTE</strong> The <code>kanidm_unixd_tasks</code> daemon is not required for PAM and nsswitch functionality. If
|
|
disabled, your system will function as usual. It is, however, recommended due to the features it
|
|
provides supporting Kanidm's capabilities.</p>
|
|
</blockquote>
|
|
<p>Both unixd daemons use the connection configuration from /etc/kanidm/config. This is the covered in
|
|
<a href="../client_tools.html#kanidm-configuration">client_tools</a>.</p>
|
|
<p>You can also configure some unixd-specific options with the file /etc/kanidm/unixd:</p>
|
|
<pre><code class="language-toml">pam_allowed_login_groups = ["posix_group"]
|
|
default_shell = "/bin/sh"
|
|
home_prefix = "/home/"
|
|
home_attr = "uuid"
|
|
home_alias = "spn"
|
|
use_etc_skel = false
|
|
uid_attr_map = "spn"
|
|
gid_attr_map = "spn"
|
|
</code></pre>
|
|
<p><code>pam_allowed_login_groups</code> defines a set of POSIX groups where membership of any of these groups
|
|
will be allowed to login via PAM. All POSIX users and groups can be resolved by nss regardless of
|
|
PAM login status. This may be a group name, spn, or uuid.</p>
|
|
<p><code>default_shell</code> is the default shell for users. Defaults to <code>/bin/sh</code>.</p>
|
|
<p><code>home_prefix</code> is the prepended path to where home directories are stored. Must end with a trailing
|
|
<code>/</code>. Defaults to <code>/home/</code>.</p>
|
|
<p><code>home_attr</code> is the default token attribute used for the home directory path. Valid choices are
|
|
<code>uuid</code>, <code>name</code>, <code>spn</code>. Defaults to <code>uuid</code>.</p>
|
|
<p><code>home_alias</code> is the default token attribute used for generating symlinks pointing to the user's home
|
|
directory. If set, this will become the value of the home path to nss calls. It is recommended you
|
|
choose a "human friendly" attribute here. Valid choices are <code>none</code>, <code>uuid</code>, <code>name</code>, <code>spn</code>. Defaults
|
|
to <code>spn</code>.</p>
|
|
<blockquote>
|
|
<p><strong>NOTICE:</strong> All users in Kanidm can change their name (and their spn) at any time. If you change
|
|
<code>home_attr</code> from <code>uuid</code> you <em>must</em> have a plan on how to manage these directory renames in your
|
|
system. We recommend that you have a stable ID (like the UUID), and symlinks from the name to the
|
|
UUID folder. Automatic support is provided for this via the unixd tasks daemon, as documented
|
|
here.</p>
|
|
</blockquote>
|
|
<p><code>use_etc_skel</code> controls if home directories should be prepopulated with the contents of <code>/etc/skel</code>
|
|
when first created. Defaults to false.</p>
|
|
<p><code>uid_attr_map</code> chooses which attribute is used for domain local users in presentation. Defaults to
|
|
<code>spn</code>. Users from a trust will always use spn.</p>
|
|
<p><code>gid_attr_map</code> chooses which attribute is used for domain local groups in presentation. Defaults to
|
|
<code>spn</code>. Groups from a trust will always use spn.</p>
|
|
<p>You can then check the communication status of the daemon:</p>
|
|
<pre><code class="language-bash">kanidm-unix status
|
|
</code></pre>
|
|
<p>If the daemon is working, you should see:</p>
|
|
<pre><code>working!
|
|
</code></pre>
|
|
<p>If it is not working, you will see an error message:</p>
|
|
<pre><code>[2020-02-14T05:58:10Z ERROR kanidm-unix] Error ->
|
|
Os { code: 111, kind: ConnectionRefused, message: "Connection refused" }
|
|
</code></pre>
|
|
<p>For more information, see the <a href="./pam_and_nsswitch.html#troubleshooting">Troubleshooting</a> section.</p>
|
|
<h2 id="nsswitch"><a class="header" href="#nsswitch">nsswitch</a></h2>
|
|
<p>When the daemon is running you can add the nsswitch libraries to /etc/nsswitch.conf</p>
|
|
<pre><code>passwd: compat kanidm
|
|
group: compat kanidm
|
|
</code></pre>
|
|
<p>You can <a href="../accounts_and_groups.html#creating-accounts">create a user</a> then
|
|
<a href="../posix_accounts.html#enabling-posix-attributes-on-accounts">enable POSIX feature on the user</a>.</p>
|
|
<p>You can then test that the POSIX extended user is able to be resolved with:</p>
|
|
<pre><code class="language-bash">getent passwd <account name>
|
|
getent passwd testunix
|
|
testunix:x:3524161420:3524161420:testunix:/home/testunix:/bin/sh
|
|
</code></pre>
|
|
<p>You can also do the same for groups.</p>
|
|
<pre><code class="language-bash">getent group <group name>
|
|
getent group testgroup
|
|
testgroup:x:2439676479:testunix
|
|
</code></pre>
|
|
<blockquote>
|
|
<p><strong>HINT</strong> Remember to also create a UNIX password with something like
|
|
<code>kanidm account posix set_password --name idm_admin demo_user</code>. Otherwise there will be no
|
|
credential for the account to authenticate.</p>
|
|
</blockquote>
|
|
<h2 id="pam"><a class="header" href="#pam">PAM</a></h2>
|
|
<blockquote>
|
|
<p><strong>WARNING:</strong> Modifications to PAM configuration <em>may</em> leave your system in a state where you are
|
|
unable to login or authenticate. You should always have a recovery shell open while making changes
|
|
(for example, root), or have access to single-user mode at the machine's console.</p>
|
|
</blockquote>
|
|
<p>Pluggable Authentication Modules (PAM) is the mechanism a UNIX-like system that authenticates users,
|
|
and to control access to some resources. This is configured through a stack of modules that are
|
|
executed in order to evaluate the request, and then each module may request or reuse authentication
|
|
token information.</p>
|
|
<h3 id="before-you-start"><a class="header" href="#before-you-start">Before You Start</a></h3>
|
|
<p>You <em>should</em> backup your /etc/pam.d directory from its original state as you <em>may</em> change the PAM
|
|
configuration in a way that will not allow you to authenticate to your machine.</p>
|
|
<pre><code class="language-bash">cp -a /etc/pam.d /root/pam.d.backup
|
|
</code></pre>
|
|
<h3 id="suse--opensuse"><a class="header" href="#suse--opensuse">SUSE / OpenSUSE</a></h3>
|
|
<p>To configure PAM on suse you must modify four files, which control the various stages of
|
|
authentication:</p>
|
|
<pre><code class="language-bash">/etc/pam.d/common-account
|
|
/etc/pam.d/common-auth
|
|
/etc/pam.d/common-password
|
|
/etc/pam.d/common-session
|
|
</code></pre>
|
|
<blockquote>
|
|
<p><strong>IMPORTANT</strong> By default these files are symlinks to their corresponding <code>-pc</code> file, for example
|
|
<code>common-account -> common-account-pc</code>. If you directly edit these you are updating the inner
|
|
content of the <code>-pc</code> file and it WILL be reset on a future upgrade. To prevent this you must first
|
|
copy the <code>-pc</code> files. You can then edit the files safely.</p>
|
|
</blockquote>
|
|
<pre><code class="language-bash">cp /etc/pam.d/common-account-pc /etc/pam.d/common-account
|
|
cp /etc/pam.d/common-auth-pc /etc/pam.d/common-auth
|
|
cp /etc/pam.d/common-password-pc /etc/pam.d/common-password
|
|
cp /etc/pam.d/common-session-pc /etc/pam.d/common-session
|
|
</code></pre>
|
|
<p>The content should look like:</p>
|
|
<pre><code># /etc/pam.d/common-auth-pc
|
|
# Controls authentication to this system (verification of credentials)
|
|
auth required pam_env.so
|
|
auth [default=1 ignore=ignore success=ok] pam_localuser.so
|
|
auth sufficient pam_unix.so nullok try_first_pass
|
|
auth requisite pam_succeed_if.so uid >= 1000 quiet_success
|
|
auth sufficient pam_kanidm.so ignore_unknown_user
|
|
auth required pam_deny.so
|
|
|
|
# /etc/pam.d/common-account-pc
|
|
# Controls authorisation to this system (who may login)
|
|
account [default=1 ignore=ignore success=ok] pam_localuser.so
|
|
account sufficient pam_unix.so
|
|
account [default=1 ignore=ignore success=ok] pam_succeed_if.so uid >= 1000 quiet_success quiet_fail
|
|
account sufficient pam_kanidm.so ignore_unknown_user
|
|
account required pam_deny.so
|
|
|
|
# /etc/pam.d/common-password-pc
|
|
# Controls flow of what happens when a user invokes the passwd command. Currently does NOT
|
|
# interact with kanidm.
|
|
password [default=1 ignore=ignore success=ok] pam_localuser.so
|
|
password required pam_unix.so use_authtok nullok shadow try_first_pass
|
|
password [default=1 ignore=ignore success=ok] pam_succeed_if.so uid >= 1000 quiet_success quiet_fail
|
|
password required pam_kanidm.so
|
|
|
|
# /etc/pam.d/common-session-pc
|
|
# Controls setup of the user session once a successful authentication and authorisation has
|
|
# occurred.
|
|
session optional pam_systemd.so
|
|
session required pam_limits.so
|
|
session optional pam_unix.so try_first_pass
|
|
session optional pam_umask.so
|
|
session [default=1 ignore=ignore success=ok] pam_succeed_if.so uid >= 1000 quiet_success quiet_fail
|
|
session optional pam_kanidm.so
|
|
session optional pam_env.so
|
|
</code></pre>
|
|
<blockquote>
|
|
<p><strong>WARNING:</strong> Ensure that <code>pam_mkhomedir</code> or <code>pam_oddjobd</code> are <em>not</em> present in any stage of your
|
|
PAM configuration, as they interfere with the correct operation of the Kanidm tasks daemon.</p>
|
|
</blockquote>
|
|
<h3 id="fedora--centos"><a class="header" href="#fedora--centos">Fedora / CentOS</a></h3>
|
|
<blockquote>
|
|
<p><strong>WARNING:</strong> Kanidm currently has no support for SELinux policy - this may mean you need to run
|
|
the daemon with permissive mode for the unconfined_service_t daemon type. To do this run:
|
|
<code>semanage permissive -a unconfined_service_t</code>. To undo this run
|
|
<code>semanage permissive -d unconfined_service_t</code>.</p>
|
|
<p>You may also need to run <code>audit2allow</code> for sshd and other types to be able to access the UNIX
|
|
daemon sockets.</p>
|
|
</blockquote>
|
|
<p>These files are managed by authselect as symlinks. You can either work with authselect, or remove
|
|
the symlinks first.</p>
|
|
<h4 id="without-authselect"><a class="header" href="#without-authselect">Without authselect</a></h4>
|
|
<p>If you just remove the symlinks:</p>
|
|
<p>Edit the content.</p>
|
|
<pre><code># /etc/pam.d/password-auth
|
|
auth required pam_env.so
|
|
auth required pam_faildelay.so delay=2000000
|
|
auth [default=1 ignore=ignore success=ok] pam_usertype.so isregular
|
|
auth [default=1 ignore=ignore success=ok] pam_localuser.so
|
|
auth sufficient pam_unix.so nullok try_first_pass
|
|
auth [default=1 ignore=ignore success=ok] pam_usertype.so isregular
|
|
auth sufficient pam_kanidm.so ignore_unknown_user
|
|
auth required pam_deny.so
|
|
|
|
account sufficient pam_unix.so
|
|
account sufficient pam_localuser.so
|
|
account sufficient pam_usertype.so issystem
|
|
account sufficient pam_kanidm.so ignore_unknown_user
|
|
account required pam_permit.so
|
|
|
|
password requisite pam_pwquality.so try_first_pass local_users_only
|
|
password sufficient pam_unix.so sha512 shadow nullok try_first_pass use_authtok
|
|
password sufficient pam_kanidm.so
|
|
password required pam_deny.so
|
|
|
|
session optional pam_keyinit.so revoke
|
|
session required pam_limits.so
|
|
-session optional pam_systemd.so
|
|
session [success=1 default=ignore] pam_succeed_if.so service in crond quiet use_uid
|
|
session required pam_unix.so
|
|
session optional pam_kanidm.so
|
|
|
|
-
|
|
|
|
# /etc/pam.d/system-auth
|
|
auth required pam_env.so
|
|
auth required pam_faildelay.so delay=2000000
|
|
auth sufficient pam_fprintd.so
|
|
auth [default=1 ignore=ignore success=ok] pam_usertype.so isregular
|
|
auth [default=1 ignore=ignore success=ok] pam_localuser.so
|
|
auth sufficient pam_unix.so nullok try_first_pass
|
|
auth [default=1 ignore=ignore success=ok] pam_usertype.so isregular
|
|
auth sufficient pam_kanidm.so ignore_unknown_user
|
|
auth required pam_deny.so
|
|
|
|
account sufficient pam_unix.so
|
|
account sufficient pam_localuser.so
|
|
account sufficient pam_usertype.so issystem
|
|
account sufficient pam_kanidm.so ignore_unknown_user
|
|
account required pam_permit.so
|
|
|
|
password requisite pam_pwquality.so try_first_pass local_users_only
|
|
password sufficient pam_unix.so sha512 shadow nullok try_first_pass use_authtok
|
|
password sufficient pam_kanidm.so
|
|
password required pam_deny.so
|
|
|
|
session optional pam_keyinit.so revoke
|
|
session required pam_limits.so
|
|
-session optional pam_systemd.so
|
|
session [success=1 default=ignore] pam_succeed_if.so service in crond quiet use_uid
|
|
session required pam_unix.so
|
|
session optional pam_kanidm.so
|
|
</code></pre>
|
|
<h4 id="with-authselect"><a class="header" href="#with-authselect">With authselect</a></h4>
|
|
<p>To work with authselect:</p>
|
|
<p>You will need to
|
|
<a href="https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/configuring_authentication_and_authorization_in_rhel/configuring-user-authentication-using-authselect_configuring-authentication-and-authorization-in-rhel#creating-and-deploying-your-own-authselect-profile_configuring-user-authentication-using-authselect">create a new profile</a>.</p>
|
|
<!--TODO this URL is too short -->
|
|
<p>First run the following command:</p>
|
|
<pre><code class="language-bash">authselect create-profile kanidm -b sssd
|
|
</code></pre>
|
|
<p>A new folder, /etc/authselect/custom/kanidm, should be created. Inside that folder, create or
|
|
overwrite the following three files: nsswitch.conf, password-auth, system-auth. password-auth and
|
|
system-auth should be the same as above. nsswitch should be modified for your use case. A working
|
|
example looks like this:</p>
|
|
<pre><code>passwd: compat kanidm sss files systemd
|
|
group: compat kanidm sss files systemd
|
|
shadow: files
|
|
hosts: files dns myhostname
|
|
services: sss files
|
|
netgroup: sss files
|
|
automount: sss files
|
|
|
|
aliases: files
|
|
ethers: files
|
|
gshadow: files
|
|
networks: files dns
|
|
protocols: files
|
|
publickey: files
|
|
rpc: files
|
|
</code></pre>
|
|
<p>Then run:</p>
|
|
<pre><code class="language-bash">authselect select custom/kanidm
|
|
</code></pre>
|
|
<p>to update your profile.</p>
|
|
<h2 id="troubleshooting"><a class="header" href="#troubleshooting">Troubleshooting</a></h2>
|
|
<h3 id="check-posix-status-of-group-and-configuration"><a class="header" href="#check-posix-status-of-group-and-configuration">Check POSIX-status of Group and Configuration</a></h3>
|
|
<p>If authentication is failing via PAM, make sure that a list of groups is configured in
|
|
<code>/etc/kanidm/unixd</code>:</p>
|
|
<pre><code class="language-toml">pam_allowed_login_groups = ["example_group"]
|
|
</code></pre>
|
|
<p>Check the status of the group with <code>kanidm group posix show example_group</code>. If you get something
|
|
similar to the following example:</p>
|
|
<pre><code class="language-bash">> kanidm group posix show example_group
|
|
Using cached token for name idm_admin
|
|
Error -> Http(500, Some(InvalidAccountState("Missing class: account && posixaccount OR group && posixgroup")),
|
|
"b71f137e-39f3-4368-9e58-21d26671ae24")
|
|
</code></pre>
|
|
<p>POSIX-enable the group with <code>kanidm group posix set example_group</code>. You should get a result similar
|
|
to this when you search for your group name:</p>
|
|
<pre><code class="language-bash">> kanidm group posix show example_group
|
|
[ spn: example_group@kanidm.example.com, gidnumber: 3443347205 name: example_group, uuid: b71f137e-39f3-4368-9e58-21d26671ae24 ]
|
|
</code></pre>
|
|
<p>Also, ensure the target user is in the group by running:</p>
|
|
<pre><code class="language-bash">> kanidm group list_members example_group
|
|
</code></pre>
|
|
<h3 id="increase-logging"><a class="header" href="#increase-logging">Increase Logging</a></h3>
|
|
<p>For the unixd daemon, you can increase the logging with:</p>
|
|
<pre><code class="language-bash">systemctl edit kanidm-unixd.service
|
|
</code></pre>
|
|
<p>And add the lines:</p>
|
|
<pre><code>[Service]
|
|
Environment="RUST_LOG=kanidm=debug"
|
|
</code></pre>
|
|
<p>Then restart the kanidm-unixd.service.</p>
|
|
<p>The same pattern is true for the kanidm-unixd-tasks.service daemon.</p>
|
|
<p>To debug the pam module interactions add <code>debug</code> to the module arguments such as:</p>
|
|
<pre><code>auth sufficient pam_kanidm.so debug
|
|
</code></pre>
|
|
<h3 id="check-the-socket-permissions"><a class="header" href="#check-the-socket-permissions">Check the Socket Permissions</a></h3>
|
|
<p>Check that the <code>/var/run/kanidm-unixd/sock</code> has permissions mode 777, and that non-root readers can
|
|
see it with ls or other tools.</p>
|
|
<p>Ensure that <code>/var/run/kanidm-unixd/task_sock</code> has permissions mode 700, and that it is owned by the
|
|
kanidm unixd process user.</p>
|
|
<h3 id="verify-that-you-can-access-the-kanidm-server"><a class="header" href="#verify-that-you-can-access-the-kanidm-server">Verify that You Can Access the Kanidm Server</a></h3>
|
|
<p>You can check this with the client tools:</p>
|
|
<pre><code class="language-bash">kanidm self whoami --name anonymous
|
|
</code></pre>
|
|
<h3 id="ensure-the-libraries-are-correct"><a class="header" href="#ensure-the-libraries-are-correct">Ensure the Libraries are Correct</a></h3>
|
|
<p>You should have:</p>
|
|
<pre><code class="language-bash">/usr/lib64/libnss_kanidm.so.2
|
|
/usr/lib64/security/pam_kanidm.so
|
|
</code></pre>
|
|
<p>The exact path <em>may</em> change depending on your distribution, <code>pam_unixd.so</code> should be co-located with
|
|
pam_kanidm.so. Look for it with the find command:</p>
|
|
<pre><code class="language-bash">find /usr/ -name 'pam_unix.so'
|
|
</code></pre>
|
|
<p>For example, on a Debian machine, it's located in <code>/usr/lib/x86_64-linux-gnu/security/</code>.</p>
|
|
<h3 id="increase-connection-timeout"><a class="header" href="#increase-connection-timeout">Increase Connection Timeout</a></h3>
|
|
<p>In some high-latency environments, you may need to increase the connection timeout. We set this low
|
|
to improve response on LANs, but over the internet this may need to be increased. By increasing the
|
|
conn_timeout, you will be able to operate on higher latency links, but some operations may take
|
|
longer to complete causing a degree of latency.</p>
|
|
<p>By increasing the cache_timeout, you will need to refresh less often, but it may result in an
|
|
account lockout or group change until cache_timeout takes effect. Note that this has security
|
|
implications:</p>
|
|
<pre><code class="language-toml"># /etc/kanidm/unixd
|
|
# Seconds
|
|
conn_timeout = 8
|
|
# Cache timeout
|
|
cache_timeout = 60
|
|
</code></pre>
|
|
<h3 id="invalidate-or-clear-the-cache"><a class="header" href="#invalidate-or-clear-the-cache">Invalidate or Clear the Cache</a></h3>
|
|
<p>You can invalidate the kanidm_unixd cache with:</p>
|
|
<pre><code class="language-bash">kanidm-unix cache-invalidate
|
|
</code></pre>
|
|
<p>You can clear (wipe) the cache with:</p>
|
|
<pre><code class="language-bash">kanidm-unix cache-clear
|
|
</code></pre>
|
|
<p>There is an important distinction between these two - invalidated cache items may still be yielded
|
|
to a client request if the communication to the main Kanidm server is not possible. For example, you
|
|
may have your laptop in a park without wifi.</p>
|
|
<p>Clearing the cache, however, completely wipes all local data about all accounts and groups. If you
|
|
are relying on this cached (but invalid) data, you may lose access to your accounts until other
|
|
communication issues have been resolved.</p>
|
|
<h3 id="home-directories-are-not-created-via-ssh"><a class="header" href="#home-directories-are-not-created-via-ssh">Home directories are not created via SSH</a></h3>
|
|
<p>Ensure that <code>UsePAM yes</code> is set in <code>sshd_config</code>. Without this the pam session module won't be
|
|
triggered which prevents the background task being completed.</p>
|
|
|
|
</main>
|
|
|
|
<nav class="nav-wrapper" aria-label="Page navigation">
|
|
<!-- Mobile navigation buttons -->
|
|
<a rel="prev" href="../recycle_bin.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="../ssh_key_dist.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="../recycle_bin.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="../ssh_key_dist.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>
|