Changing Authentication Method

Last modified on July 27, 2021
Note: This information applies to SwaggerHub On-Premise.

SwaggerHub On-Premise supports several ways of authenticating users:

  • Okta (SAML 2.0)

  • LDAP: Active Directory, OpenLDAP

  • Internal

  • GitHub

  • Internal_and_GitHub (default)

Considerations

  • If your SwaggerHub On-Premise instance is accessible from the public Internet, some authentication methods (Internal and GitHub.com) will potentially allow anyone – including people outside your company – to log in to your SwaggerHub On-Premise instance. This is not a concern when hosting SwaggerHub On-Premise in a private network.

  • In earlier SwaggerHub On-Premise versions (prior to 1.20.1), single sign-on setup included an extra step to migrate existing users to single sign-on. Starting from v. 1.20.1, users are migrated automatically, and the manual migration procedure is no longer needed.

SAML 2.0

SwaggerHub On-Premise supports single sign-on through the SAML 2.0 standard. The users must exist in the identity provider.

We currently support Okta as the identity provider. If you use another identity provider, please contact SmartBear Support for assistance.

LDAP

SwaggerHub On-Premise integrates with Microsoft Active Directory and OpenLDAP for single sign-on. In v. 1.18.0 and later, access can be limited to specific user groups. The users must exist in your LDAP directory.

How to configure LDAP authentication

Internal

Built-in authentication. The usernames and passwords are managed in SwaggerHub.

By default, users can create an account themselves, but you can disable sign-ups to make your SwaggerHub On-Premise portal invite-only.

GitHub

Single sign-on using GitHub user accounts. Both GitHub.com and GitHub Enterprise are supported.

How to configure GitHub authentication

Internal_and_GitHub (default)

A combination of built-in authentication and GitHub single sign-on. GitHub users can log in using their GitHub accounts, and non-GitHub users can create regular accounts in SwaggerHub that have a username and password (the so-called “internal users”). Internal users can link their account to GitHub at any time to enable GitHub sign-on.

Change the authentication method

To change the authentication method for your SwaggerHub On-Premise instance:

  1. Open the Admin Center.

  2. Select Settings on the left.

  3. In the Authentication section, select the desired Authentication Type – SAML, LDAP, Internal, GitHub or Internal_and_GitHub.

  4. Configure other settings for the selected authentication method:

  5. 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.

    Changes to any authentication settings (not just the authentication method) require SwaggerHub restart in order for the changes to take effect.
  6. Wait a few minutes for the system to restart completely.

  7. Important note for versions prior to 1.20.1: If you switched from internal authentication to SAML or LDAP, run the maintenance script to migrate existing users.

See Also

Single Sign-On - Overview
Disabling Account Sign-Ups

Highlight search results