How to: Configure LDAP Authentication in SwaggerHub On-Premise

After you specify the LDAP settings, click Test LDAP to test the connection to your LDAP server. If the test fails, double-check your LDAP settings.

Required. Your LDAP server in the format ldap(s)://host[:port]. For example, ldap://my.domain.com or ldaps://my.domain.com:636. ldaps:// is supported since SwaggerHub On-Premise 1.18.3.

For ldaps://, we support TLS 1.2. If your ldaps:// server uses a self-signed certificate or a private CA, upload a PEM file containing the trusted certificates to the Certificate Manager, then select it from the Certificate list in SwaggerHub LDAP settings.

Introduced in SwaggerHub On-Premise 1.18.3.

If your ldaps:// server uses a self-signed SSL certificate or a certificate issued by a private Certificate Authority (CA), you need to provide the trusted certificates that can be used to validate the LDAP server certificate. Follow these steps:

Required. The username and password used to query the user directory on your LDAP server. This is usually a service account created specifically for LDAP integrations. This user must have read access to all LDAP users and groups that will be used for SwaggerHub authentication.

The username format depends on your system. It can be:

If your LDAP server uses anonymous bind, leave the username and password blank. Note: Anonymous bind is supported since SwaggerHub On-Premise v. 1.20.0.

Required. The DN of the LDAP directory where the users are stored. For example:

DC=my,DC=domain,DC=com

Introduced in SwaggerHub On-Premise 1.18.8. In previous versions, this is always sAMAccountName.

Required. The LDAP ID field that contains the LDAP logon names of the users. This is typically sAMAccountName for Active Directory and uid for OpenLDAP. SwaggerHub uses this ID field to find users in your LDAP directory.

User ID may or may not be the same as the Profile name. The following examples show the difference between the two.

Example 1

User ID = uid, Profile name = cn:

Example 2

User ID = uid, Profile name = uid:

Introduced in SwaggerHub On-Premise 1.18.2. In previous versions, this is always sAMAccountName.

Required. The LDAP field or fields used to generate SwaggerHub usernames for LDAP users. In the general case, SwaggerHub usernames may differ from LDAP logon names specified by the User ID option. For example, a LDAP user who logs in as jsmith might see John_Smith as the username in SwaggerHub.

For most Active Directory installations, this should be sAMAccountName. Other LDAP providers may have similar fields with other names, such as uid or cn. Note that LDAP field names are case-sensitive.

To use multiple LDAP fields, separate them with commas: givenName, sn. The values of these fields will be concatenated using underscores to create a SwaggerHub username (more on that below).

When a LDAP user logs in to SwaggerHub for the first time, a SwaggerHub username is generated as follows:

Example 1

Consider a user with the following LDAP fields:

sAMAccountName: jsmith
userPricinalName: [email protected]
cn: Jane Smith
givenName: Jane
sn: Smith
displayName: Jane D. Smith

The following table provides examples of SwaggerHub usernames based on different LDAP fields:

Example 2

The following table provides examples of how SwaggerHub usernames are normalized (given that Profile name = displayName).

Notes:

Required. The LDAP field that contains the email address of the user. This is typically userPrincipalName for Active Directory and mail for OpenLDAP. The field name is case-sensitive.

Introduced in SwaggerHub On-Premise 1.18.0.

Optional. The full DNs of the user groups that will be allowed to log in to your SwaggerHub On-Premise instance. Separate multiple groups with semicolons (;). For example:

CN=GDC-SwaggerHub,OU=Groups,OU=Galway,DC=example,DC=com; CN=Developers,CN=Users,DC=example,DC=com

s

If left blank, all the users in the specified Domain base will be able to log in.

Introduced in SwaggerHub On-Premise 1.19.3.

Required. The filter used to fetch a list of groups a user is a member of. In most cases, you need one of these filters:

The filter is a template string in the format:

(GROUP_ATTR={{dn}})
or
(GROUP_ATTR={{uid}})

where GROUP_ATTR is a group attribute that stores the group members, {{dn}} will be replaced with the user’s Distinguished Name (DN), and {{uid}} will be replaced with the user’s uid attribute.

Example 1

Consider the following LDAP objects:

# User
dn: cn=bob, o=example, dc=example, dc=com
userPrincipalName: [email protected]
sAMAccountName: bob
...

# Group
dn: cn=Developers, ou=groups, o=example, dc=example, dc=com
member: cn=alice, o=example, dc=example, dc=com
member: cn=bob, o=example, dc=example, dc=com
...

The group member attribute is member and it contains the user’s DN, so the group filter will be (member={{dn}}).

Example 2

Consider the following LDAP objects:

# User
dn: uid=alice, o=example, dc=example, dc=com
uid: alice
mail: [email protected]
...

# Group
dn: cn=Developers, ou=groups, o=example, dc=example, dc=com
memberUid: alice
memberUid: bob
objectclass: posixGroup
objectclass: top
...

The group member attribute is memberUid and it contains the user’s uid, so the group filter will be (memberUid={{uid}}).

Remarks

SwaggerHub On-Premise instances created using v. 1.19.2 or earlier use the following broad group filter:

(|(member={{dn}})(memberUid={{uid}})(uniqueMember={{dn}}))

It covers most LDAP instance types, but may result in poor performance against large LDAP directories. If you experience large delays or timeouts when logging in, replace the above-mentioned group filter with a specific filter that corresponds to your LDAP server type (for example, use (member={{dn}}) for Active Directory).