Radius Authentication¶
It is possible to authenticate users for SSH/SFTP access by using the RADIUS authentication protocol to contact a third party RADIUS authentication server. The following will explain how to install and configure this capability on a Clearwater node, and how to go about using it.
The authentication process¶
On attempting to access a node via SSH or SFTP, a user is either expected to use a key, or to provide a password to verify their identity, and thus pass through authentication successfully. This process requires a locally provisioned set of authentication details for each user that the sshd process can compare to the provided credentials for verification. In the case of password authentication, by enabling RADIUS all user accounts can be configured centrally on a RADIUS server, or in a database said server can access, and each node can pass user credentials provided at log in across to this server to complete the authentication process.
As the user attempting access may not exist locally on the node, which sshd requires, any unknown user is mapped to the default Ubuntu user to allow authentication to proceed correctly. As such, once authenticated, they will be acting as if they were the default user, but for auditing purposes it is the username provided at login that is recorded.
Prerequisites¶
The following conditions are assumed by this process:
- Your nodes are running on Ubuntu 14.04.
- Your nodes have access to both Clearwater and Ubuntu repositories.
- Your SSH configuration allows password authentication and PAM (the correct configuration will be detailed below).
- You have access to a third-party RADIUS server (such as freeRADIUS).
- Your firewall allows UDP traffic to the above server on port 1812.
Installation¶
Package installation¶
Install the Clearwater RADIUS authentication package:
sudo apt-get install clearwater-radius-auth
Configuration¶
The details of your RADIUS server will need to be entered into
/etc/pam_radius_auth.conf
. This file provides an example of how
entries should be structured: * Multiple entries are allowed, but each
must be on a new line. * Each line consists of three fields: *
server[:port]
(The default is port 1812. All traffic will be UDP) *
secret
* [timeout]
(Default timeout is 3 seconds) * The secret
is shared between each client and the server to allow simple encryption
of passwords. The secret must match the entry for the client in the
RADIUS server configuration. * Both the port and timeout entries are
optional.
Your sshd configuration must allow password authentication, and use of
PAM. If you are unsure, check that the PasswordAuthentication
and
UsePAM
entries in /etc/ssh/sshd_config
are set to yes
. Any
changes to ssh configuration will require the ssh process to be
restarted before coming into effect.
You must ensure that your firewall/security groups allow UDP traffic to the RADIUS server on port 1812.
Usage¶
Once the above is installed and configured, any user provisioned in the
RADIUS server can attempt SSH or SFTP access to the configured node, and
on providing their password they will be authenticated against the
details held on the RADIUS server, and logged in, acting as the default
Ubuntu user. Commands such as who
or last
will output the
username supplied at login, and this will also be recorded in the auth
log /var/log/auth.log
.
Any users provisioned locally on the node will see no change to their authentication experience. By default, RADIUS authentication is set to be a sufficient, but not required condition. As such, failing to authenticate against the server credentials will cause the authentication attempt to fall back to checking locally provisioned details. See below for further details on configuration options.
Troubleshooting¶
- If you are not seeing any traffic reaching your RADIUS server, and
entries in
/var/log/auth.log
state that no RADIUS server was reachable, re-check the RADIUS server entry in/etc/pam_radius_auth.conf
, and ensure that your firewall is configured to allow UDP traffic to the RADIUS server on port 1812. - If your RADIUS server is rejecting authentication requests, ensure that the server is configured correctly.
Removal¶
To properly remove clearwater-radius-auth, and the components it brings with it, run the following:
sudo apt-get purge clearwater-radius-auth
sudo apt-get purge libpam-radius-auth
sudo apt-get purge libnss-ato
This will remove all configuration put in place by the installation. Should your configuration become corrupt, purging and re-installing the associated module will re-instate the correct configuration.
Further configuration¶
This section details the configuration put in place by the installation. It is highly recommended that these be left as their defaults. The following is for information purposes only.
libnss-ato.conf¶
The libnss-ato configuration file is found at /etc/libnss-ato.conf
,
and will look like the following:
ubuntu:x:1000:1000:Ubuntu:/home/ubuntu:/bin/bash
It holds the information of the default user to which unknown users are mapped. By default this maps to the Ubuntu user.
Only the first line of this file is parsed. The user entry is the same
format as is found in /etc/passwd
. Replacing this file with a
different user entry will map unknown users to the entry provided.
pam.d/sshd¶
The PAM configuration file for the sshd process is found at
/etc/pam.d/sshd
. As part of the installation, the 3 lines around
auth sufficient pam_radius_auth.so
are added at the top of the file,
configuring PAM to attempt RADIUS authentication before other methods.
It will look like the following:
# PAM configuration for the Secure Shell service
# +clearwater-radius-auth
auth sufficient pam_radius_auth.so
# -clearwater-radius-auth
# Standard Un*x authentication.
It is strongly recommended that users do not modify this entry. Further information on this configuration can be found at FreeRADIUS.
nsswitch.conf¶
The NSS configuration file is found at /etc/nsswitch.conf
. After
installation, the top three entries in this file will look as follows:
passwd: compat ato
group: compat
shadow: compat ato
Modifications to the NSS configuration make it check the libnss-ato
component for a user mapping if no local user is found. The addition of
ato
at the end of both the passwd
and shadow
entries
provides this function. Removal of these addition will disable the user
mapping, and break RADIUS authentication.