Install an SSL Certificate to SwaggerHub On-Premise

Note: This guide explains SSL certificate setup for SwaggerHub On-Premise v. 1.19.2 and later. If you use an earlier 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.

  • 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:

    • the certificate itself,

    • any required intermediate certificates (without the root certificate),

    • the private key (either included in the certificate file or provided in a separate field during certificate uploading).

    The order of certificates in the PEM file must be such that each one certifies the one before it. If the private key is included in the certificate file, it must be at the end of the file.

    PEM file example:

    -----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 (optional)
-----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. These requirements apply to both CA-signed and self-signed certificates.

Considerations for self-signed certificates

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

Step 1. Upload certificate to Certificate Manager

Start by uploading your SSL certificate and private key to the Certificate Manager:

  1. Open the Admin Center.

  2. Select Certificate Manager on the left.

  3. Click Import Certificate.

  4. Browse for the Certificate File (PEM file, see above).

  5. If the specified PEM file includes the private key, skip to the next step.

    If the specified PEM file contains only the certificate, but not the private key, paste the key into the Private Key field. Paste the key value exactly as it was generated, including the BEGIN PRIVATE KEY and END PRIVATE KEY lines.

  6. Specify a Friendly Name and an optional Description for this certificate.

  7. Click Import.

  8. If your certificate is self-signed or issued by a private CA, also import the CA bundle file (see above for the file format).

Note

If you get an error during the import, refer to the Troubleshooting tips below.

Step 2. Apply SSL certificate

  1. In the Admin Center, select Settings on the left.

  2. 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/

  3. In the Privacy section:

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

    • Select the uploaded certificate from the SSL Certificate list.

      Applying SSL certificate on the Settings page in Admin Center

    • If your SSL certificate is self-signed or issued by a private CA, select the uploaded CA bundle from the SSL Certificate Trust Chain list.

  4. Click Save Changes and Restart. Wait a few minutes for the system to restart completely.

Step 3. 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

There are several ways to view the certificate information (such as the validity period, issuer, and other details):

  • In the Certificate Manager, expand the row that corresponds to the certificate.

  • In your web browser:

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

  • Using OpenSSL tools:

    openssl s_client -connect Your.SwaggerHub.Domain:443

Replace SSL certificate

If you need to replace an SSL certificate, for example, if it is about to expire, do the following:

  1. Upload the new certificate with a private key to the Certificate Manager.

  2. On the Settings page, select the new certificate from the SSL Certificate list.

  3. Click Save Changes.

  4. On the System tab, click Restart SwaggerHub. Wait a few minutes for the system to restart completely.

  5. In the Certificate Manager, delete the old certificate.

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. (This applies to SwaggerHub On-Premise 1.19.1 and earlier versions.)

  • 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. Click X in the SSL Certificate and SSL Certificate Trust Chain fields to clear the selection.

  5. Click Save Changes.

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

  7. (Optional.) Switch to the Certificate Manager and delete the SSL certificates previously used.

Now, your SwaggerHub On-Premise instance can be accessed 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: