How to: Single Sign-On With Okta

Last modified on October 14, 2021

This information applies to SwaggerHub On-Premise.

Okta is a SAML identity provider (IdP) that can be used to authenticate with SwaggerHub On-Premise. Integrating SwaggerHub with Okta includes the following steps:

  • Adding SwaggerHub as an application in Okta.

  • Assigning the SwaggerHub application to Okta users and groups.

  • Specifying Okta details in the SwaggerHub configuration.

Prerequisites

Before enabling Okta SSO, 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.

Add SwaggerHub as an application to Okta

  1. Log in to Okta as an admin.

  2. If you are on the developer dashboard (as indicated by the < > Developer Console label in the top left corner), switch to Classic UI.

    Okta Classic UI

    Click the image to enlarge it.

  3. Click Applications and then Add Application.

    Adding an application in Okta

    Click the image to enlarge it.

  4. Click Create New App.

    Create New App
  5. Select Web as the platform, SAML 2.0 as the sign-in method and click Create.

    Creating a SAML 2.0 application in Okta

    Click the image to enlarge it.

  6. Enter SwaggerHub as the App name and click Next.

  7. Specify the following settings:

    SAML 2.0 settings

    Click the image to enlarge it.

    • Single sign on URL – http(s)://{SWAGGERHUB}/login/callback

    • Audience URI (SP Entity ID) – http(s)://{SWAGGERHUB}/login/callback

      Replace {SWAGGERHUB} with the domain name or IP address of your SwaggerHub instance. Use https:// if SSL access is enabled, otherwise, use http://.

    • Name ID format – EmailAddress

    • Attribute statements:

      Name Name format Value
      email Unspecified user.email
  8. Leave everything else by default and click Next.

  9. On the feedback page, select I’m an Okta customer adding an internal app, and click Finish.

  10. Switch to the Sign On tab and click View Setup Instructions.

    View Setup Instructions

    Click the image to enlarge it.

  11. This will open a new browser tab containing SAML metadata that you will later have to specify in SwaggerHub to complete the integration. Keep this tab open for now.

Assign SwaggerHub to Okta users

Next, configure which Okta authenticated users will have access to SwaggerHub:

  1. In Okta, go to Applications and click Assign Applications.

    Assign Applications

    Click the image to enlarge it.

  2. On the left, select the SwaggerHub application, and on the right select the users that need access to SwaggerHub.

    Assigning users to the SwaggerHub application in Okta

    Click the image to enlarge it.

  3. Click Next and confirm the assignments.

Configure SwaggerHub

  1. Open the Admin Center.

  2. Select Settings on the left.

  3. Under Integrations & Authentication, specify the following:

    • Authentication Type – change to SAML.

    • SAML Identity Provider EntityID (Issuer) – paste Okta’s Identity Provider Issuer value.

    • SAML Identity Provider SSO URL – paste Okta’s Identity Provider Single Sign-On URL.

    • SAML Identity Provider Certificate – paste Okta’s X.509 Certificate here, including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines.

    SAML settings in SwaggerHub

    Click the image to enlarge it.

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

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

Migrate existing SwaggerHub users to single sign-on

This information applies to SwaggerHub On-Premise versions prior to 1.20.1.

In earlier SwaggerHub On-Premise versions, the existing internal users (such as the admin user) need to be enabled for SSO before they can log in via Okta. To learn how to do this, see Migrating Existing Users to Single Sign-On.

Test single sign-on

To test SSO initiated from SwaggerHub:

  1. Log out from SwaggerHub and from Okta.

  2. (Recommended) Open a new browser tab in incognito mode.

  3. Open the SwaggerHub home page and click Log In.

  4. You will be redirected to Okta.

  5. Log in to Okta using your Okta credentials.

You will be redirected to SwaggerHub and will be logged in.

To test SSO initiated from Okta:

  1. Log out from SwaggerHub

  2. In Okta, navigate to My Applications.

  3. Click SwaggerHub in the application list.

You will be redirected to SwaggerHub and will be logged in automatically.

Troubleshooting

If you experience errors when logging in to SwaggerHub via Okta, see the Troubleshooting page for tips to resolve common issues.

See Also

Single Sign-On

Highlight search results