LDAP and authorization


Table of Contents:


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/srv-idp/integrations/ldap.yaml. The ldap config file should then be listed in the includes found in /etc/srv-idp/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$"
"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
  "authorize": [
    [
      { "email":"^[^@]+@example.com$"},
      { "ldap":"ldap_profile"}
    ]
  ],

Basic LDAP usage

In your LDAP config file (/etc/srv-idp/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}})
"ldap": {
  "server": {
    "ldap_server": {
      "method": "plain",
      "address": "127.0.0.1:389",
      "user": "cn=admin,dc=ldap,dc=example,dc=com",
      "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}})
  "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 programatically 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 require the use of custom attributes for authentication. MIRACL Trust SSO can be used to extract both basic LDAP attributes (cn, givenName, etc.) and custom attributes (such as ImmutableID for Office 365). The configuration of LDAP attribute extraction is done as follows:

  1. In the SP config file, a profile section should be created with an attribute subsection. Here the attributes to be extracted are set. the following example from Datadog shows eduPersonPrincipalName, sn and givenName being set as attributes (all of which use SessionUserEmail):

    profile:
      attribute:
        datadog: >-
          <AttributeStatement>{{ if not (eq .SessionUserEmail "")}}
            <Attribute FriendlyName="eduPersonPrincipalName" Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.6" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
              <AttributeValue xmlns:XMLSchema-instance="http://www.w3.org/2001/XMLSchema-instance" XMLSchema-instance:type="xs:string">{{.SessionUserEmail}}</AttributeValue>
            </Attribute>
            <Attribute FriendlyName="sn" Name="urn:oid:2.5.4.4" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
              <AttributeValue xmlns:XMLSchema-instance="http://www.w3.org/2001/XMLSchema-instance" XMLSchema-instance:type="xs:string">{{.SessionUserEmail}}
            </AttributeValue>
            </Attribute>
            <Attribute FriendlyName="givenName" Name="urn:oid:2.5.4.42" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
              <AttributeValue xmlns:XMLSchema-instance="http://www.w3.org/2001/XMLSchema-instance" XMLSchema-instance:type="xs:string">{{.SessionUserEmail}}</AttributeValue>
            </Attribute>{{end}}
          </AttributeStatement>

    "profile": {
      "attribute": {
        "datadog": "<AttributeStatement>{{ if not (eq .SessionUserEmail \"\")}}  <Attribute FriendlyName=\"eduPersonPrincipalName\" Name=\"urn:oid:1.3.6.1.4.1.5923.1.1.1.6\" NameFormat=\"urn:oasis:names:tc:SAML:2.0:attrname-format:uri\">\n    <AttributeValue xmlns:XMLSchema-instance=\"http://www.w3.org/2001/XMLSchema-instance\" XMLSchema-instance:type=\"xs:string\">{{.SessionUserEmail}}</AttributeValue>\n  </Attribute>\n  <Attribute FriendlyName=\"sn\" Name=\"urn:oid:2.5.4.4\" NameFormat=\"urn:oasis:names:tc:SAML:2.0:attrname-format:uri\">\n    <AttributeValue xmlns:XMLSchema-instance=\"http://www.w3.org/2001/XMLSchema-instance\" XMLSchema-instance:type=\"xs:string\">{{.SessionUserEmail}}\n  </AttributeValue>\n  </Attribute>\n  <Attribute FriendlyName=\"givenName\" Name=\"urn:oid:2.5.4.42\" NameFormat=\"urn:oasis:names:tc:SAML:2.0:attrname-format:uri\">\n    <AttributeValue xmlns:XMLSchema-instance=\"http://www.w3.org/2001/XMLSchema-instance\" XMLSchema-instance:type=\"xs:string\">{{.SessionUserEmail}}</AttributeValue>\n  </Attribute>{{end}}\n</AttributeStatement>"
      }
    }
  2. In the ldap config file (/etc/srv-idp/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={{.Email}})"
            attributes:
            - cn
            - givenName

    "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={{.Email}})",
              "attributes": ["cn", "givenName"]
              }
          ]
        }
      }
    }
  3. In the SP config file (/etc/srv-idp/service_providers/example_sp.yaml) the attribute profile and ldap query are then invoked in the authorize and profile subsections:

    sp:
      example_sp:
        description: ''
        issuer: ''
        relay_state: "/"
        login_url: ''
        logout_url: ''
        slo_url: ''
        metadata: ''
        sign_response: true
        sign_assertion: true
        encrypt_assertion: false
        user_id_transform:
        - {}
        authorize:
        - - ldap: ldap_profile
        profile:
          assertion: global
          nameid: global
          attribute: example_sp
          response: global
          signature: global

    "sp": {
        "exampleco": {
        "description": "",
        "issuer": "",
        "relay_state": "/",
        "login_url": "",
        "logout_url": "",
        "slo_url": "",
        "metadata": "",
        "sign_response": true,
        "sign_assertion": true,
        "encrypt_assertion": false,
        "user_id_transform": [
            {}
        ],
        "authorize": [
            [
            {
                "ldap": "query1"
            }
            ]
        ],
        "profile": {
            "assertion": "global",
            "nameid": "global",
            "attribute": "exampleco",
            "response": "global",
            "signature": "global"
        }
        }
    }

Top