SSH demo setup

Demo setup of logging into a simple SSH client

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 Setup and Installation section of these docs.

When changes have been made to your MIRACL Trust RADIUS config it is necessary to run sudo service srv-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:

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

MIRACL Trust SSO RADIUS setup

Open your /etc/srv-radius/config.json file and make the following adjustments.

Edit the zfa section to include the client id and secret from your app (as created in the MIRACL Trust SSO RADIUS authentication portal in the Setup and Installation section):

"zfa": {
  "global": {
    "client_id": "*********",
    "client_secret": "******************************",
    "otp_endpoint": "https://api.mpin.io/otp",
    "max_uses": 1,
    "max_attempts": 3
  }
},

otp_endpoint should always be set as https://api.mpin.io/otp

Then, in the host section, add the IP of your PAM RADIUS client, plus an arbitrary name and a shared secret (a strong and hard to guess arbtirary 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 zfa_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": "pamradius",
    "zfa_id":"{{.UserID}}@mycompany.com",
    "authorize": [[{"ldap":"global"}]],
    "zfa": "global",
    "secret": "********"
  }
},

Note on user authentication

Note that, 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 zfa_id shows how to extract the username prefix from the email you register with as the username you will use for SSH login, while still presenting the full email address to the MIRACL Trust platform for authentication purposes.

Also note that the default config means that LDAP is effectively disabled, as the global server's LDAP method is set as none (rather than plain or tls). Therefore the above "authorize": [[{"ldap":"global"}]], is OK to use for testing a non-LDAP setup.

As a further note, the zfa_id feature is only available from version 1.1.0 release 101 and above. If you are using a version older than this, you will need to use a full email address for your ssh username. Instructions for this will be given below.

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, which is stored in both the MIRACL Trust RADIUS config.json file and in the PAM RADIUS config file

Finally, in the protocols section, note that the pap protocol is enabled by default. This enables communication with PAM RADIUS:

"protocols": ["pap", "chap", "mschapv1"]

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

    Also note that if you are using a version earlier than 1.1.0 release 101, the zfa_id feature is not available. So you will need to use a full email address as your ssh username: sudo adduser --force-badname john.smith@miracl.com

    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

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 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 srv-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.

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

MIRACL Trust RADIUS setup

Open your /etc/srv-radius/config.json file and make the following adjustments.

Edit the zfa section to include the client id and secret from your app (as created in the MIRACL Trust SSO RADIUS authentication portal in the Setup and Installation section):

"zfa": {
  "global": {
    "client_id": "*********",
    "client_secret": "******************************",
    "otp_endpoint": "https://api.mpin.io/otp",
    "max_uses": 1,
    "max_attempts": 3
  }
},

otp_endpoint should always be set as https://api.mpin.io/otp

Then, in the host section, add the IP of your PAM RADIUS client, plus an arbitrary name and a shared secret (a strong and hard to guess arbtirary 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 zfa_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": "pamradius",
    "zfa_id":"{{.UserID}}@mycompany.com",
    "authorize": [[{"ldap":"global"}]],
    "zfa": "global",
    "secret": "**********"
  }
},

Note on user authentication

Note that, 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 zfa_id shows how to extract the username prefix from the email you register with as the username you will use for SSH login, while still presenting the full email address to the MIRACL Trust platform for authentication purposes.

Also note that the default config means that LDAP is effectively disabled, as the global server's LDAP method is set as none (rather than plain or tls). Therefore the above "authorize": [[{"ldap":"global"}]], is OK to use for testing a non-LDAP setup.

As a further note, the zfa_id feature is only available from version 1.1.0 release 101 and above. If you are using a version older than this, you will need to use a full email address for your ssh username. Instructions for this will be given below.

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, which is stored in both the MIRACL Trust RADIUS config.json file and in the PAM RADIUS config file

Note that, in the protocols section, the pap protocol is enabled by default. This enables communication with PAM RADIUS:

"protocols": ["pap", "chap", "mschapv1"]

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

    If you are using a version earlier than 1.1.0 release 101, the zfa_id parameter is not available and 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, 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 srv-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.

Top