162 lines
6.2 KiB
Plaintext
162 lines
6.2 KiB
Plaintext
=head1 NAME
|
|
|
|
pam_ssh_agent_auth - PAM module for granting permissions based on SSH agent requests
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
This module provides authentication via ssh-agent. If an ssh-agent listening at SSH_AUTH_SOCK can successfully authenticate that it has the secret key for a public key in the specified file, authentication is granted, otherwise authentication fails.
|
|
|
|
=head1 CONFIGURATION
|
|
|
|
=over
|
|
|
|
=item /etc/pam.d/sudo:
|
|
auth sufficient pam_ssh_agent_auth.so file=/etc/security/authorized_keys
|
|
|
|
=item /etc/sudoers:
|
|
|
|
In older versions of sudo (< 1.8.5) it was necessary to set:
|
|
Defaults env_keep += "SSH_AUTH_SOCK"
|
|
|
|
=back
|
|
|
|
This configuration would permit anyone who has an SSH_AUTH_SOCK that manages the private key matching a public key in /etc/security/authorized_keys to execute sudo without having to enter a password. Note that the ssh-agent listening to SSH_AUTH_SOCK can either be local, or forwarded.
|
|
|
|
Unlike NOPASSWD, this still requires an authentication, it's just that the authentication is provided by ssh-agent, and not password entry.
|
|
|
|
|
|
=head1 ARGUMENTS
|
|
|
|
=over
|
|
|
|
=item file=<path to authorized_keys>
|
|
|
|
Specify the path to the authorized_keys file(s) you would like to use for authentication. Subject to tilde and % EXPANSIONS (below)
|
|
|
|
=item allow_user_owned_authorized_keys_file
|
|
|
|
A flag which enables authorized_keys files to be owned by the invoking user, instead of root. This flag is enabled automatically whenever
|
|
the expansions %h or ~ are used.
|
|
|
|
=item authorized_keys_command=<path to executable>
|
|
|
|
Specify an external command to run, which should take a single argument, the username of the person being authenticated, and emit to its stdout a file in authorized_keys format.
|
|
This is ideally suited for use with sssd's sss_ssh_authorizedkeys, for authenticating users via authorized_keys stored in ldap or other sssd supported security service.
|
|
|
|
=item authorized_keys_command_user=<username>
|
|
|
|
Specify a user to run the authorized_keys_command as. If this option is not specified, the authorized_keys_command will be run as the user being authenticated.
|
|
|
|
=item debug
|
|
|
|
A flag which enables verbose logging
|
|
|
|
=item sudo_service_name=<service name you compiled sudo to use>
|
|
|
|
(when compiled with --enable-sudo-hack)
|
|
|
|
Specify the service name to use to identify the service "sudo". When the PAM_SERVICE identifier matches this
|
|
string, and if PAM_RUSER is not set, pam_ssh_agent_auth will attempt to identify the calling user from the
|
|
environment variable SUDO_USER.
|
|
|
|
This defaults to "sudo".
|
|
|
|
=back
|
|
|
|
=head1 EXPANSIONS
|
|
|
|
=over
|
|
|
|
=item ~ -- same as in shells, a user's Home directory
|
|
|
|
Automatically enables allow_user_owned_authorized_keys_file if used in the context of ~/. If used as ~user/, it would expect the file to be owned by 'user', unless you explicitly set allow_user_owned_authorized_keys_file
|
|
|
|
=item %h -- User's Home directory
|
|
|
|
Automatically enables allow_user_owned_authorized_keys_file
|
|
|
|
=item %H -- The short-hostname
|
|
|
|
=item %u -- Username
|
|
|
|
=item %f -- FQDN
|
|
|
|
=back
|
|
|
|
=head1 EXAMPLES
|
|
|
|
in /etc/pam.d/sudo
|
|
|
|
=over
|
|
|
|
=item C<auth sufficient pam_ssh_agent_auth.so file=~/.ssh/authorized_keys>
|
|
|
|
The default .ssh/authorized_keys file in a user's home-directory
|
|
|
|
=item C<auth sufficient pam_ssh_agent_auth.so file=%h/.ssh/authorized_keys>
|
|
|
|
Same as above.
|
|
|
|
=item C<auth sufficient pam_ssh_agent_auth.so file=~fred/.ssh/authorized_keys>
|
|
|
|
If the home-directory of user 'fred' was /home/fred, this would expand to /home/fred/.ssh/authorized_keys.
|
|
In this case, we have not specified allow_user_owned_authorized_keys_file,
|
|
so this file must be owned by 'fred'.
|
|
|
|
=item C<auth sufficient pam_ssh_agent_auth.so file=/secure/%H/%u/authorized_keys allow_user_owned_authorized_keys_file>
|
|
|
|
On a host named foobar.baz.com, and a user named fred,
|
|
would expand to /secure/foobar/fred/authorized_keys.
|
|
In this case, we specified allow_user_owned_authorized_keys_file,
|
|
so fred would be able to manage that authorized_keys file himself.
|
|
|
|
=item C<auth sufficient pam_ssh_agent_auth.so file=/secure/%f/%u/authorized_keys>
|
|
|
|
On a host named foobar.baz.com, and a user named fred,
|
|
would expand to /secure/foobar.baz.com/fred/authorized_keys.
|
|
In this case, we have not specified allow_user_owned_authorized_keys_file,
|
|
so this file must be owned by root.
|
|
|
|
=item C<auth [success=3 default=ignore] pam_ssh_agent_auth.so file=~/.ssh/authorized_keys debug>
|
|
|
|
This pam.d config format allows for more control over how pam handles success and failure. In this example,
|
|
we use success=3, which specifies that when this module succeeds, pam should jump over the next 3 auth modules
|
|
and continue from there. This is useful, for instance, if /etc/pam.d/common-auth is included, and contains
|
|
3 "auth required" or similar module rules that we wish to skip, but we wish not to skip other auth rules.
|
|
|
|
For more information, please see http://linux.die.net/man/5/pam.d
|
|
|
|
=back
|
|
|
|
=head1 COPYRIGHT
|
|
|
|
Copyright (c) 2008-2014, Jamie Beverly.
|
|
And is based on openssh, and the included works by Markus Friedl, Darren Tucker,
|
|
Todd C. Miller, Ben Lindstrom, Tim Rice, Damien Miller, and many others.
|
|
|
|
All rights reserved.
|
|
|
|
See sources for complete attributions.
|
|
|
|
Redistribution and use in source and binary forms, with or without modification, are
|
|
permitted provided that the following conditions are met:
|
|
|
|
1. Redistributions of source code must retain the above copyright notice, this list of
|
|
conditions and the following disclaimer.
|
|
|
|
2. Redistributions in binary form must reproduce the above copyright notice, this list
|
|
of conditions and the following disclaimer in the documentation and/or other materials
|
|
provided with the distribution.
|
|
|
|
THIS SOFTWARE IS PROVIDED BY Jamie Beverly ``AS IS'' AND ANY EXPRESS OR IMPLIED
|
|
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
|
|
FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL Jamie Beverly OR
|
|
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
|
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
|
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
|
|
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
|
|
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
|
|
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
|
|
=cut
|