Configuring GitHub Integration

Last modified on October 14, 2021

Note: This information applies to SwaggerHub On-Premise.

GitHub integration enables the following features in SwaggerHub On-Premise:

  • GitHub Sync integration,
  • user sign-in and login via GitHub.

SwaggerHub On-Premise supports both GitHub.com and GitHub Enterprise.

Prerequisites

To set up GitHub integration, you must be an organization owner in GitHub and an admin in SwaggerHub.

Considerations

If your SwaggerHub On-Premise instance is accessible from the public Internet and uses GitHub.com as the authentication method, anyone who has a GitHub.com account – including people outside your company – will potentially be able to log in to SwaggerHub.

This is not a concern when hosting SwaggerHub On-Premise behind a firewall or when using GitHub Enterprise.

In GitHub

First, you need a GitHub client ID and a client secret. To get them, follow these steps to register SwaggerHub as an OAuth application on GitHub:

  1. Log in to GitHub as an owner of your GitHub organization.

  2. Click your profile photo and select Settings from the menu.

  3. In the sidebar, under Organization settings, click your organization.

    Accessing organization settings on GitHub

    Click the image to enlarge it.

  4. In the sidebar, click OAuth Apps (if you use GitHub.com) or OAuth applications (if you use GitHub Enterprise).

  5. Create a new OAuth application.

    Creating a new OAuth app

    Click the image to enlarge it.

  6. Enter the following:

    • Application name –SwaggerHub

    • Homepage URL – http(s)://{SWAGGERHUB}

    • Authorization callback URL – http(s)://{SWAGGERHUB}/apiproxy

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

  7. Click Register application.

  8. Copy the generated Client ID and Client Secret.

    GitHub client ID and secret

    Click the image to enlarge it.

In SwaggerHub On-Premise

  1. Open the Admin Center.

  2. Select Settings > Integrations on the left.

  3. Configure the settings as described below.

    GitHub.com

    You need to specify only the client ID and secret. The other options are pre-filled, but we provide the values below for reference:

    • Authentication Type – To enable user authentication via GitHub, use of the following authentication types:

      • Internal_and_GitHub (default) – both built-in authentication and GitHub authentication can be used.

      • GitHub – authentication via GitHub only. Built-in authentication is disabled.

      Note: GitHub authentication is incompatible with SAML and LDAP single sign-on.
    • GitHub UI location – https://github.com

    • GitHub API URL – https://api.github.com

    • GitHub Client ID and GitHub Client Secret – Paste the client ID and client secret that you generated earlier.

    • GitHub Authorization Endpoint – https://github.com/login/oauth/authorize

    • GitHub Token Endpoint – https://github.com/login/oauth/access_token

    GitHub Enterprise

    • Authentication Type – To enable user authentication via GitHub, use of the following authentication types:

      • Internal_and_GitHub (default) – both built-in authentication and GitHub authentication can be used.

      • GitHub – authentication via GitHub only. Built-in authentication is disabled.

      Note: GitHub authentication is incompatible with SAML and LDAP single sign-on.
    • GitHub UI location – Your GitHub server URL, for example, https://ghe.MyCompany.com or http://10.10.10.10:8080.

    • GitHub API URL – http(s)://{GITHUB-SERVER}/api/v3

    • GitHub Client ID and GitHub Client Secret – Paste the client ID and client secret that you generated earlier.

    • GitHub Authorization Endpoint – http(s)://{GITHUB-SERVER}/login/oauth/authorize

    • GitHub Token Endpoint – http(s)://{GITHUB-SERVER}/login/oauth/access_token

    Replace {GITHUB-SERVER} above with your GitHub server domain or IP address.

  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.

Using GitHub Integration

GitHub Sync integration will now work with the GitHub server you chose – GitHub.com or GitHub Enterprise.

GitHub integration settings

Click the image to enlarge it.

Additionally, if you use GitHub authentication, users will be able to create SwaggerHub accounts using GitHub and to link their existing accounts to GitHub.

See Also

Configuring SwaggerHub On-Premise

Highlight search results