LDAP

Introduction

A key feature of MIRACL Trust SSO 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-sso/integrations/ldap.yaml. The ldap config file should then be listed in the includes found in /etc/miracl-sso/config.yaml and the server and query invoked in the authorize subsection in the individual SP files. Multiple servers and queries can be set up, then each SP 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 SP config file.

Both methods are invoked in the authorize subsection in the relevant SP configuration file, as per the following example:

sp:
  example_sp:
    description: An example SAML service provider configuration
    issuer: http://example.com
    relay_state: /
    login_url: http://example.com/login
    logout_url: http://example.com/logout
    metadata: >-
    authorize:
    - - email: "^[^@]+@example.com$"
      - ldap: ldap_profile

Please note that in the authentication 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

Basic regex domain filtering

The following example shows an OR list of regex domains, meaning that users from any of the three listed domains are authorized to attempt login. For the YAML OR list note that each expression is a double dash. For the json OR list, each expression is within its own set of square brackets:

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

The following example is an AND query (in yaml the first expression is a double dash and the second is a single dash. While in JSON both expressions are within the one set of square brackets). This allows, for example, only authorized users from a particular email domain AND who are also in a particular LDAP group (configuring LDAP will be explained in more detail below).

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

Basic LDAP usage

In your LDAP config file (/etc/miracl-sso/ldap.yaml) you can enter your ldap server details:

ldap:
  server:
    ldap_server:
      method: plain
      address: 127.0.0.1:389
      user: cn=Directory Manager
      password: secret
  query:
    ldap_profile:
      server: ldap_server
      search:
      - dn: ou=people,dc=example,dc=com
        filter: (mail={{.Email}})

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 ‘ldap_profile2’ which also queries the ‘ldap_server’ server:

query:
 ldap_profile:
  server: ldap_server
  search:
  - dn: ou=people,dc=example,dc=com
    filter: (mail={{.Email}})
 ldap_profile2:
  server: ldap_server
  search:
  - dn: ou=dept2,dc=example,dc=com
    filter: (mail={{.Email}})

The “filter” in the above example programmatically picks up the current user’s email address from the IdP and checks it with the ‘mail’ attribute on the LDAP server.

Advanced LDAP usage

Some Service Providers have particular requirements for the extraction of LDAP attributes (such as ImmutableID for Office 365).

With MIRACL Trust SSO there are two types of attributes that can be passed:

  1. Attributes which are programmatically picked up from the SSO IdP to pass on to the SP. In an attribute statement these are passed as variables within the AttributeValue tags. Examples being <AttributeValue>{{.NameID}}</AttributeValue> or <AttributeValue>{{.MetadataEntityID}}</AttributeValue>. An explanation (along with a table of available variables) of how this is done can be found in the Generic Setup Instructions

  2. Attributes which are extracted from an LDAP server before being passed on to the SP. In an attribute statement these are passed as {{AttrVal}} variables within the AttributeValue tags. An example being <AttributeValue>{{AttrVal "uid" 0 "" .Attributes}}</AttributeValue>. This is explained in more detail below.

The use case here is as follows:

  1. For the user attempting to register/login, grab an LDAP attribute from the LDAP server

  2. The MIRACL Trust SSO passes this value to the Service Provider (which should be expecting to receive the custom LDAP attribute for the user in order to match with its own records)

  3. The Service Provider checks that the value passed for the user matches what they have.

These steps are managed thus:

  1. In the ldap config file (/etc/miracl-sso/integrations/ldap.yaml) the attributes to be used are made available in an ldap query:

    ldap:
      server:
        ldap_server:
          method: plain
          address: 52.xx.xx.xxx:389
          user: cn=admin,dc=ldap,dc=example,dc=com
          password: strong_password
      query:
        ldap_profile:
          server: ldap_server
          search:
          - dn: ou=dept1,dc=ldap,dc=example,dc=com
            filter: "(mail={{.UserID}})"
            attributes:
            - departmentNumber
    
  2. In the SP config file (/etc/miracl-sso/service_providers/example_sp.yaml), a profile section should be created with an attribute subsection. This names the attribute according to what the SP is expecting (dept_code in this example), and passes the LDAP attribute (departmentNumber) as extracted in step 1 (note the use of AttrVal which identifies that this is an LDAP atttribute). The ldap query is invoked in the authorize subsection, while the attribute profile is invoked in the profile subsection:

    profile:
      attribute:
        example_sp: >-
          <AttributeStatement>
            <Attribute Name="dept_code">
              <AttributeValue>{{AttrVal "departmentNumber" 0 "" .Attributes}}</AttributeValue>
            </Attribute>
          </AttributeStatement>
    sp:
      example_sp:
        description: An example SAML service provider configuration
        issuer: http://example.com
        relay_state: "/"
        login_url: http://example.com/login
        logout_url: http://example.com/logout
        slo_url: ''
        metadata: >-
        authorize:
        - - ldap: ldap_profile
        profile:
          attribute: example_sp