LDAP and Authorization

# Introduction

A key feature of MIRACL Trust RADIUS server is that it is possible to create filters so that only authorized individuals can attempt to login. There are 2 ways of approaching this:

  1. An LDAP server. You can enter the details of your server in a config file such as /etc/miracl-radius/integrations/ldap.yaml. The ldap config file should then be listed in the includes found in /etc/miracl-radius/config.yaml and the server and query invoked in the authorize subsection in the individual desired host files. Multiple servers and queries can be set up, then each host file can make use of the appropriate queries.
  2. For more basic needs, a simple regex filter can be set to e.g. only allow attempted logins from users in specific email domains. This is done directly in the individual host configuration.

Both methods are invoked in the authorize subsection in the relevant host configuration file (e.g. /etc/miracl-radius/hosts/openvpn.yaml), as per the following example:

host:
  203.0.113.1:
    name: openvpn
    mfa: global
    secret: <SECRET>
    authorize:
    - - email: '^[^@]+@test.com$'

# Basic Usage

Please note that in the MFA platform all identities are converted to lowercase. Hence, if you assign an email containing uppercase characters to a Windows user in Active Directory, the user is required to authenticate with the lowercase equivalent. For example John.Smith@example.com needs to authenticate as john.smith@example.com.

Here you can enter your ldap server details:

ldap:
  server:
    ldap_server:
      method: plain
      address: 203.0.113.1:389
      user: cn=admin,dc=ldap,dc=example,dc=com
      password: <PASSWORD>
  query:
    ldap_profile:
      server: ldap_server
      search:
      - dn: ou=dept1,dc=ldap,dc=example,dc=com
        filter: "(mail={{.UserID}})"

Within the server subsection it is possible to add more than one LDAP server and then have one or more queries for each server within the query subsection. As an example you could add a second query ’ldap_profile2’ which also queries the ‘global’ server:

query:
  ldap_profile:
    server: ldap_server
    search:
    - dn: ou=dept1,dc=ldap,dc=example,dc=com
      filter: "(mail={{.UserID}})"
  ldap_profile2:
    server: ldap_server
    search:
    - dn: ou=dept2,dc=ldap,dc=example,dc=com
      filter: "(mail={{.UserID}})"

The “filter” in the above example programmatically picks up the current UserID value from the RADIUS Server (which is the user’s email address) and checks it with the ‘mail’ attribute on the LDAP server query.

When configuring a RADIUS server, any queries can be invoked by its name in the “authorize” parameter within the host section of the config file:

authorize:
- - email: "^[^@]+@yourcompany.com$"
  - ldap: ldap_profile

The above example shows that regex email filters can be used together with an ldap query. This authorizes users who meet both the email AND ldap query conditions. Some filters may mitigate the need for simple LDAP setups.

It is possible to use authorize queries as boolean OR lists:

authorize:
- - email: "^[^@]+@test.com$"
- - email: "^[^@]+@example.com$"
- - email: "^[^@]+@mycompany.co.uk$"

An AND query can be used to allow, for example, only authorized users from a particular email domain AND who are also in a particular LDAP group:

authorize:
- - email: "^[^@]+@example.com$"
  - ldap: ldap_profile2

# Advanced Usage

The program can be configured to use other LDAP attributes for authentication.

An important point to remember here is to distinguish between authorization (using LDAP to determine whether a user with a specific email address / username is permitted to attempt to authenticate/login) and authentication (the authentication carried out by the MIRACL Trust authentication server, in order to log the authorized user in).

The example below demonstrates how to configure an LDAP user verification setup which allows a user to access a RADIUS client (ssh, OpenVPN etc.) with a non email-based username, whilst still extracting the email of the user in order to carry out the final authentication with the MIRACL Trust authentication server.

The basic points involved are:

  1. In the ldap config section, set your query to use the LDAP filter field to tell the service what LDAP attribute you wish to be used as the .UserID for logging in to your RADIUS client - i.e. what LDAP attribute is used as the username for your ssh or OpenVPN client.

  2. In your ldap query, you also need to use the attributes field to specify which other LDAP attributes need to be extracted. When, as specified in point 1, using another attribute as .UserID, this needs to include mail, as that is what must be used for the actual authentication with the authentication server.

  3. In the host config section, as well as using authorize to invoke the correct ldap query as set up in points 1 and 2, you must use the mfa_id field to specify which of the extracted attributes are used to authenticate with the authentication server (i.e. ‘mail’).

In the ldap_profile2 example below, "filter": "(displayName={{.UserID}})", tells the program to use the LDAP attribute of displayName as the UserID for logging in, as in this openLDAP example.

ldap:
  server:
    ldap_server:
      method: plain
      address: 203.0.113.1:389
      user: cn=admin,dc=ldap,dc=example,dc=com
      password: <PASSWORD>
  query:
    ldap_profile:
      server: ldap_server
      search:
      - dn: cn=Users,dc=ldap,dc=example,dc=com
        filter: "(mail={{.UserID}})"
    ldap_profile2:
      server: global
      search:
      - dn: cn=Users,dc=ldap,dc=example,dc=com
        filter: "(displayName={{.UserID}})"
        attributes:
        - mail

This enables the client being logged into (SSH client, OpenVPN, etc.) to allow the user to login with a simple username rather than an email address:

ssh mike-hewitt@198.51.100.1

In "attributes": ["mail"] the program is being told that it still needs to extract the mail attribute for the user. It is used for authenticating with the MIRACL Trust authentication server (the LDAP email must match the email the user has registered with the OTP service). If a particular user profile is needed, other “attributes” have to be extracted, e.g. "attributes": ["mail", "employeeType", "employeeNumber"].

Then ldap_profile2 is invoked in the host section which specifies the IP of the host (ssh client, OpenVPN etc.), as well as the authorization/LDAP and authentication details:

host:
  203.0.113.1:
    name: pamradius
    authorize:
    - - ldap: ldap_profile2
    mfa_id: '{{AttrVal "mail" 0 "" .Attributes}}'
    mfa: global
    secret: <SECRET>

The key parameter here is mfa_id. This tells the program what extracted LDAP attribute to use for authentication of the user with the MIRACL Trust authentication server.