SSO with Cover Reports

SSO authentication is only provided by using the OAUTH2 and OIDC protocols and connecting to an external SSO provider.

Currently, the supported providers are:

• PingIdentity

• Keycloak

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

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.

Prerequisites

• A server running Cover Reports.

• An SSO provider.

Authorization Code Grant Type

Cover Reports uses the authorization code grant type 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

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

Since the authorization code grant type 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

• 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

• All users must have a Cover Reports role associated to them for Authorization

Configuring Cover Reports

Once the SSO provider has been configured, there are several properties that must be set in Cover Reports see how to set properties:

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

General Properties

Property	Description	Example value
spring.profiles.active	Specifies a comma separated list of profiles	postgres,oauth2

PingIdentity Specific Properties

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

Keycloak Specific Properties

Property	Description	Example value
spring.security.oauth2.client.registration.keycloak.provider	Name of spring.security.oauth2.client.provider	keycloak-provider
spring.security.oauth2.client.registration.keycloak.client-id	ID of SSO client	diffblue-cover-reports
spring.security.oauth2.client.registration.keycloak.client-secret	Secret of SSO client	some-secret-key
spring.security.oauth2.client.registration.keycloak.authorization-grant-type	Type of authorization grant. Must be authorization_code	authorization_code
spring.security.oauth2.client.registration.keycloak.scope	Scope of user account accessible by Cover Reports. Must be openid	openid
spring.security.oauth2.client.registration.keycloak.redirect-uri	URL of Cover Reports where the SSO will redirect the user after successful login	http://www.example.com:8080/login/oauth2/code/keycloak
spring.security.oauth2.client.provider.keycloak-provider.issuer-uri	URL of the SSO provider that Cover Reports will use	https://www.example.com:9031

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

Only 1 of these profiles can be specified at any one time.

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:

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

Authorization

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

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

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

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.