2022-12-29 04:22:16 +01:00
<!DOCTYPE HTML>
< html lang = "en" class = "sidebar-visible no-js light" >
< head >
<!-- Book generated using mdBook -->
< meta charset = "UTF-8" >
< title > SSH Key Distribution - 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 >
2023-02-17 08:24:03 +01:00
< div id = "body-container" >
2022-12-29 04:22:16 +01:00
<!-- 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" >
2023-03-02 04:03:10 +01:00
< 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 = "posix_accounts.html" > < strong aria-hidden = "true" > 4.2.< / strong > POSIX Accounts and Groups< / a > < / li > < li class = "chapter-item expanded " > < a href = "backup_restore.html" > < strong aria-hidden = "true" > 4.3.< / strong > Backup and Restore< / a > < / li > < li class = "chapter-item expanded " > < a href = "database_maint.html" > < strong aria-hidden = "true" > 4.4.< / strong > Database Maintenance< / a > < / li > < li class = "chapter-item expanded " > < a href = "domain_rename.html" > < strong aria-hidden = "true" > 4.5.< / strong > Domain Rename< / a > < / li > < li class = "chapter-item expanded " > < a href = "monitoring.html" > < strong aria-hidden = "true" > 4.6.< / strong > Monitoring the platform< / a > < / li > < li class = "chapter-item expanded " > < a href = "password_quality.html" > < strong aria-hidden = "true" > 4.7.< / strong > Password Quality and Badlisting< / a > < / li > < li class = "chapter-item expanded " > < a href = "recycle_bin.html" > < strong aria-hidden = "true" > 4.8.< / 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" > < strong aria-hidden = "true" > 5.< / strong > PAM and nsswitch< / a > < / li > < li class = "chapter-item expanded " > < a href = "ssh_key_dist.html" class = "active" > < 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
2022-12-29 04:22:16 +01:00
< / 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 >
2023-03-02 04:03:10 +01:00
< a href = "https://github.com/kanidm/kanidm/edit/master/book/src/ssh_key_dist.md" title = "Suggest an edit" aria-label = "Suggest an edit" >
2022-12-29 04:22:16 +01:00
< 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 = "ssh-key-distribution" > < a class = "header" href = "#ssh-key-distribution" > SSH Key Distribution< / a > < / h1 >
< p > To support SSH authentication securely to a large set of hosts running SSH, we support distribution
of SSH public keys via the Kanidm server. Both persons and service accounts support SSH public keys
on their accounts.< / p >
< h2 id = "configuring-accounts" > < a class = "header" href = "#configuring-accounts" > Configuring Accounts< / a > < / h2 >
< p > To view the current SSH public keys on accounts, you can use:< / p >
2023-03-02 04:03:10 +01:00
< pre > < code class = "language-bash" > kanidm person|service-account \
ssh list-publickeys --name < login user> < account to view>
kanidm person|service-account \
ssh list-publickeys --name idm_admin william
2022-12-29 04:22:16 +01:00
< / code > < / pre >
< p > All users by default can self-manage their SSH public keys. To upload a key, a command like this is
the best way to do so:< / p >
2023-03-02 04:03:10 +01:00
< pre > < code class = "language-bash" > kanidm person|service-account \
ssh add-publickey --name william william 'test-key' " `cat ~/.ssh/id_ecdsa.pub`"
2022-12-29 04:22:16 +01:00
< / code > < / pre >
< p > To remove (revoke) an SSH public key, delete them by the tag name:< / p >
2023-03-02 04:03:10 +01:00
< pre > < code class = "language-bash" > kanidm person|service-account ssh delete-publickey --name william william 'test-key'
2022-12-29 04:22:16 +01:00
< / code > < / pre >
< h2 id = "security-notes" > < a class = "header" href = "#security-notes" > Security Notes< / a > < / h2 >
< p > As a security feature, Kanidm validates < em > all< / em > public keys to ensure they are valid SSH public keys.
Uploading a private key or other data will be rejected. For example:< / p >
2023-03-02 04:03:10 +01:00
< pre > < code class = "language-bash" > kanidm person|service-account ssh add-publickey --name william william 'test-key' " invalid"
2022-12-29 04:22:16 +01:00
Enter password:
... Some(SchemaViolation(InvalidAttributeSyntax)))' ...
< / code > < / pre >
< h2 id = "server-configuration" > < a class = "header" href = "#server-configuration" > Server Configuration< / a > < / h2 >
< h3 id = "public-key-caching-configuration" > < a class = "header" href = "#public-key-caching-configuration" > Public Key Caching Configuration< / a > < / h3 >
< p > If you have kanidm_unixd running, you can use it to locally cache SSH public keys. This means you
can still SSH into your machines, even if your network is down, you move away from Kanidm, or some
other interruption occurs.< / p >
< p > The kanidm_ssh_authorizedkeys command is part of the kanidm-unix-clients package, so should be
installed on the servers. It communicates to kanidm_unixd, so you should have a configured
PAM/nsswitch setup as well.< / p >
< p > You can test this is configured correctly by running:< / p >
< pre > < code class = "language-bash" > kanidm_ssh_authorizedkeys < account name>
< / code > < / pre >
< p > If the account has SSH public keys you should see them listed, one per line.< / p >
< p > To configure servers to accept these keys, you must change their /etc/ssh/sshd_config to contain the
lines:< / p >
< pre > < code > PubkeyAuthentication yes
UsePAM yes
AuthorizedKeysCommand /usr/bin/kanidm_ssh_authorizedkeys %u
AuthorizedKeysCommandUser nobody
< / code > < / pre >
< p > Restart sshd, and then attempt to authenticate with the keys.< / p >
< p > It's highly recommended you keep your client configuration and sshd_configuration in a configuration
management tool such as salt or ansible.< / p >
< blockquote >
< p > < strong > NOTICE:< / strong > With a working SSH key setup, you should also consider adding the following
sshd_config options as hardening.< / p >
< / blockquote >
< pre > < code > PermitRootLogin no
PasswordAuthentication no
PermitEmptyPasswords no
GSSAPIAuthentication no
KerberosAuthentication no
< / code > < / pre >
< h3 id = "direct-communication-configuration" > < a class = "header" href = "#direct-communication-configuration" > Direct Communication Configuration< / a > < / h3 >
< p > In this mode, the authorised keys commands will contact Kanidm directly.< / p >
< blockquote >
< p > < strong > NOTICE:< / strong > As Kanidm is contacted directly there is no SSH public key cache. Any network outage
or communication loss may prevent you accessing your systems. You should only use this version if
you have a requirement for it.< / p >
< / blockquote >
< p > The kanidm_ssh_authorizedkeys_direct command is part of the kanidm-clients package, so should be
installed on the servers.< / p >
< p > To configure the tool, you should edit /etc/kanidm/config, as documented in
< a href = "./client_tools.html" > clients< / a > < / p >
< p > You can test this is configured correctly by running:< / p >
< pre > < code class = "language-bash" > kanidm_ssh_authorizedkeys_direct -D anonymous < account name>
< / code > < / pre >
< p > If the account has SSH public keys you should see them listed, one per line.< / p >
2023-03-02 04:03:10 +01:00
< p > To configure servers to accept these keys, you must change their /etc/ssh/sshd_config to contain
the lines:< / p >
2022-12-29 04:22:16 +01:00
< pre > < code > PubkeyAuthentication yes
UsePAM yes
AuthorizedKeysCommand /usr/bin/kanidm_ssh_authorizedkeys_direct -D anonymous %u
AuthorizedKeysCommandUser nobody
< / code > < / pre >
< p > Restart sshd, and then attempt to authenticate with the keys.< / p >
2023-03-02 04:03:10 +01:00
< p > It's highly recommended you keep your client configuration and sshd_configuration in a
configuration management tool such as salt or ansible.< / p >
2022-12-29 04:22:16 +01:00
< / main >
< nav class = "nav-wrapper" aria-label = "Page navigation" >
<!-- Mobile navigation buttons -->
2023-03-02 04:03:10 +01:00
< a rel = "prev" href = "integrations/pam_and_nsswitch.html" class = "mobile-nav-chapters previous" title = "Previous chapter" aria-label = "Previous chapter" aria-keyshortcuts = "Left" >
2022-12-29 04:22:16 +01:00
< i class = "fa fa-angle-left" > < / i >
< / a >
2023-03-02 04:03:10 +01:00
< a rel = "next" href = "integrations/oauth2.html" class = "mobile-nav-chapters next" title = "Next chapter" aria-label = "Next chapter" aria-keyshortcuts = "Right" >
2022-12-29 04:22:16 +01:00
< 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" >
2023-03-02 04:03:10 +01:00
< a rel = "prev" href = "integrations/pam_and_nsswitch.html" class = "nav-chapters previous" title = "Previous chapter" aria-label = "Previous chapter" aria-keyshortcuts = "Left" >
2022-12-29 04:22:16 +01:00
< i class = "fa fa-angle-left" > < / i >
< / a >
2023-03-02 04:03:10 +01:00
< a rel = "next" href = "integrations/oauth2.html" class = "nav-chapters next" title = "Next chapter" aria-label = "Next chapter" aria-keyshortcuts = "Right" >
2022-12-29 04:22:16 +01:00
< 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 -->
2023-02-17 08:24:03 +01:00
< / div >
2022-12-29 04:22:16 +01:00
< / body >
< / html >
