SSH demo setup

We will now take you through setting up a basic PAM RADIUS client and configuring both it and your MIRACL Trust SSO RADIUS server to communicate with each other. It will then be possible to generate One Time Passwords that can be used to gain ssh access to the PAM RADIUS client.

These instructions assume that you have installed a running instance of a MIRACL Trust RADIUS app and obtained API keys as detailed in the Installation section of these docs.

When changes have been made to your MIRACL Trust RADIUS config it is necessary to run sudo service miracl-radius restart to apply the changes.

You can follow a tutorial for either a Ubuntu or CentOS Linux machine with PAM RADIUS authentication. Please choose the appropriate tab:

Ubuntu

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

MIRACL Trust SSO 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 SSO RADIUS authentication portal in the Installation section):

server:
  address: :1812
protocols:
  - pap
  - chap
  - mschapv1
mfa:
  global:
    client_id: ''
    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 will mean 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: '********'
    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

For the actual authentication of a user, the MIRACL Trust authentication server must receive an email address (Please see the OTP Generation menu section for an understanding of how an email address is used to register and authenticate once RADIUS/OTP is up and running). Hence the above mfa_id enables a user to use the prefix to their email address for logging into the SSH client, while still presenting the full email address to the MIRACL Trust platform for authentication purposes. For example, while you have registered with `john.smith@example.com, 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 the MIRACL Trust authentication 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.

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)
    5.xxx.xx.xxx   mrtrt_*%&6             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 will work 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 will 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 will 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 SSO 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 SSO RADIUS Server:

sso 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 SSO RADIUS server.

Verify your configuration

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

service miracl-radius status

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 will be 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 will be 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 SSO 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 SSO RADIUS authentication portal in the Installation section):

server:
  address: :1812
protocols:
  - pap
  - chap
  - mschapv1
mfa:
  global:
    client_id: ''
    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 will mean 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: '********'
    mfa_id: '{{.UserID}}@example.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

For the actual authentication of a user, the MIRACL Trust authentication server must receive an email address (Please see the OTP Generation menu section for an understanding of how an email address is used to register and authenticate once RADIUS/OTP is up and running). Hence the above mfa_id enables a user to use the prefix to their email address for logging into the SSH client, while still presenting the full email address to the MIRACL Trust platform for authentication purposes. For example, while you have registered with `john.smith@example.com, 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 the MIRACL Trust authentication 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.

Configuring your CentOS PAM RADIUS Client

  1. Install PAM RADIUS Authentication Module:

    sudo yum -y install epel-release
    sudo yum -y update
    sudo yum -y install pam_radius pam-devel
    
  2. 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

  3. Edit the file /etc/pam_radius.conf and edit the following section thus:

    IP_address(:port)                shared_secret                timeout
    52.xx.xxx.xx.                    mrtrt_*%&6                      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.

  4. Now edit the /etc/ssh/sshd_config file to allow password authentication by editing the following line:

    PasswordAuthentication yes

  5. Restart the SSH service by running:

    sudo service sshd restart

  6. 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 will 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

Test login with OTP

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

You will be 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 will be given an OTP, which you can enter in your ssh terminal prompt to gain access to the RADIUS server.

Docker

To get a test Docker setup running, please follow the instructions in either the Ubuntu or CentOS tab for editing the MIRACL Trust RADIUS server config files and setting up a PAM RADIUS client to log into.

You can then use the config files for your MIRACL Trust RADIUS server to run a test Docker container.

To get the miracl/radius image that is referenced in the following section, please contact MIRACL.

docker run --name=radius --network host -v /home/user/miracl-radius-dockertest/:/etc/miracl-radius miracl/radius:latest -c /etc/miracl-radius/config.yaml

The above command assumes that your config files are stored in the /home/user/miracl-radius-dockertest/ directory.

Once your Docker container is running, make sure that the correct RADIUS port (UDP 1812 and 1813 if accounting is used) is open on both your host and the terminal you are attempting to log in to. Then you should be able to successfully ssh into the terminal.

Note also that the following environment variables are available when using Docker:

  • MIRACLRADIUS_CONFIGPATH - sets the configuration file to start the service with
  • MIRACLRADIUS_LOGLEVEL - sets the Log level to be one of EMERGENCY, ALERT, CRITICAL, ERROR, WARNING, NOTICE, INFO or DEBUG
  • MIRACLRADIUS_DUMP - if set to JSON or YAML, outputs the full configuration, if set to SCHEMA - outputs the JSON schema