Advanced Config

In the /integrations subfolder of the server configuration you find an example file structure that can be used to manage advanced settings.

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

Some RADIUS clients require more than one request to the RADIUS server to establish a connection, which is why the MIRACL Trust RADIUS server has an option to increase the uses and attempts with one generated OTP. You can make the following additional config to any apps configured in the mfa section (note that this example refers to an app named global, for which you should have already specified the Client ID and Client Secret in the core.yaml file):

mfa:
  global:
    max_uses: 1
    max_attempts: 3

max_uses controls the number of times an issued OTP can be used before it expires.

max_attempts controls the number of incorrect attempts a user can make before they are blocked. The maximum recommended value for this is 5.

# MIRACL Trust Authentication properties

The MIRACL Trust RADIUS server authenticates to the MIRACL Trust Portal through the OIDC protocol. It runs its own HTTP server to generate OTPs, and all otp settings in the server section are used to configure it. The value of otp_expiration specifies how many seconds an OTP is valid after it is generated.

Here are the default values used for the OTP generation HTTP server:

server:
  address: :1812
  otp_address: :8000
  otp_expiration: 90
  otp_shutdown_timeout: 10
  otp_read_timeout: 10
  otp_write_timeout: 10
  otp_idle_timeout: 10
  otp_read_header_timeout: 2

The following settings are required for the OIDC authentication:

mfa:
  global:
    client_id: <YOUR_CLIENT_ID>
    client_secret: <YOUR_CLIENT_SECRET>
    issuer: https://api.mpin.io
    redirect_url: http://127.0.0.1:8000/login

issuer should always be the issuer of MIRACL Trust Portal https://api.mpin.io.
redirect_url should be an endpoint to the server.otp_address value and should match the Redirect URL in the MIRACL Trust Platform application created here.

# Change Log Level

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

log:
  level: INFO

The level can be set to “ERROR”, “WARN”, “INFO” or “DEBUG”.

Note that it should not be set to DEBUG in a production environment.

# Stats for System Performance

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

The program uses StatsD to collect usage metrics which can then be used with a StatsD-compatible client such as Graphite to visually render key system performance information such as session starts, logins, communicating with the authentication server, spikes in 404 statuses etc.

An example config would be:

stats:
  prefix: miracl-radius
  network: udp
  address: :8125

Note that prefix defines the prefix that is given to each bucket of stats. Address can be in the format of ‘url:port’ or just ‘port’.

The above example would be suitable for a Graphite installation, as Graphite https://github.com/etsy/statsd/blob/master/docs/graphite.md listens on port 8125 by default. A useful Docker image for Graphite can be found at https://github.com/hopsoft/docker-graphite-statsd.

# Session Settings

By default the MIRACL Trust RADIUS server uses internal memory to store its collected logged in sessions. Below is the default config.

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

store:
  memory:
    cleanup_interval: 60

You can specify Redis as external storage. This enables multiple instances of the server to share storage. Redis can be used locally or installed on a separate machine. In a production environment, AWS ElastiCache may be used. You can enable it by including its configuration path in the main service configuration (/etc/miracl-radius/config.yaml):

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

store:
  redis:
    network: tcp
    address: :6379
    password: <PASSWORD>

# Return Attributes

There are cases when you would want to send predefined attributes from the RADIUS server to the RADIUS client. This could be achieved by the host.return_attributes section.

host:
  172.17.0.1:
    name: docker
    authorize:
    - - ldap: ldap_profile
    mfa: global
    secret: <SECRET>
    return_attributes:
      Reply-Message: Hello, from MIRACL
      Acct-Interim-Interval: 600
      Vendor-Specific:
        Fortinet:
          Fortinet-Group-Name: MiraclGroup

The key of the returned attribute should be a valid RADIUS attribute name and its value should be valid type per its specification. Note that it supports vendor-specific attributes as here is the required structure:

return_attributes:
  Vendor-Specific:
    Vendor-ID-Name:
      Vendor-Type1: Value
      Vendor-Type2:
      - Value1
      - Value2