Single Sign-on (SSO)

Squore single sign-on integration is compatible with any identity provider that supports SAML 2.0 framework. Single sign-on properties will be used to configure the connection between Squore and the external identity provider, which information to map and how to connect or disconnect.

You can either use an identity provider metadata file to define your single sign-on properties, or you can define said properties directly in the provider.

It is recommended to store configuration files outside of <SQUORE_HOME> to avoid losing them when upgrading your installation.

Depending on your setup, you might need to configure mappers in your identity provider, to return the required key and value pairs.

When single sign-on (SSO) is enabled, a Switch Account entry is available in the user menu, that will redirect you to the login page. Allowing you to authenticate using an alternative authentication method (if any is configured).

The login page, when accessed directly, also provides a way to authenticate using the single sign-on (SSO) method.

Using an identity provider metadata file

The mandatory properties are the following:

spEntityId, the unique identifier of the service provider. Its value must be the Squore Server URL: http://localhost:8180.
spPublicKey, the path to the service provider public key file.
spPrivateKey, the path to the service provider private key file use to encrypt the data.
idpMetadataFile or idpMetadataUrl, the path or URL to the identity provider metadata file.
userDisplayNameAttribute, the attribute that will be used to specify Squore user display name.
userMailAttribute, the attribute that will be used to specify Squore user mail.
userDepartmentAttribute, the attribute that will be used to specify Squore user department.
userLastNameAttribute (deprecated), the attribute that will be used to construct Squore user display name, together with userFirstNameAttribute. Use userDisplayNameAttribute instead.
userFirstNameAttribute (deprecated), the attribute that will be used to construct Squore user display name, together with userLastNameAttribute. Use userDisplayNameAttribute instead.

The optional properties are the following:

spInitLogout (default: false):
- false, to log the users out of Squore and reconnect them immediately if they are still connected to the identity provider. Logging out of the identity provider automatically invalidates the Squore session.
- true, to log the users out of Squore and redirect them to the identity provider login screen.

Here is an example of a complete single sign-on authentication configuration that uses a URL to retrieve the identity provider metadata file:

<subsystem xmlns="urn:com:vector:squore:1.0" >
	<security>
		<authentication name="default">
			<auth-module name="mySingleSignOn" provider="samlAuth" flag="sufficient"/>
		</authentication>
		<providers>
			<provider name="samlAuth" type="saml">
				<property name="spEntityId" value="http://localhost:8180" />
				<property name="spPublicKey" value="/path/to/sp-public-key.crt"/>
				<property name="spPrivateKey" value="/path/to/sp-private-key.pk8"/>
				<property name="idpMetadataUrl" value="https://<domain>:<port>/url/to/file/idp-metadata.xml"/>
				<property name="userDisplayNameAttribute" value="username"/>
				<property name="userMailAttribute" value="mail"/>
				<property name="userDepartmentAttribute" value="organization"/>
			</provider>
		</providers>
	</security>
</subsystem>

Defining properties directly

The mandatory properties are the following:

spEntityId, the unique identifier of the service provider. Its value must be the Squore Server URL: http://localhost:8180.
spPublicKey, the path to the service provider public key file.
spPrivateKey, the path to the service provider private key file use to encrypt the data.
userDisplayNameAttribute, the attribute that will be used to specify Squore user display name.
userMailAttribute, the attribute that will be used to specify Squore user mail.
userDepartmentAttribute, the attribute that will be used to specify Squore user department.
userLastNameAttribute (deprecated), the attribute that will be used to construct Squore user display name, together with userFirstNameAttribute. Use userDisplayNameAttribute instead.
userFirstNameAttribute (deprecated), the attribute that will be used to construct Squore user display name, together with userLastNameAttribute. Use userDisplayNameAttribute instead.
idpEntityId, the unique identifier of the identity provider. Its value must be the identity provider URL: http://<domain>:<port>;.
idpSsoUrl, the single sign on URL of the identity provider.
idpSloUrl, the single sign-off URL of the identity provider.
idpX509Cert, the certificate of the identity provider used to verify the authenticity of the SAML response.
idpSloBinding, the type of the single sign-off request (POST or GET). For example:
- urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect
idpSsoBinding, the type of the single sign on request (POST or GET). For example:
- urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST

The optional properties are the following:

idpCertFingerprint, the identity provider certificate fingerprint. In replacement of idpX509Cert properties to reduce the size of the exchanged messages. To generate a certificate fingerprint:
- openssl x509 -noout -fingerprint -in identity-provider-certificate.crt
idpCertAlgorithm (default: sha1), the algorithm used to generate the identity provider certificate fingerprint. Only necessary when idpCertFingerprint is present. Accepted values are:
- sha1
- sha256
- sha384
- sha512
spXmlValidation (default: true), to validate all the XML content received by the service provider.
spAuthnRequestSigned (default: true), to indicate that the messages sent by the service provider are signed.
spNamedIdEncryted (default: false), to indicate that the nameID of the logout request sent by the service provider are encrypted.
spLogoutRequestSigned (default: true), to indicate whether the <samlp:logoutRequest> messages sent by the service provider are signed.
spLogoutResponseSigned (default: false), to indicate whether the <samlp:logoutResponse> messages sent by the service provider are signed.
spMessagesSigned (default: false), to indicate whether the <samlp:Response>, <samlp:LogoutRequest> and <samlp:LogoutResponse> messages received by the service provider are signed.
spAssertionsSigned (default: false), to indicate whether the <saml:Assertion> messages received by the service provider are signed.
spAssertionsEncrypted (default: false), to indicate whether the <saml:Assertion> messages received by the service provider are encrypted.
spSlsBinding (default: urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST), to specify the single logout (SLO) HTTP request type, either POST or GET.
spAcsBinding (default: urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST), to specify the assertion consumer service (ACS) HTTP request type, either POST or GET.
spNameFormatId (default: urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified), to specify the name identifier (nameId) format used by the service provider for handling the subject.
spInitLogout (default: false):
- false, to log the users out of Squore and reconnect them immediately if they are still connected to the identity provider. Logging out of the identity provider automatically invalidates the Squore session.
- true, to log the users out of Squore and redirect them to the identity provider login screen.

Here is an example of a complete single sign-on authentication configuration with properties defined directly in the provider:

<subsystem xmlns="urn:com:vector:squore:1.0" >
	<security>
		<authentication name="default">
			<auth-module name="mySingleSignOn" provider="samlAuth" flag="sufficient"/>
		</authentication>
		<providers>
			<provider name="samlAuth" type="saml">
				<property name="spEntityId" value="http://localhost:8180" />
				<property name="spPublicKey" value="/path/to/sp-public-key.crt"/>
				<property name="spPrivateKey" value="/path/to/sp-private-key.pk8"/>
				<property name="userDisplayNameAttribute" value="username"/>
				<property name="userMailAttribute" value="mail"/>
				<property name="userDepartmentAttribute" value="organization"/>
                <property name="idpEntityId" value="http://<domain>:<port>"/>
                <property name="idpSsoUrl" value="http://<domain>:<port>/auth/realms/<idp-realm>/protocol/saml"/>
                <property name="idpSloUrl" value="http://<domain>:<port>/auth/realms/<idp-realm>/protocol/saml"/>
                <property name="idpX509Cert" alue="MIICqTCCAZECBgF8d..."/>
                <property name="idpSloBinding" value="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"/>
                <property name="idpSsoBinding" value="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"/>
			</provider>
		</providers>
	</security>
</subsystem>