MIRACL RADIUS Server

MIRACL Trust RADIUS is a RADIUS server implementing authentication, authorization and accounting. It could be configured to communicate with one or more RADIUS-supporting clients so they gain access to a particular network resource using One Time Passwords (OTPs). You can generate OTPs by visiting your configured OTP address URL in your web browser. They are valid for a default of 90 seconds. MIRACL Trust RADIUS server could be configured to authenticate using one of the following authentication mechanisms - PAP, CHAP, MSCHAPv1, and PEAPv0-MSCHAPv2 which allows you to authenticate through a secure tunnel.

Once installed, the use of MIRACL Trust RADIUS server involves managing a set of config files which are located in the /etc/miracl-radius/ directory.

The steps involved are:

  1. Register in the MIRACL Trust Portal and create a new MIRACL Trust OIDC app. The authentication to the MIRACL Trust platform uses OIDC and you need OIDC credentials to configure your RADIUS server. You can generate an OTP by its OTP Address following this guide.

  2. Install your MIRACL Trust RADIUS server.

  3. Configure your MIRACL Trust RADIUS server and RADIUS client / VPN server (simple ssh client, OpenVPN, Cisco Anyconnect etc.).

  4. End users can then visit the OTP generation URL in their browser to generate One Time Passwords for a specific email which allow them to log in to the RADIUS client / VPN server with the registered User ID email and the generated OTP as a password.

# Server Configuration

The configuration of MIRACL Trust RADIUS server is managed using config files stored in the /etc/miracl-radius/ directory. The functions served by these files can be split into separate files and then loaded by the main config.yaml file which lists the files to be loaded as ‘includes’. The config.yaml file could include all of the configuration itself in one large file, but it is recommended to split and name the files into a logical structure that enables more modular management of functionality and hosts. Note that MIRACL Trust supports config files in both YAML and JSON format. Throughout the documentation, however, we are using YAML.

Note that the default example layout and naming of the config files are only for guidance, and you can choose a different structure and naming system and describe it in the include section of the main config.yaml file.

/etc/miracl-radius/
├── config.yaml
├── core.yaml
├── hosts
│   └── example.yaml
│   └── fortigate.yaml
│   └── openvpn.yaml
│   └── sshtest.yaml
└── integrations
    ├── accounting.yaml
    ├── ldap.yaml
    ├── log.yaml
    ├── peap.yaml
    ├── redis.yaml
    ├── stats.yaml
    └── mfa.yaml

The config.yaml file simply lists the other files to be included. The following example shows that you are only including core.yaml hosts/openvpn.yaml and integrations/ldap.yaml:

includes:
  - core.yaml
#  - hosts/example.yaml
  - hosts/openvpn.yaml
#  - hosts/sshtest.yaml
#  - integrations/log.yaml
  - integrations/ldap.yaml
#  - integrations/mfa.yaml
#  - integrations/peap.yaml
#  - integrations/redis.yaml
#  - integrations/stats.yaml

core.yaml contains the basic details of your MIRACL Trust RADIUS server installation, plus the Client ID and Client Secret obtained from the MIRACL Trust Portal. Note that the RedirectURL of the app should be an endpoint to the RADIUS server OTP address as it’s part of the OIDC authentication to the MIRACL Trust Platform.

In the hosts/ subfolder, you can configure multiple hosts for OTP access (ssh clients, VPN clients, etc.).

LDAP and other advanced settings can be configured in the integrations/ subfolder. For more information, see the LDAP and authorization and Advanced config sections.

Note that settings in files lower down the list of includes override the settings in those higher in the list. For example, if you include a file which specifies a server port number, this overrides a server port number set in a file higher in the list of includes.

When changes have been made to your MIRACL Trust RADIUS server config files (in the /etc/miracl-radius/ directory), it is necessary to restart the service so changes can apply.

You can find an explanation of making necessary configurations in the Generic client setup info and SSH demo or OpenVPN demo pages.

# Component Diagram

The following diagram gives a high-level overview of the components involved:

graph LR A(MIRACL Trust\n RADIUS server) -- RADIUS protocol <--> B{VPN Server \nRADIUS capable} B <--> D{VPN Client} A -- OIDC protocol <--> E(MIRACL Trust\nMFA Platform) A -- LDAP protocol<--> C((LDAP Server))

  1. The user authenticates with MIRACL Trust Platform and is given an OTP valid for a default of 90 seconds.
  2. The user uses the generated OTP as a password and their associated User ID as a username.
  3. The RADIUS server authorises the User ID with LDAP if configured to.
  4. The VPN server verifies the OTP for the user and the user is logged in.