Configuring LDAP authentication for Microsoft Active Directory

To configure LDAP for MetalSoft a series of configurations are required on both the MetalSoft side and also on the Identity Provider side to ensure that MetalSoft uses the correct attributes.

The following are the attributes that need to be configured and an example configuration using Microsoft Active Directory. These are changed in the Admin UI under Global Configuration/Authentication and ticking Enable LDAP Authentication.

Caution

When testing the configuration, we strongly suggest keeping “Enable built-in Authentication enabled until LDAP authentication and login have been confirmed as working.

1. LDAP URL: ldap://saml-test.ad.metalsoft.dev:389
2. LDAP User Search Base: ou=adfsusers,dc=ad,dc=metalsoft,dc=dev
3. LDAP User Search Filter: (userPrincipalName={{username}})
4. LDAP Group Search Base: ou=adfsGroups,dc=ad,dc=metalsoft,dc=dev
5. LDAP Group Search Filter: (member={{dn}})
6. LDAP Bind DN: `cn=adfsadmin,ou=adfsusers,dc=ad,dc=metalsoft,dc=dev“
7. LDAP Bind Credentials: (As set for adfsadmin)
8. LDAP Allowed Domains: ad.metalsoft.dev

After this is set up, the following groups must be set up (LDAP Group-MetalSoft role):

• MS-Model_root - root
• MS-Model_FullAdmin - full_admin
• MS-Model_BasicAdmin - basic_admin
• MS-Model_User - user

Caution

If a user is part of multiple groups, the user will be a member of the highest group (i.e. if a member of MS-Model_User and MS-Model_root, the user will have root permissions).

Within LDAP, the following fields are used by MetalSoft:

• userPrincipalName - Used to Log in
• mail - Used to identify user (if a user who is a built in user, then the mail address will be matched with the email address field in MetalSoft)
• sAMAccountName - Used to populate the user name in MetalSoft
• Group (as above) - Used to assign the role to the user

Adding a user in the group MS-Model_FullAdmin will be mapped to a full_admin role in MetalSoft.

Once the LDAP configuration and the groups have been set up, the users will be able to log in.

Caution

If a user is set up as a built in user, and then domain is then changed to LDAP, the built in user will be converted to an LDAP user and the role will be changed according to the group the user is assigned to.

Caution

Currently, if a user is archived, they will not be able to be converted to an LDAP user. The user will have to be un-archived before they can log in using LDAP.

Managing custom LDAP group-to-role mappings via the CLI

By default, Metalsoft ships with a fixed set of LDAP group-to-role mappings (e.g. MS-Model_FullAdmin → full_admin). If your organization uses different group names, or if you need to map groups to custom roles, you can manage these mappings using the CLI.

All mapping commands are under metalcloud-cli auth ldap.

Listing current mappings

metalcloud-cli auth ldap mapping-list

Output shows each configured mapping with its group name, role, and priority.

Adding a mapping

metalcloud-cli auth ldap mapping-add "group_name" --role-name <role> --priority <number>

The --priority flag controls which role wins when a user belongs to multiple mapped groups. Lower numbers take precedence. The default priority is 10. If two mappings share the same priority the behavior is undefined, so use distinct values.

# Map "Domain Admins" to the admin role with highest priority
metalcloud-cli auth ldap mapping-add "Domain Admins" --role-name admin --priority 1

# Map "Power Users" to a custom role
metalcloud-cli auth ldap mapping-add "Power Users" --role-name power-user --priority 5

# Map "Developers" with lower priority
metalcloud-cli auth ldap mapping-add "Developers" --role-name developer --priority 10

Updating a mapping

You can change the role, the priority, or both for an existing mapping:

# Change only the role
metalcloud-cli auth ldap mapping-update "Power Users" --role-name senior-developer

# Change only the priority
metalcloud-cli auth ldap mapping-update "Developers" --priority 15

# Change both
metalcloud-cli auth ldap mapping-update "Guests" --role-name read-only --priority 20

Removing a mapping

metalcloud-cli auth ldap mapping-remove "Guests"

This is irreversible. To restore the mapping, use mapping-add again.

Caution

Removing a mapping does not affect users who are already logged in, but the next time they authenticate via LDAP they will no longer receive the role associated with that group.

---

Adding custom CAs

If your environment uses an SSL certificate that is privately generated (from own corporate CA), you will need to add the certificate to the system so that it can be used to authenticate the LDAP server. Uncomment the following environment variable setting on the authentication microservice YAML manifest:

- name: NODE_EXTRA_CA_CERTS
  valueFrom:
     configMapKeyRef:
        name: common
        key: node_extra_ca_certs

Disabling TLS authentication

NOT RECOMMENDED: To disable TLS verification edit the authentication microservice manifest and uncomment:

- name: NODE_TLS_REJECT_UNAUTHORIZED
  value: "0"