LDAP configuration


Table of Contents:


In the ldap section of the config file, it is possible to enter the details of an LDAP server.

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 will be required to authenticate with the lowercase equivalent. For example John.Smith@example.com will need to authenticate as john.smith@example.com

Here you can enter your ldap server details:

"ldap": {
  "server": {
    "global": {
      "method": "plain",
      "address": "52.xx.xx.xxx:389",
      "user": "cn=admin,dc=ldap,dc=example,dc=com",
      "password": "strong_password"
    }
  },
  "query": {
    "query1": {
      "server": "global",
      "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 query for 'query2' which also queries the 'global' server:

  "query": {
    "query1": {
      "server": "global",
      "search": [
        {
        "dn": "ou=dept1,dc=ldap,dc=example,dc=com",
        "filter": "(mail={{.UserID}})"
        }
      ]
    },
    "query2": {
      "server": "global",
      "search": [
        {
        "dn": "ou=dept2,dc=ldap,dc=example,dc=com",
        "filter": "(mail={{.UserID}})"
        }
      ]
    }
  }

The "filter" in the above example programatically 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.

When configuring a RADIUS client application, any queries can then be invoked by the "authorize" parameter within the host section of the config file:

  "authorize": [
    [
      { "email":"^[^@]+@yourcompany.com$"},
      { "ldap":"query1"}
    ]
  ],

Note that the above example shows that regex email filters can be used, which may mitigate the need for some simple LDAP setups.

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

For the json OR list, note that each expression is within its own set of square brackets:

"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:

For the json AND list, note that both expressions are within the one set of square brackets:

"authorize":[
        [{"email":"^[^@]+@example.com$"},{"ldap":"dept1"}]
  ],

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 will demonstrate 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 will be used as the username for your ssh or OpenVPN client.

  2. In your ldap query, you will 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 will need 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 zfa_id field to specify which of the extracted attributes will be used to authenticate with the authentication server (i.e. 'mail').

    Note that the zfa_id feature is only available from version 1.1.0 release 101 and above

In the query2 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": {
      "global": {
        "method": "plain",
        "address": "52.xx.xx.xxx:389",
        "user": "cn=admin,dc=ldap,dc=example,dc=com",
        "password": ""
      }
    },
    "query": {
      "query1": {
        "server": "global",
        "search": [
          {
            "dn": "cn=Users,dc=ldap,dc=example,dc=com",
            "filter": "(mail={{.UserID}})"
          }
        ]
      },
      "query2": {
        "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@50.xxx.xxx.xxx

In "attributes": ["mail"] the program is being told that it still needs to extract the mail attribute for the user as this will need to be used for the actual authentication with the MIRACL Trust authentication server (the LDAP email entry needs to match the email the user has registered with the OTP service). If a particular user profile was needed, other attributes could be specified for extraction, e.g. "attributes": ["mail", "employeeType", "employeeNumber"]

Then query2 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": {
    "54.xxx.xxx.xxx": {
      "name": "pamradius",
      "authorize": [
        [
          {
            "ldap": "query2"
          }
        ]
      ],
      "zfa_id":"{{AttrVal \"mail\" 0 \"\" .Attributes}}",
      "zfa": "global",
      "secret": "strongsecret"
    }
  },

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

For test purposes, it is recommended that you follow the SSH demo setup tutorial, and implement the above instructions.

Top