Install an SSL Certificate to SwaggerHub On-Premise 1.18.5–1.19.1

Note: This guide explains the SSL certificate setup for SwaggerHub On-Premise v. 1.18.5–1.19.1. If you use a later version, see here.

HTTPS access to SwaggerHub On-Premise can be implemented in two ways. One way is to install an SSL certificate in your SwaggerHub On-Premise instance.

Requirements for SSL certificates

You can get an SSL certificate from a Certificate Authority (CA) of your choice or use a self-signed certificate. The certificate must meet these requirements:

  • Your SwaggerHub domain name must match the certificate Common Name (CN) or one of the Subject Alternative Name (SAN) entries. For example, if you want to host SwaggerHub at https://swaggerhub.acme.com, then swaggerhub.acme.com must be specified in the certificate CN or SAN, or you can use a wildcard certificate for *.acme.com.

    Note

    CN cannot be an IP address; it must be a resolvable fully qualified domain name (FQDN) or a wildcard domain. IP addresses can be specified only as SAN entries in the certificate.

  • Self-signed certificates are supported starting with SwaggerHub On-Premise 1.18.6. See below for more details.

  • The certificate and private key must be in the PEM format as shown below. The typical extension is .pem, but it may also be .key (for private keys), .cer, .crt, .cert or other. You can convert your certificate to the PEM format by using OpenSSL tools.

    The PEM file must contain your SwaggerHub server certificate, any required intermediate certificates (without the root certificate), and the private key joined together. If intermediate certificates are included, the certificate order must be such that each one certifies the one before it. PEM files are text files, so you can use any text editor to combine the files.

    -----BEGIN CERTIFICATE-----
certificate contents
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
intermediate certificate 1
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
intermediate certificate 2
-----END CERTIFICATE-----
-----BEGIN PRIVATE KEY-----
private key contents
-----END PRIVATE KEY-----

    Important

    There must be no blank lines at the beginning and end of the file, and between the -----BEGIN and -----END lines.

  • The private key must be in the PKCS #8 format (beginning with -----BEGIN PRIVATE KEY-----).

    PKCS #1 private keys (beginning with -----BEGIN RSA PRIVATE KEY-----) can be converted to PKCS #8 using this command:

    openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in old.key -out new.key

  • The private key must not be encrypted.

  • The certificate must be valid (not expired) at the time of upload.

  • If you have Mac users with macOS Catalina (version 10.15), make sure your SwaggerHub server certificate matches the macOS Catalina security requirements. For example, certificates issued after July 1, 2019, cannot have a validity period longer than 825 days.

Considerations for self-signed certificates

Introduced in SwaggerHub On-Premise 1.18.6.

If your SSL certificate is self-signed or issued by a private CA, then, in addition to the certificate itself, you need to provide another PEM file containing the CA bundle – root and intermediate certificates used to establish the full chain of trust. This is required so that SwaggerHub subsystems can trust your self-signed certificate.

The order of certificates in the CA bundle PEM file must be such that each one certifies the one before it. That is, lower-level certificates first, the root certificate last.

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

Important

There must be no blank lines at the beginning and end of the file, and between the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines.

Some self-signed certificates are their own CA. In this case, you will need to upload the certificate with the private key to SSL Certificate, and the certificate without the private key to SSL Certificate Trust Chain.

Install SSL certificate

  1. Open the Admin Center.

  2. Select Settings on the left.

  3. In the Basic Settings section:

    • In the DNS name for this server field, enter the domain name you will use for SwaggerHub. This domain must resolve to the IP address of your SwaggerHub On-Premise instance. The value must also match the common name (CN) or one of the subject alternate names (SAN) of your SSL certificate. Do not include https:// at the beginning and / at the end.

      Correct: swaggerhub.mycompany.com

      Incorrect: https://swaggerhub.mycompany.com/

  4. In the Privacy section:

    • Change the SSL Termination setting to Use SSL with termination on SwaggerHub (certificate required).

    • Upload your SSL Certificate (a PEM file containing the certificate, any required intermediate certificates, and private key; see above).

      Important

      Click Upload to complete the upload.

      Installing SSL certificate

      Notes:

      • If you get an error that says, "failed to save configuration values: SSL certificate is mandatory for enabling SSLTermination", make sure to click Upload in the SSL Certificate field.

      • If you get the “Invalid certificate format” error, refer to the Troubleshooting tips below.

    • For SwaggerHub On-Premise 1.18.6 and later: If your SSL certificate is self-signed or issued by a private CA, upload your SSL Certificate Trust Chain (CA bundle PEM file, see above).

      Important

      Click Upload to complete the upload.

  5. Click Save Changes.

  6. Select System on the left and click Restart SwaggerHub to apply the changes. Wait a few minutes for the system to restart completely.

Test HTTPS

To make sure HTTPS works, navigate to https://your-swaggerhub-domain in various browsers. You should see the SwaggerHub home page with the lock icon in the browser address bar. If you access SwaggerHub via http://, it should automatically redirect to https://.

HTTPS indicator in browser

If you see certificate validation errors, you are probably using a self-signed certificate, or the PEM file is missing intermediate certificates or the private key. Double-check your PEM file to make sure it has the correct format.

View certificate information

Once a certificate has been installed in SwaggerHub On-Premise, you can use your browser to view the certificate information, including the dates the certificate is valid for.

  • In Chrome, click the lock icon in the address bar, then click Certificate.

  • In Firefox, right-click the page and select View Page Info, then switch to the Security tab and click View Certificate.

Alternatively, you can view the certificate information using OpenSSL tools:

openssl s_client -connect Your.SwaggerHub.Domain:443

Renew certificate

To replace an existing SSL certificate, simply upload a new PEM file in the Admin Center. The new certificate will replace the old one.

Troubleshooting

“Invalid certificate format” when uploading the PEM file

A PEM file will be rejected in the following cases:

  • The PEM file does not include the private key.

  • The private key is not in the PKCS #8 format (-----BEGIN PRIVATE KEY-----).

  • The private key is encrypted (-----BEGIN ENCRYPTED PRIVATE KEY-----).

  • Wrong or missing intermediate certificates.

  • A wrong order of entries in the PEM file (for example, private key goes before the certificate).

  • Extra line breaks between the lines, or spaces at the end of the lines.

Double-check your PEM file and make sure it is formatted exactly as explained in the requirements above.

Disable HTTPS

If you need to disable HTTPS and remove the SSL certificate from SwaggerHub, follow these steps:

  1. Open the Admin Center.

  2. Select Settings on the left.

  3. Change SSL Termination settings to No SSL.

  4. Scroll down to the bottom and click Save Changes.

  5. Delete the SSL Certificate and SSL Certificate Trust Chain you previously uploaded to SwaggerHub.

    Note

    The Delete button is disabled if the SSL Termination settings value has not been changed to No SSL.

    Deleting an SSL certificate

  6. Click Save Changes again.

  7. Select System on the left and click Restart SwaggerHub. Wait a few minutes for the system to restart completely.

Now, you can access your SwaggerHub On-Premise instance via HTTP only.

What’s next

After you enable HTTPS, consider updating the inbound links to your SwaggerHub instance to use HTTPS:

  • Domain references in existing API definitions.

  • The SwaggerHub callback URL used on GitHub (see GitHub Integration).

  • SwaggerHub URLs in your SAML identity provider used for single sign-on.

  • Calls to the SwaggerHub Registry API and to your API mocks.

See Also

In this section:
© 2024
Publication date: