SSH Demo Setup

This is a guide on how to set up a basic PAM RADIUS client and configure it with MIRACL Trust RADIUS server. Then you can authenticate by generating an OTP and using it as a password in the SSH client. These instructions assume that you have already registered in the MIRACL Portal and have created a MIRACL Trust OTP app to obtain API keys as detailed in the Installation section of these docs.

For new settings to take effect, the service needs to be restarted.

You can follow a tutorial for either a Ubuntu or CentOS Linux machine with PAM RADIUS authentication.

# Ubuntu

These instructions have been tested using Ubuntu 16, with a running ssh service.

# MIRACL Trust RADIUS Setup

Make sure your /etc/miracl-radius/config.yaml lists the correct files to include:

includes:
  - core.yaml
  - hosts/sshtest.yaml

Open your /etc/miracl-radius/core.yaml file and edit the mfa section to include the client id and client secret from your app (as created in the MIRACL Trust RADIUS authentication portal in the Installation section):

server:
  address: :1812
protocols:
  - pap
  - chap
  - mschapv1
mfa:
  global:
    client_id: <YOUR_CLIENT_ID>
    client_secret: <YOUR_CLIENT_SECRET>

Note that the pap protocol is enabled by default. This enables communication with PAM RADIUS.

Then edit your /etc/miracl-radius/hosts/sshtest.yaml file. Add the IP of your PAM RADIUS client (you can use 127.0.0.1 if installed on the same machine), plus an arbitrary name and a shared secret (a strong and hard to guess arbitrary string that should also be entered on the PAM RADIUS client (as seen below)). For the purposes of this simple demo you can also use the mfa_id parameter to allow for a non-email SSH login. The example below means that you can use the first half of an ‘@mycompany.com’ email address as your username for logging into an SSH client (e.g. ‘john’ from ‘john@mycompany.com’):

host:
  52.xxx.xxx.xx:
    name: sshtest
    mfa: global
    secret: <SECRET>
    mfa_id: '{{.UserID}}@mycompany.com'
    authorize: true
#    authorize:
#    - - ldap: ldap_profile

Using authorize: true on its own would mean that anybody would be permitted to attempt to login, but combining it with mfa_id: ‘{{.UserID}}@mycompany.com’ means that only users with the @mycompany email domain are authorized. The LDAP and authorization section explains how LDAP or simple regex of email domains can be used for more detailed control of lists of users authorized to attempt to login.

# Note on User Authentication

To generate OTP users need to register first. Registration is outlined in the OTP Generation page. Authentication to SSH client could be done using a user identifier and not an email. This is achieved using the mfa_id configuration option of the MIRACL Trust RADIUS Server which transforms the email to user identifier.

Do not confuse Client Secret with Secret! Client Secret is the OIDC Client Secret of the MIRACL Trust API and Secret is the arbitrary secret that must be specified both in the MIRACL Trust RADIUS Server config.json and the PAM RADIUS config file so they can authenticate to each other.

# Configuring Your PAM RADIUS Client

Install SSH Server: sudo apt-get install openssh-server
Install PAM RADIUS Authentication Module: sudo apt-get install libpam-radius-auth
Configure SSHD for RADIUS Authentication by editing /etc/pam.d/sshd and adding the following line as the second line of the file: auth required /lib/security/pam_radius_auth.so
You may also need to comment out the following line so that the system does not attempt to authenticate via standard Unix password authentication even after a successful RADIUS Authentication: @include common-auth
Open the file /etc/pam_radius_auth.confand add the relevant information under IP_address(:port) shared_secret timeout Where IP_address is the IP address of your RADIUS server, shared_secret is a string which matches the value entered in the RADIUS server config file, as explained above; timeout is the timeout value in seconds. Your file should now look something like:
```
# server[:port] shared_secret      timeout (s)
52.xxx.xx.xx    <SECRET>           5
```
Now edit the ssh config file:

sudo vim /etc/ssh/sshd_config

And allow password authentication:

PasswordAuthentication yes
Restart the SSH service by running:

sudo service ssh restart
Now add yourself as a user:

sudo adduser john

This works for an email address with a one-word prefix (see earlier note on user authentication). For an email address such as john.smith@mycompany.com which has a two-word prefix separated by a ‘.’, you have to use the ‘–force-badname’ flag:

sudo adduser --force-badname john.smith

Enter a unix password when prompted (and default blank entries for all other user fields).

Note that it is possible to use LDAP with your RADIUS setup as per the LDAP instructions.

Note that if you are not using the mfa_id feature, you need to use a full email address as your ssh username: sudo adduser --force-badname john.smith@miracl.com

That completes the setup of your simple PAM RADIUS client.

# Open UDP Ports

To enable the MIRACL Trust RADIUS server and the PAM RADIUS client to communicate with each other it is necessary to open port 1812 (and 1813 if you’re using accounting) on both servers, to the ip address of the other.

So, on AWS, you would add a rule on the MIRACL Trust RADIUS Server:

sso udp port

Where 53.xxx.xx.xx is the IP address of the PAM RADIUS client.

And, on the PAM RADIUS client, you would add a rule:

radius udp port

Where 52.xxx.xx.xx is the IP address of the MIRACL Trust RADIUS server.

# Verify Your Configuration

Before proceeding, make sure your MIRACL Trust RADIUS server is running, with the following command:

docker ps | grep radius

Exit your PAM RADIUS client and attempt to ssh back into it using the user you have just added:

ssh john@12.34.56.789 or ssh john.smith@miracl.com@12.34.56.789

When prompted, enter the unix password you created with the adduser command. You should find that authentication is denied, which means that disabling @include common-auth in /etc/pam.d/sshd has had the desired effect!

You are prompted to enter your OTP. Either visit the OTP url for in-browser OTP generation, or use the MIRACL Trust mobile app to generate an OTP (see here for an explanation of in-browser/mobile OTP generation):

otp create id and create pin

You are given an OTP, which you can enter in your ssh terminal prompt to gain access to the RADIUS server.

# CentOS

These instructions have been tested using CentOS 7.x, with a running ssh service.

# MIRACL Trust RADIUS Setup

Make sure your /etc/miracl-radius/config.yaml lists the correct files to include:

includes:
  - core.yaml
  - hosts/sshtest.yaml

server:
  address: :1812
protocols:
  - pap
  - chap
  - mschapv1
mfa:
  global:
    client_id: <YOUR_CLIENT_ID>
    client_secret: <YOUR_CLIENT_SECRET>

Note that the pap protocol is enabled by default. This enables communication with PAM RADIUS.

host:
  52.xxx.xx.xx:
    name: sshtest
    mfa: global
    secret: <SECRET>
    mfa_id: '{{.UserID}}@example.com'
    authorize: true
#    authorize:
#    - - ldap: ldap_profile

# Note on User Authentication

In order to authenticate and receive an OTP, a user needs to register using the OTP link first. Please, see the OTP Generation menu section for an understanding of how to do it once RADIUS/OTP is up and running. Hence the above mfa_id enables a user to use the prefix to their email address for SSH login, while using the full email address to the MIRACL Trust platform for authentication purposes. For example, while you have registered with john.smith@example.com to MIRACL Trust platform, this would enable you to log in to your ssh client with ssh john.smith@52.xxx.xx.xx.

Do not confuse Client Secret with Secret! Client Secret is one of the API keys you receive from your app in the MIRACL Trust authentication portal and is used to check if the user has really authenticated to the MIRACL Portal. While Secret is the arbitrary secret you must specify and add to both the MIRACL Trust RADIUS config.json file and the PAM RADIUS config file, so they could “know” each other.

# Configuring Your CentOS PAM RADIUS Client

Install PAM RADIUS Authentication Module:

sudo yum -y install epel-release
sudo yum -y update
sudo yum -y install pam_radius pam-devel

Configure SSHD for RADIUS Authentication by editing /etc/pam.d/sshd and adding the following line as the second line of the file (just after #%PAM-1.0):

auth sufficient pam_radius_auth.so
Edit the file /etc/pam_radius.conf and edit the following section thus:
```
IP_address(:port)                shared_secret                timeout
52.xxx.xx.xx                     <SECRET>                     5
```
The above IP address should be that of the MIRACL Trust RADIUS server. The shared secret must match the value entered in the MIRACL Trust RADIUS config, as explained above; timeout is the timeout value in seconds.
Now edit the /etc/ssh/sshd_config file to allow password authentication by editing the following line:

PasswordAuthentication yes
Restart the SSH service by running:

sudo service sshd restart
Next you need to add yourself as a user:

sudo adduser john

Remember your username must match the prefix of the email address you have registered with for OTP (see earlier note on user authentication).

Note that it is possible to use LDAP with your RADIUS setup as per the LDAP instructions

Note that if you are not using the mfa_id feature, you have to add a full email address as your ssh username. However, CentOS does not accept the @ character in a username. So, for this simple demo, we need to add a username with ‘AT’ as a placeholder for the ‘@’ symbol, subsequently replacing it using ‘sed’:

sudo adduser john.smithATexample.com
sudo sed -i 's/john.smithATexample.com/john.smith@example.com/g' /etc/passwd
sudo sed -i 's/john.smithATexample.com/john.smith@example.com/g' /etc/shadow

To prevent an error message on login, change the user’s home directory:

sudo mv /home/john.smithATexample.com /home/john.smith@example.com

That completes the setup of your simple PAM RADIUS server.

# Setup of Ports

To enable the MIRACL Trust RADIUS server and the PAM RADIUS client to communicate with each other it is necessary to open port 1812 (UDP) on both servers (and 1813 (UDP) if you are using accounting), to the ip address of the other (or if both are installed on the one server, open the port to its own public/private IP).

So, on AWS, you would add a rule on the MIRACL Trust RADIUS Server:

radius udp port

Where 52.xxx.xx.xx is the IP address of the PAM RADIUS client.

And, on the PAM RADIUS client, you would add a rule:

radius udp port

Where 53.xxx.xx.xx is the IP address of the MIRACL Trust RADIUS server.

Before proceeding, make sure your MIRACL Trust RADIUS server is running:

service miracl-radius status

Exit your PAM RADIUS and attempt to ssh back into it using the user you have just added:

ssh john@12.34.56.789 or ssh john.smith@example.com@12.34.56.789

otp create id and create pin

You are given an OTP, which you can enter in your ssh terminal prompt to gain access to the RADIUS server.

SSH Demo Setup

# Ubuntu

# MIRACL Trust RADIUS Setup

# Note on User Authentication

# Configuring Your PAM RADIUS Client

# Open UDP Ports

# Verify Your Configuration

# CentOS

# MIRACL Trust RADIUS Setup

# Note on User Authentication

# Configuring Your CentOS PAM RADIUS Client

# Setup of Ports

# Test Login With OTP