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.

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

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

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": "03wgfhdss77bj",
    "client_secret": "urewrfwefjdsfiwefj23rjejfwStd_wJFI",
    "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 RADIUS server and the shared secret (a strong and hard to guess arbtirary string) that should also be entered on the PAM RADIUS client (as seen below):


"host": {
  "52.xxx.xx.xxx": {
    "name": "local",
    "ldap": "global",
    "zfa": "global",
    "secret": "mrtrt_*%&6"
  }
}

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

  • Edit the file /etc/pam_radius_auth.conf and under the line:
    127.0.0.1 secret 1

  • Edit the line:
    IP_address(:port) shared_secret timeout
    Where IP_address is the IP address (and port, if using a RADIUS port other than the port defined in /etc/services) of your MIRACL Trust® SSO server, shared_secret is a string which matches the value entered in the MIRACL Trust® SSO RADIUS admin console, 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 --force-badname john.smith@miracl.com

    The --force-badname parameter is necessary, as an email address is not a uniform unix format for a username

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

    Note that it is possible to add a user with a non-email based username (e.g.johnsmith) if you follow the advanced 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 and attempt to ssh back into it using the user you have just added:

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": "03wgfhdss77bj",
    "client_secret": "urewrfwefjdsfiwefj23rjejfwStd_wJFI",
    "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 RADIUS server and the shared secret (a strong and hard to guess arbtirary string) that should also be entered on the RADIUS server:


"host": {
  "52.xxx.xx.xxx": {
    "name": "local",
    "ldap": "global",
    "zfa": "global",
    "secret": "mrtrt_*%&6"
  }
}

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 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. The MIRACL Trust® server only accepts email addresses as usernames, and 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

    Note that it is possible to add a user with a non-email based username (e.g.johnsmith) if you follow the advanced LDAP instructions

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