Generic client setup info

When setting up MIRACL Trust RADIUS to work with RADIUS-supporting clients (ssh clients, VPN clients, etc.) there are certain generic points which will apply in all cases. This information should provide all that is needed to configure MIRACL Trust RADIUS to work with any client. It may also be useful to run through our guides to testing MIRACL Trust RADIUS with a simple ssh client or OpenVPN Access Server, to ensure that you are comfortable with the basics of getting the server running and connected properly.

The following points will need addressed in all cases:

Add app client id and secret to core.yaml

First of all open the /etc/miracl-radius/core.yaml config file.

Then, to establish the connection to the authentication platform, add the client_id and client_secret obtained as per Setup and Installation to the mfa section of the config.

Note that you can use the admin portal to set up multiple RADIUS apps and add their Client IDs and Client Secrets for different RADIUS client connections. The below example shows only one, named global:

server:
  address: :1812
protocols:
  - pap
  - chap
  - mschapv1
mfa:
  global:
    client_id: ''
    client_secret: ''

Supported protocols

You must know which RADIUS protocols are supported by the client you are working with, and make sure they are enabled on the MIRACL Trust RADIUS server. This is controlled as above in the /etc/miracl-radius/core.yaml file.

As default, support for pap, chap and mschapv1 is enabled. “peap” can also be enabled by adding it to the includes in /etc/miracl-radius/core.yaml. If so, it is necessary to generate an x.509 private key and public certificate for your MIRACL Trust RADIUS server and add them to /etc/miracl-radius/integrations/peap.yaml:

peap:
  private_key: ''
  public_certificate: ''
protocols:
- peap

To generate a key and certificate, the following terminal command can be used (with the necessary adjustments to your location and domain information). This will create the key and certificate and output them both in single line format, with all the " characters escaped. The terminal output can then be pasted into the config file:

openssl req -x509 -nodes -newkey rsa:2048 -keyout miracl-radius.key -out miracl-radius.crt -days 1000 -subj /C=UK/ST=London/L=London/O=Development/CN=example.com \
&& echo -e "\nCONFIG PRIVATE KEY:\n" \
&& echo $(cat miracl-radius.key | tr -d '\n' | sed -E 's/-----[^-]+-----//g') \
&& echo -e "\nCONFIG PUBLIC CERTIFICATE:\n" \
&& echo $(cat miracl-radius.crt | tr -d '\n' | sed -E 's/-----[^-]+-----//g') \
&& echo ""

Add host details and create shared secret

For your RADIUS client/host (e.g. OpenVPN), create a ‘host’ yaml/json file such as /etc/miracl-radius/hosts/openvpn.yaml (note that multiple hosts can be configured):

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

The following points should be noted:

  1. You must first add the IP address of your host.
  2. mfa is used to invoke the correct app with its Client ID and Client Secret, as detailed at the start of this page.
  3. You must also add an arbitrary shared secret (a strong and hard to guess string) that is also entered on the RADIUS client application you will be connecting to.
  4. The authorize section is used to control who is actually allowed to attempt to login. This can be done using simple regex control of permitted email domains or LDAP for more detailed user verification (explained in more detail in the LDAP Configuration page). In the above example, authorize: true means that anyone is permitted to attempt login. This could be used for testing purposes, to make sure all other configuration is set correctly.
  5. You can also use the mfa_id parameter to allow for logging into e.g. your SSH client with a non-email username. The above commented-out example shows how to extract the prefix from the email you have registered with, 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

An example of a shared secret being added to a client application is found when using a PAM RADIUS client and editing the /etc/pam_radius_auth.conf file to contain the IP address of your MIRACL Trust RADIUS server, as well as the shared secret:

server[:port] shared_secret      timeout (s)
52.xxx.xx.xxx   ********             5

Or in the admin console for OpenVPN Access Server:

opnvpnui1

Accounting

MIRACL Trust RADIUS server supports accounting functionality. RADIUS accounting collects data for statistical purposes and network monitoring and is also employed to enable accurate billing of users. It could be enabled by including in the main config.yaml:

/etc/miracl-radius/integrations/accounting.yaml

server:
  accounting:
    address: :1813
    storage:
      file:
        path: ./acct.log

Currently we support only file storage which will write json lines records of the received accounting packages in the specified file which could be parsed by desired needs.

Ensure correct ports are listening

As can be seen from the above OpenVPN as a screenshot, the default authentication port for RADIUS is 1812. It is important that port 1812 is open on both the client and the MIRACL Trust RADIUS server. This is set in the /etc/miracl-radius/core.yaml file as seen at the start of this page. If you have setup the accounting of MIRACL Trust RADIUS server, you need to assure that port 1813 is open too.

In conjunction with any product-specific documentation for the client you are connecting to, this should give you all the information you need to get set up and begin issuing One Time Passwords to your clients.