How to: Configure LDAP Authentication in SwaggerHub On-Premise

Last modified on October 14, 2021

SwaggerHub On-Premise supports user authentication via LDAP. The users must exist in your LDAP directory. In SwaggerHub On-Premise 1.18.0 and later, access can be limited to specific user groups.

Supported LDAP providers

  • Active Directory
  • OpenLDAP (since SwaggerHub On-Premise v. 1.18.8)

LDAPS (LDAP over TLS) is supported only with TLS 1.2.

Prerequisites

Before enabling LDAP, review the user list on the License page of the Admin Center and make sure the email addresses of all the existing users (including you, the admin) are the same as in your identity provider.

Users with non-matching email addresses will have to update the email address in their SwaggerHub settings. Otherwise, SSO logins will not be linked to those existing users, and SwaggerHub will create new users.

SwaggerHub user list displayed in Admin Center > License

Click the image to enlarge it.

Configure LDAP authentication

  1. Open the Admin Center.

  2. Select Settings on the left.

  3. In the Authentication section, change the Authentication Type to LDAP.

  4. Specify the LDAP settings (see below).

    Notes:

    • LDAP authentication does not use proxy and requires a direct connection from the SwaggerHub VM to your LDAP server.

    • Pay attention to the User ID, Profile name and Email options, and make sure they are mapped to the correct LDAP fields.

      Once users have been created in SwaggerHub, any changes to the Profile name and Email options will break user login. If you need to change these options or fix the usernames or email addresses of existing LDAP users, contact Support.

  5. Click Test LDAP to test the connection to your LDAP server. If the connection fails, double-check your LDAP settings. See the common LDAP errors below for troubleshooting tips.

    Testing LDAP connection
  6. Click Save Changes and Restart.

    In v. 1.19.1 or earlier, click Save Changes, then switch to the System page and click Restart SwaggerHub.

  7. Wait a few minutes for the system to restart completely.

  8. If you use SwaggerHub On-Premise v. 1.20.0 or earlier, follow the instructions on this page to migrate the existing users to single sign-on.

Note: LDAP is used by the main SwaggerHub application. The Admin Center does not use LDAP, it uses the administrator username and password configured during the installation. The administrator can always access the Admin Center even if LDAP is misconfigured.

LDAP settings

Note: Any changes to LDAP settings require SwaggerHub restart in order for the changes to take effect.

Connection Test

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.

Host

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.

LDAP authentication does not use proxy and requires a direct connection from the SwaggerHub VM to your LDAP server.

Certificate

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:

  1. Prepare a PEM file containing the CA root certificate and any required intermediate certificates, in any order. The file should look as follows. Make sure there are no new lines after -----END CERTIFICATE---- at the end of the file.

    -----BEGIN CERTIFICATE-----
    intermediate certificate 1
    -----END CERTIFICATE-----
    -----BEGIN CERTIFICATE-----
    intermediate certificate 2
    -----END CERTIFICATE-----
    -----BEGIN CERTIFICATE-----
    CA root certificate
    -----END CERTIFICATE----

    Some self-signed certificates are their own CA – in this case, use a PEM file containing the actual LDAP server certificate.

  2. If you use SwaggerHub On-Premise 1.19.2 or later:

    • Upload this PEM file to the Certificate Manager.

    • Switch back to Settings > Authentication and select the uploaded PEM file from the Certificate list.

    If you use SwaggerHub On-Premise 1.18.3–1.19.1, upload the PEM file directly to the Certificate option.

Domain search username and password (or LDAP Bind Username and Password in older versions)

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:

  • A simple username, such as ldap-search.

  • A username including the domain name, such as ldap-search@my.domain.com.

  • A name written by using the full distinguished name (DN) syntax, such as:

    CN=LDAP Search,CN=Users,DN=my,DC=domain,DC=com

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.

Domain base

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

DC=my,DC=domain,DC=com

User ID

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:

LDAP usernames vs SwaggerHub usernames

Click the image to enlarge it.

Example 2

User ID = uid, Profile name = uid:

LDAP usernames vs SwaggerHub usernames

Click the image to enlarge it.

Profile name

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:

  1. The values of the specified Profile name fields are concatenated with an underscore as a delimiter.

  2. Characters other than A..Z a..z 0..9 _ . - are replaced with underscores _.

  3. The username is trimmed so that it begins and ends with a letter or number.

  4. If the username already exists, a number is appended at the end (2, 3, …) until the username is unique.

Example 1

Consider a user with the following LDAP fields:

sAMAccountName: jsmith
userPricinalName: jsmith@company.com
cn: Jane Smith
givenName: Jane
sn: Smith
displayName: Jane D. Smith

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

Profile name SwaggerHub Username
sAMAccountName jsmith
cn Jane_Smith
displayName Jane_D_Smith
givenName, sn (same as cn) Jane_Smith
sn, givenName Smith_Jane
userPricinalName jsmith_company.com

Example 2

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

LDAP displayName SwaggerHub Username Comments
John Smith John_Smith  
John_Smith John_Smith2 Since the John_Smith user already exists in SwaggerHub, the new user becomes John_Smith2.
John~Smith John_Smith3 Similarly, number 3 is appended to make the username unique.
Mr. John Smith Jr.! Mr_John_Smith_Jr  

Notes:

  • Once LDAP users are created in SwaggerHub, their assigned usernames are fixed and cannot be changed.

  • Changing the Profile name option will break the login for existing LDAP users. Please contact Support if you need to change this option.

  • An incorrect (misspelled or non-existing) value of Profile name will cause the “Invalid User Name or Password” error during user login.

Email

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.

Email addresses are used to identify LDAP users in SwaggerHub. Any email address changes will break the login for existing LDAP users. Please contact Support if the email addresses of LDAP users need to be updated.

Restricted user groups

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.

Note: This field does not support custom LDAP queries, it accepts only group DNs.

Group filter

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:

  • Active Directory: (member={{dn}}) (default)

  • OpenLDAP: (memberUid={{uid}}) or (uniqueMember={{dn}})

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: bob@example.com
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: alice@example.com
...

# 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).

Troubleshooting

Connection failed: unable to get local issuer certificate [1001]

This means your LDAPS server is using a self-signed certificate or a certificate signed by a private CA. You need to upload your trusted root certificate to SwaggerHub so that it trusts this certificate. See the instructions here.

After you have configured the trusted certificates, click Test LDAP to verify the connection.

Connection failed with status Invalid Bind Credentials, check username/password [1004]

Make sure the Domain search user and Domain search password values are correct.

Connection failed with status 0000202B: RefErr: DSID-0310082F, data 0, 1 access points ref 1 [10]

Make sure the correct LDAP base directory is specified in the Domain base field.

Timeout during user login

Examine the LDAP Group filter option, and if it is

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

change it to one of the following (depending on your LDAP attribute names):

  • Active Directory: (member={{dn}})

  • OpenLDAP: (memberUid={{uid}}) or (uniqueMember={{dn}})

Note: The Group filter option was added in SwaggerHub On-Premise 1.19.3. If you use an earlier version, upgrade to the latest version to be able to use the group filter.

Unable to connect to Diagnostics

This can happen if the DNS name for this server is either incorrect or not resolvable from the VM itself. The option must specify the actual domain name (or IP address) you use to access SwaggerHub in a browser. The "Test LDAP" button uses this DNS name to connect to the internal LDAP diagnostics system, so an incorrect value would cause a connection error.

See Also

Single Sign-On - Overview
Troubleshooting Single Sign-On in SwaggerHub On-Premise

Highlight search results