Skip to content

OpenId Connect plugin configuration

OpenID Connect plugin adds a new authentication entrypoint to Squash. Squash behaves as a Service Provider only. The Identity Provider is an external tool such as: Google, GitLab, Microsoft or Okta.

OpenID Connect relies on the OAuth 2.0 protocol associated with a JSON Web Token (JWT).

This plugin does not replace the login form which remains the authentication entrypoint by default in Squash. As such, users can keep on authenticate themselves through the Login and Password fields.

OpenID Connect

Quick plugin configuration

Prerequisite

OpenId Connect plugin requires:

  • Squash version 6.0 at least;
  • a valid PREMIUM or ULTIMATE license;
  • to have downloaded the security.openid.connect-X.Y.Z.RELEASE plugin.

This documentation gives some examples with Google, GitLab, and Okta IdPs, but other applications can be used as identity Provider: Microsoft Azure, Keycloak, GitHub…

Creating or registering of the application in the IdP.

It is required before starting any configuration attempt in Squash to create the app in the IdP. Here are the links to the documentation pages describing the steps to follow for Google, GitLab and Okta:

Configuration in Squash

  1. Activate the plugin by adding the following property in the squash.tm.cfg.properties file which is located in the conf folder of Squash. If it already exists, simply add the openid-connect profile to the already existing profiles, separated by a comma. 

    spring.profiles.include=openid-connect

  2. Place the security.openid.connect-X.Y.Z.RELEASE.jar plugin in the plugins folder of Squash;

  3. Add and modify the squash.tm.cfg-openid-connect.properties configuration file of the plugin in the conf folder of Squash. The desired configurations are carried by that file.

Fill in the properties file

OAuth2 properties

OAuth2 properties regarding the set up of an IdP follow this naming pattern: 

spring.security.oauth2.client.[provider_or_registration].[idp_name].[property]

The name of the IdP can be defined freely, this value is displayed on the connection button on the standard Squash connection page. Spaces must be replaced with _.

There are two types of properties of the configuration of an IdP: properties with so-called “provider” information and those with so-called “client” information.

  • "provider" properties: those properties start with spring.security.oauth2.client.provider;
  • "client" properties: those properties start with spring.security.oauth2.client.registration.

Those properties match the informations provided by the IdP following the registration of the application.

Depending on the chosen IdP, all configuration properties will not be required. In particular for Google, Okta, GitHub, and Facebook IdPs, they can be omitted.

To avoid configuration mistakes, it is recommended to inquire about the minimal configuration required for the selected IdP or to fill in all properties. For more information regarding the available properties, refer to the documentation available directly in the properties file squash.tm.cfg-openid-connect.properties embedded in the plugin.

Add properties with informations from "the provider"

Some examples:

  • Google

    Google does not require any of those properties to be filled.

    Info

    Google provider's infos are directly embedded into the plugin, therefore it is not necessary to add them.

  • GitLab

    spring.security.oauth2.client.provider.gitlab.authorization-uri=https://gitlab.com/oauth/authorize
spring.security.oauth2.client.provider.gitlab.token-uri=https://gitlab.com/oauth/token
spring.security.oauth2.client.provider.gitlab.user-info-uri=https://gitlab.com/oauth/userinfo
spring.security.oauth2.client.provider.gitlab.jwk-set-uri=https://gitlab.com/oauth/discovery/keys
spring.security.oauth2.client.provider.gitlab.issuer-uri=https://gitlab.com

  • Okta

    spring.security.oauth2.client.provider.okta.authorization-uri=
spring.security.oauth2.client.provider.okta.token-uri=https://{yourOktaDomain}/oauth2/default/v1/token
spring.security.oauth2.client.provider.okta.user-info-uri=
spring.security.oauth2.client.provider.okta.jwk-set-uri=
spring.security.oauth2.client.provider.okta.issuer-uri=

Add properties with informations from "the client"

Some examples:

  • Google

    spring.security.oauth2.client.registration.google.client-id= {client id}
spring.security.oauth2.client.registration.google.client-secret= {client secret}
spring.security.oauth2.client.registration.google.scope= {scope}
spring.security.oauth2.client.registration.google.redirect-uri= {redirect uri}
spring.security.oauth2.client.registration.google.client-name= {IdP name} {optional}
spring.security.oauth2.client.registration.google.authorization-grant-type=authorization_code{optional}

  • GitLab

    spring.security.oauth2.client.registration.gitlab.client-id= {application id}
spring.security.oauth2.client.registration.gitlab.client-secret= {secret}
spring.security.oauth2.client.registration.gitlab.authorization-grant-type=authorization_code
spring.security.oauth2.client.registration.gitlab.redirect-uri= {redirect uri}
spring.security.oauth2.client.registration.gitlab.scope= {scope}
spring.security.oauth2.client.registration.gitlab.client-name= {IdP name}

  • Okta

    spring.security.oauth2.client.registration.okta.client-id= {client id}
spring.security.oauth2.client.registration.okta.client-secret= {client secret}
spring.security.oauth2.client.registration.okta.authorization-grant-type=client_credentials
spring.security.oauth2.client.registration.okta.scope= {scope}

Everything related to spring.security.oauth2.client.provider.XXX.YYY is located in each IdP's OpenId Connect .well-known file

Everything related tospring.security.oauth2.client.registration.XXX.YYY is specific to the Squash application provided in the IdP

  • XXX is to be defined by yourself to differentiate the different IdPs;
  • YYY are the minimum parameters to be able to connect Squash to the OpenId Connect IdP.

Recommanded properties

user-name-attribute

Adding the user-name-attribute property enables to determine which value is used as login for a user in Squash.

Beware, this value must be unique. If an already existing user has an identical login to the value send by the IdP, it will log onto the already existing user. If that value does not match any login, a new user is created.

Recommanded configuration of this property: 

spring.security.oauth2.client.provider.[idp_name].user-name-attribute=mail

oidc.access.whitelist

Some IdPs do not provide the possibility to filter users allowed to access the application. This property enables to define a white list of domain names or user's email allowed to connect to Squash.

The elements from the list must be separated by commas and must not contain any spaces: 

oidc.access.whitelist=@domain_name.com,@domain_name.fr

Warning

The oidc.access.whitelist property cannot be used with an IdP which does not know or provide the user's email, as it is the case with Microsoft Azure.

Connection's operating

Users can both log in through the IdP as well as the by default login form.

For users to be able to log in to Squash with OpenId Connect, they must be present in the IdP and be authorized to log in. Only users from domain authorized by the application and by the white list defined in Squash can log in with this IdP:

  • If the user is not authorized to log in by the application, an error message from the IdP is displayed;
  • If the user is authorized to log in by the application but is not by the white list configured in Squash, an error message is displayed directly in Squash;
  • If the user is authorized to log in by both the application and the white list, the user can log in:
    • The user already has an account in Squash with an identical login: when connecting, he/she gets authorizations associated with this account;
    • The user does not have an user account in Squash: during the first connection, an user account is automatically generated in Squash but no authorization is granted;
      Subsequently, authorizations must be granted by an administrator in Squash.