Skip to content

OpenId Connect plugin configuration

OpenID Connect plugin adds a new authentification 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 authenticifaction entrypoint by default in Squash. As such, users can keep on authentificate themselves throught 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 is already exist, simply add the 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 'plungins" 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 namming pattern:

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

The name of the IdP is to freely be entered, 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 IdP chosen, all configuration properties will not be required. Particularly 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 diferenciate the diferent 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 a 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

Attention

The oidc.access.whitelist property cannot be used with a IdP which doesn't 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 gets authorizations associated with this account back.
    • 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.