# SSO with Cover Reports

SSO authentication is only provided by using the [OAUTH2](https://en.wikipedia.org/wiki/OAuth) and [OIDC](https://openid.net/developers/how-connect-works/) protocols and connecting to an external SSO provider.

Currently, the supported providers are:

* [PingIdentity](https://www.pingidentity.com/)
* [Keycloak](https://www.keycloak.org/)

Other providers that use the same protocols are likely to work with similar configuration, but have not been tested by Diffblue.

{% hint style="info" %}
SSO access control is only provided for the UI and any REST endpoints used by the UI. Access to other REST endpoints, e.g. for upload, is controlled using the internal JWT mechanism.
{% endhint %}

## Prerequisites

* A server running Cover Reports.
* An SSO provider.

## Authorization Code Grant Type <a href="#authorization-code-grant-type" id="authorization-code-grant-type"></a>

Cover Reports uses the [authorization code grant type](https://oauth.net/2/grant-types/authorization-code/) flow.

When a user navigates to the Reports UI, they are redirected to the SSO provider which presents a login screen. The user enters their credentials and will be authenticated by the SSO provider. If successful, the user will be redirected back to the Reports home page.

## Integrating with an SSO Provider <a href="#integrating-with-an-sso-provider" id="integrating-with-an-sso-provider"></a>

To integrate Cover Reports with an SSO provider:

* The SSO provider must be configured with details of Cover Reports
* Cover Reports must be configured with details of the SSO provider

### Configuring the SSO Provider <a href="#configuring-the-sso-provider" id="configuring-the-sso-provider"></a>

Since the [authorization code grant type](https://oauth.net/2/grant-types/authorization-code/) flow is a standard mechanism, it should be possible to configure any SSO provider in this way. However, each provider has a very different configuration; it is not within the scope of this document to describe it.

However, it should be sufficient to note that the following properties must be set:

* A new client must be created that has the ID: `diffblue-cover-reports`. This can be changed if necessary by specifying a property in the [Cover Reports configuration](#configuring-cover-reports)
* A client secret must be used to authenticate Cover Reports to this new client
* The authorization code grant type must be used
* The scope must be `openid`
* A redirect URL must be set that matches the Cover Reports installation, e.g. [http://www.example.com:8080/login/oauth2/code/ping](http://localhost:8080/login/oauth2/code/ping)
* All users must have a Cover Reports role associated to them for [#authorisation](#authorisation "mention")

### Configuring Cover Reports <a href="#configuring-cover-reports" id="configuring-cover-reports"></a>

Once the SSO provider has been configured, there are several properties that must be set in Cover Reports [see how to set properties](https://docs.diffblue.com/features/cover-reports/cover-reports-administrator/configuration-options):

* Add `oauth2` to the active profile list - this enables SSO in Cover Reports
* SSO client ID
* SSO client secret
* Type of authorization grant; must be `authorization_code`
* Scope of user account accessible by Cover Reports; must be `openid`
* URL of Cover Reports where the SSO will redirect the user after successful login
* URL of the SSO provider that Cover Reports will use

The names of most of these properties depend on the SSO provider.

{% hint style="info" %}
When the `oauth2` profile is specified, the [upload](https://cover-docs.diffblue.com/features/cover-reports/configuration-options#enable-upload-authentication) and [API](https://cover-docs.diffblue.com/features/cover-reports/configuration-options#enable-api-authentication) user authentication is enabled and so their credentials must be supplied. This ensures access to Reports is fully controlled. This authentication can be disabled if not required (see [upload](https://cover-docs.diffblue.com/features/cover-reports/configuration-options#disable-upload-authentication) and [API](https://cover-docs.diffblue.com/features/cover-reports/configuration-options#disable-api-authentication) configuration).
{% endhint %}

#### **General Properties**

<table><thead><tr><th width="202">Property</th><th width="273">Description</th><th>Example value</th></tr></thead><tbody><tr><td>spring.profiles.active</td><td>Specifies a comma separated list of profiles</td><td>postgres,oauth2</td></tr></tbody></table>

#### **PingIdentity Specific Properties**

<table><thead><tr><th width="260">Property</th><th width="306">Description</th><th>Example value</th></tr></thead><tbody><tr><td>spring.security.oauth2.client.registration.ping.provider</td><td>Name of spring.security.oauth2.client.provider</td><td>pingprovider</td></tr><tr><td>spring.security.oauth2.client.registration.ping.client-id</td><td>ID of SSO client</td><td>diffblue-cover-reports</td></tr><tr><td>spring.security.oauth2.client.registration.ping.client-secret</td><td>Secret of SSO client</td><td>some-secret-key</td></tr><tr><td>spring.security.oauth2.client.registration.ping.authorization-grant-type</td><td>Type of authorization grant. Must be <code>authorization_code</code></td><td>authorization_code</td></tr><tr><td>spring.security.oauth2.client.registration.ping.scope</td><td>Scope of user account accessible by Cover Reports. Must be <code>openid</code></td><td>openid</td></tr><tr><td>spring.security.oauth2.client.registration.ping.redirect-uri</td><td>URL of Cover Reports where the SSO will redirect the user after successful login</td><td><a href="http://localhost:8080/login/oauth2/code/ping">http://</a><a href="http://localhost:8080/login/oauth2/code/ping">www.example.com</a><a href="http://localhost:8080/login/oauth2/code/ping">:8080/login/oauth2/code/ping</a></td></tr><tr><td>spring.security.oauth2.client.provider.pingprovider.issuer-uri</td><td>URL of the SSO provider that Cover Reports will use</td><td><a href="https://localhost:9031/">https://</a><a href="http://localhost:8080/login/oauth2/code/ping">www.example.com</a><a href="https://localhost:9031/">:9031</a></td></tr></tbody></table>

#### **Keycloak Specific Properties**

<table><thead><tr><th width="264">Property</th><th width="302">Description</th><th>Example value</th></tr></thead><tbody><tr><td>spring.security.oauth2.client.registration.keycloak.provider</td><td>Name of spring.security.oauth2.client.provider</td><td>keycloak-provider</td></tr><tr><td>spring.security.oauth2.client.registration.keycloak.client-id</td><td>ID of SSO client</td><td>diffblue-cover-reports</td></tr><tr><td>spring.security.oauth2.client.registration.keycloak.client-secret</td><td>Secret of SSO client</td><td>some-secret-key</td></tr><tr><td>spring.security.oauth2.client.registration.keycloak.authorization-grant-type</td><td>Type of authorization grant. Must be <code>authorization_code</code></td><td>authorization_code</td></tr><tr><td>spring.security.oauth2.client.registration.keycloak.scope</td><td>Scope of user account accessible by Cover Reports. Must be <code>openid</code></td><td>openid</td></tr><tr><td>spring.security.oauth2.client.registration.keycloak.redirect-uri</td><td>URL of Cover Reports where the SSO will redirect the user after successful login</td><td><a href="http://localhost:8080/login/oauth2/code/keycloak">http://</a><a href="http://localhost:8080/login/oauth2/code/ping">www.example.com</a><a href="http://localhost:8080/login/oauth2/code/keycloak">:8080/login/oauth2/code/keycloak</a></td></tr><tr><td>spring.security.oauth2.client.provider.keycloak-provider.issuer-uri</td><td>URL of the SSO provider that Cover Reports will use</td><td><a href="https://localhost:9031/">https://</a><a href="http://localhost:8080/login/oauth2/code/ping">www.example.com</a><a href="https://localhost:9031/">:9031</a></td></tr></tbody></table>

#### **SSO Profiles**

To simplify this configuration, there are pre-configurations (or profiles) supplied in Cover Reports for the supported SSO providers. These provide default values for the required properties.

The profiles are:

* **ping** - for the PingIdentity provider
* **keycloak** - for the Keycloak provider

{% hint style="info" %}
Only 1 of these profiles can be specified at any one time.
{% endhint %}

To specify the profile, the profile name must be appended to the end of the `spring.profiles.active` property.

For example, to enable SSO with the PingIdentity provider, the properties could be reduced to:

```properties
spring.profiles.active=postgres,oauth2,ping
spring.security.oauth2.client.registration.ping.client-secret=some-secret-key
```

## Authorization <a href="#authorisation" id="authorisation"></a>

Authorization is managed by adding roles to users. This must be done within the SSO provider. The roles of each user must be set in the claims of the user details. Cover Reports will retrieve the user details from the SSO provider after a successful login and extract the roles from the claims.

The default name of the claim is `cover-reports-roles` which should contain a list of all the roles the user has.

This name can be customised by setting the `reports.roles.claimNameWithRoles` property, but it must align with that set in the SSO provider.

The roles in Cover Reports are:

| Role  | Description       | Permissions                                                                                       |
| ----- | ----------------- | ------------------------------------------------------------------------------------------------- |
| USER  | a standard user   | view all information                                                                              |
| ADMIN | a privileged user | view all information; Delete runs; Access the administration page to perform administrative tasks |

The names of these roles can be customised by setting the `reports.roles.userName` and `reports.roles.adminName` properties respectively.

#### Available Properties <a href="#available-properties" id="available-properties"></a>

| Property                         | Description                                                | Default value       |
| -------------------------------- | ---------------------------------------------------------- | ------------------- |
| reports.roles.claimNameWithRoles | Name of the claim in user details that has a list of roles | cover-reports-roles |
| reports.roles.userName           | Name of the standard user role                             | USER                |
| reports.roles.adminName          | Name of the administrator role                             | ADMIN               |

## Logout <a href="#logout" id="logout"></a>

Currently, there is no logout function in Cover Reports. This reflects the notion that a user with SSO would not want to logout of SSO from Cover Reports.

### Cover Reports User Sessions

Cover Reports creates its own user session once a user has authenticated with the SSO provider. The session will remain active while the user interacts with the Cover Reports UI and is ended by inactivity. Note that the SSO provider cannot invalidate an active Cover Reports session.

## Uploading to Cover Reports <a href="#uploading-to-cover-reports" id="uploading-to-cover-reports"></a>

Uploading information to Cover Reports works in the same way regardless of whether SSO is enabled or not.

User authentication is performed by configuring Diffblue Cover CLI and Cover Reports as [documented](https://docs.diffblue.com/features/cover-reports/cover-reports-administrator/configuration-options#upload-authentication).