1pam_ssh_agent_auth(8)                 PAM                pam_ssh_agent_auth(8)
2
3
4

NAME

6       pam_ssh_agent_auth - PAM module for granting permissions based on SSH
7       agent requests
8

DESCRIPTION

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

CONFIGURATION

18   SUDO
19       /etc/pam.d/sudo:
20            auth   sufficient      pam_ssh_agent_auth.so file=/etc/security/authorized_keys
21
22       /etc/sudoers:
23           In older versions of sudo (< 1.8.5) it was necessary to set:
24            Defaults    env_keep += "SSH_AUTH_SOCK"
25
26       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
32       Unlike NOPASSWD, this still requires an authentication, it's just that
33       the authentication is provided by ssh-agent, and not password entry.
34
35   SSHD
36       /etc/ssh/sshd_config:
37            PubkeyAuthentication yes
38            AuthenticationMethods publickey,keyboard-interactive:pam
39            PasswordAuthentication no
40            UsePAM yes
41
42       /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
49       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

ARGUMENTS

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
61       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
66       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
74       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
79       debug
80           A flag which enables verbose logging
81
82       sudo_service_name=<service name you compiled sudo to use>
83           (when compiled with --enable-sudo-hack)
84
85           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
90           This defaults to "sudo".
91

EXPANSIONS

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
99       %h -- User's Home directory
100           Automatically enables allow_user_owned_authorized_keys_file
101
102       %H -- The short-hostname
103       %u -- Username
104       %f -- FQDN
105

EXAMPLES

107       in /etc/pam.d/sudo
108
109       "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
112       "auth sufficient pam_ssh_agent_auth.so file=%h/.ssh/authorized_keys"
113           Same as above.
114
115       "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
121       "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
129       "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
136       "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
146           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
153        All rights reserved.
154
155        See sources for complete attributions.
156
157        Redistribution and use in source and binary forms, with or without modification, are
158        permitted provided that the following conditions are met:
159
160        1. Redistributions of source code must retain the above copyright notice, this list of
161           conditions and the following disclaimer.
162
163        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
167        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.
176
177
178
179v0.10.3                           2022-09-29             pam_ssh_agent_auth(8)
Impressum