1pam_ssh_agent_auth(8) PAM pam_ssh_agent_auth(8)
2
6 pam_ssh_agent_auth - PAM module for granting permissions based on SSH
7 agent requests
8
10 This module provides authentication via ssh keys. If an ssh-agent
11 listening at SSH_AUTH_SOCK can successfully authenticate that it has
12 the secret key for a public key in the specified file, authentication
13 is granted. If the public key originally used to authenticate at sshd
14 matches an authorized key, authentication succeeds. Otherwise
15 authentication fails.
16
18 SUDO
19 /etc/pam.d/sudo:
20 auth sufficient pam_ssh_agent_auth.so file=/etc/security/authorized_keys
21 /etc/sudoers:
23 In older versions of sudo (< 1.8.5) it was necessary to set:
24 Defaults env_keep += "SSH_AUTH_SOCK"
25 This configuration would permit anyone who has an SSH_AUTH_SOCK that
27 manages the private key matching a public key in
28 /etc/security/authorized_keys to execute sudo without having to enter a
29 password. Note that the ssh-agent listening to SSH_AUTH_SOCK can either
30 be local, or forwarded.
31 Unlike NOPASSWD, this still requires an authentication, it's just that
33 the authentication is provided by ssh-agent, and not password entry.
34 SSHD
36 /etc/ssh/sshd_config:
37 PubkeyAuthentication yes
38 AuthenticationMethods publickey,keyboard-interactive:pam
39 PasswordAuthentication no
40 UsePAM yes
41 /etc/pam.d/sshd:
43 auth required pam_permit.so
44 auth sufficient pam_ssh_agent_auth.so file=/etc/security/super_authorized_keys
45 auth sufficient pam_secondary_auth_method.so
46 ...
47 auth requisite pam_deny.so
48 This configuration would permit anyone who originally authenticated to
50 sshd with a public key also found in
51 /etc/security/super_authorized_keys to log in without having to
52 complete other PAM auth methods. Anyone whose ssh key was accepted
53 initially by sshd but whose key is not in the allowlist must complete
54 another secondary PAM module such as OTP or else be denied.
55
57 file=<path to authorized_keys>
58 Specify the path to the authorized_keys file(s) you would like to
59 use for authentication. Subject to tilde and % EXPANSIONS (below)
60 allow_user_owned_authorized_keys_file
62 A flag which enables authorized_keys files to be owned by the
63 invoking user, instead of root. This flag is enabled automatically
64 whenever the expansions %h or ~ are used.
65 authorized_keys_command=<path to executable>
67 Specify an external command to run, which should take a single
68 argument, the username of the person being authenticated, and emit
69 to its stdout a file in authorized_keys format. This is ideally
70 suited for use with sssd's sss_ssh_authorizedkeys, for
71 authenticating users via authorized_keys stored in ldap or other
72 sssd supported security service.
73 authorized_keys_command_user=<username>
75 Specify a user to run the authorized_keys_command as. If this
76 option is not specified, the authorized_keys_command will be run as
77 the user being authenticated.
78 debug
80 A flag which enables verbose logging
81 sudo_service_name=<service name you compiled sudo to use>
83 (when compiled with --enable-sudo-hack)
84 Specify the service name to use to identify the service "sudo".
86 When the PAM_SERVICE identifier matches this string, and if
87 PAM_RUSER is not set, pam_ssh_agent_auth will attempt to identify
88 the calling user from the environment variable SUDO_USER.
89 This defaults to "sudo".
91
93 ~ -- same as in shells, a user's Home directory
94 Automatically enables allow_user_owned_authorized_keys_file if used
95 in the context of ~/. If used as ~user/, it would expect the file
96 to be owned by 'user', unless you explicitly set
97 allow_user_owned_authorized_keys_file
98 %h -- User's Home directory
100 Automatically enables allow_user_owned_authorized_keys_file
101 %H -- The short-hostname
103 %u -- Username
104 %f -- FQDN
105
107 in /etc/pam.d/sudo
108 "auth sufficient pam_ssh_agent_auth.so file=~/.ssh/authorized_keys"
110 The default .ssh/authorized_keys file in a user's home-directory
111 "auth sufficient pam_ssh_agent_auth.so file=%h/.ssh/authorized_keys"
113 Same as above.
114 "auth sufficient pam_ssh_agent_auth.so file=~fred/.ssh/authorized_keys"
116 If the home-directory of user 'fred' was /home/fred, this would
117 expand to /home/fred/.ssh/authorized_keys. In this case, we have
118 not specified allow_user_owned_authorized_keys_file, so this file
119 must be owned by 'fred'.
120 "auth sufficient pam_ssh_agent_auth.so
122 file=/secure/%H/%u/authorized_keys
123 allow_user_owned_authorized_keys_file"
124 On a host named foobar.baz.com, and a user named fred, would expand
125 to /secure/foobar/fred/authorized_keys. In this case, we specified
126 allow_user_owned_authorized_keys_file, so fred would be able to
127 manage that authorized_keys file himself.
128 "auth sufficient pam_ssh_agent_auth.so
130 file=/secure/%f/%u/authorized_keys"
131 On a host named foobar.baz.com, and a user named fred, would expand
132 to /secure/foobar.baz.com/fred/authorized_keys. In this case, we
133 have not specified allow_user_owned_authorized_keys_file, so this
134 file must be owned by root.
135 "auth [success=3 default=ignore] pam_ssh_agent_auth.so
137 file=~/.ssh/authorized_keys debug"
138 This pam.d config format allows for more control over how pam
139 handles success and failure. In this example, we use success=3,
140 which specifies that when this module succeeds, pam should jump
141 over the next 3 auth modules and continue from there. This is
142 useful, for instance, if /etc/pam.d/common-auth is included, and
143 contains 3 "auth required" or similar module rules that we wish to
144 skip, but we wish not to skip other auth rules.
145 For more information, please see http://linux.die.net/man/5/pam.d
147
149 Copyright (c) 2008-2014, Jamie Beverly.
150 And is based on openssh, and the included works by Markus Friedl, Darren Tucker,
151 Todd C. Miller, Ben Lindstrom, Tim Rice, Damien Miller, Liz Fong-Jones, and many others.
152 All rights reserved.
154 See sources for complete attributions.
156 Redistribution and use in source and binary forms, with or without modification, are
158 permitted provided that the following conditions are met:
159 1. Redistributions of source code must retain the above copyright notice, this list of
161 conditions and the following disclaimer.
162 2. Redistributions in binary form must reproduce the above copyright notice, this list
164 of conditions and the following disclaimer in the documentation and/or other materials
165 provided with the distribution.
166 THIS SOFTWARE IS PROVIDED BY Jamie Beverly ``AS IS'' AND ANY EXPRESS OR IMPLIED
168 WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
169 FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL Jamie Beverly OR
170 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
171 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
172 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
173 ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
174 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
175 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
176v0.10.3 2023-07-26 pam_ssh_agent_auth(8)