SSO with Cover Reports

NGINX can be used to secure access to your Cover Reports server using SSO. NGINX provide various setup guides for different SSO providers - see Set Up Single Sign-On for Proxied Applications on the official docs site.

Prerequisites

• A server running Cover Reports.

• A server running NGINX Plus (this can be the same server as Cover Reports) with a valid subscription.

• An SSO provider.

Auth0 considerations

Note the following when setting up NGINX with Auth0. For details of the full process, see Single Sign-On With Auth0 on the NGINX docs site.

• On your NGINX Auth0 Dashboard, set the callback URL to http://<YOUR-NGINX-SERVER-IP>:80/_codexch (replace <YOUR-NGINX-SERVER-IP> with the IP address of your NGINX instance).

• On your NGINX server, update the upstream details for Cover Reports in the frontend.conf file (replace <YOUR-COVER-REPORTS-SERVER-IP> with the IP address of your Cover Reports instance):

upstream cover-reports {
    zone cover-reports 64k;
    server <YOUR-COVER-REPORTS-SERVER-IP>:8080;
}

• Also in the frontend.conf file, make sure that the NGINX server is listening on port 80 and that your proxy_pass destination matches the upstream value configured above (cover-reports):

listen 80;
...
proxy_pass http://cover-reports;

• Once SSO has been configured for Cover Reports, port 8080 will still be open, bypassing SSO. To prevent this you will need to close port 8080 which can be done as part of your network configuration. However, blocking port 8080 entirely will prevent reports bundles being uploaded using Cover Pipeline and Cover CLI. We recommend that you add the IP range of your CI runners and Cover CLI users to your network allow-list for port 8080.

Okta considerations

Note the following when setting up NGINX with Okta. For details of the full process, see Single Sign-On With Okta on the NGINX docs site.

• On your Okta Application's general settings, set the "Sign-in redirect URI" to http://<YOUR-NGINX-SERVER-IP>:80/_codexch (replace <YOUR-NGINX-SERVER-IP> with the IP address of your NGINX instance).

• On your NGINX server, update the upstream details for Cover Reports in the frontend.conf file (replace <YOUR-COVER-REPORTS-SERVER-IP> with the IP address of your Cover Reports instance):

upstream cover-reports {
    zone cover-reports 64k;
    server <YOUR-COVER-REPORTS-SERVER-IP>:8080;
}

• Also in the frontend.conf file, make sure that the NGINX server is listening on port 80 and that your proxy_pass destination matches the upstream value configured above (cover-reports):

listen 80;
...
proxy_pass http://cover-reports;

• Make sure to include your in your Client ID and Client secret in your openid_connect_configuration.conf on your NGINX server. Set the oidc_client to your Client ID and oidc_client_secret to your Client secret.

map $host $oidc_client {
    default "<YOUR-CLIENT-ID>";
}

...

map $host $oidc_client_secret {
    default "<YOUR-CLIENT-SECRET>";
}

• Once SSO has been configured for Cover Reports, port 8080 will still be open, bypassing SSO. To prevent this you will need to close port 8080 which can be done as part of your network configuration. However, blocking port 8080 entirely will prevent reports bundles being uploaded using Cover Pipeline and Cover CLI. We recommend that you add the IP range of your CI runners and Cover CLI users to your network allow-list for port 8080.

Amazon Cognito considerations

Note the following when setting up NGINX with Amazon Cognito. For details of the full process, see Single Sign-On With Amazon Cognito on the NGINX docs site. At the time of writing the official docs do not reflect the updated web UI for Amazon Cognito, however equivalent fields can still be found for all required configurations.

• Amazon Cognito will require you to use HTTPS - a self-signed or CA certificate will be required. On your NGINX server, update the following in the frontend.conf file:

  - SSL listening port.

  - IP address of your Cover Reports instance.

  - SSL certificate details.

    listen 443 ssl;

    server_name <YOUR-COVER-REPORTS-SERVER-IP>;

    ssl_certificate /etc/ssl/certs/nginx-selfsigned.crt;
    ssl_certificate_key /etc/ssl/private/nginx-selfsigned.key;
    ssl_dhparam /etc/ssl/certs/dhparam.pem;

• On your NGINX server, update the upstream details for Cover Reports in the frontend.conf file (replace <YOUR-COVER-REPORTS-SERVER-IP> with the IP address of your Cover Reports instance):

upstream cover-reports {
    zone cover-reports 64k;
    server <YOUR-COVER-REPORTS-SERVER-IP>:8080;
}

• On your Amazon Cognito Dashboard, set the callback URL to https://<YOUR-NGINX-SERVER-IP>:443/_codexch (replace <YOUR-NGINX-SERVER-IP> with the IP address of your NGINX instance).

• Once SSO has been configured for Cover Reports, port 8080 will still be open, bypassing SSO. To prevent this you will need to close port 8080 which can be done as part of your network configuration. However, blocking port 8080 entirely will prevent reports bundles being uploaded using Cover Pipeline and Cover CLI. We recommend that you add the IP range of your CI runners and Cover CLI users to your network allow-list for port 8080.