Single Sign-On

Governor supports Single Sign-On using OAuth2 or SAML.

Setting up OAuth2

OAuth2 is supported with the following clients:

  • Google

  • Microsoft

  • GitHub

For setting up OAuth2 single sign-on, provide the necessary application properties for the respective clients. See Spring Boot reference for the documentation. Governor supports GitHub, Google and Microsoft via the following set of properties:

spring.security.oauth2.client.registration.github.clientid
spring.security.oauth2.client.registration.github.clientsecret
spring.security.oauth2.client.registration.github.redirecturi
spring.security.oauth2.client.registration.google.clientid
spring.security.oauth2.client.registration.google.clientsecret
spring.security.oauth2.client.registration.microsoft.clientid
spring.security.oauth2.client.registration.microsoft.clientsecret

Setting up clientid property for any of this will enable the respective icon on the authentication form.

Setting up SAML

SAML is supported with the following providers:

  • Google

  • Microsoft Entra ID

Configure your SAML identity provider using the following URLs:

  • Identifier (Entity ID): https://[host]/api/v1/saml2/service-provider-metadata/microsoft

  • Reply URL (Assertion Consumer Service URL): https://[host]/api/v1/saml2/login/sso/microsoft

In order to set up SAML for, you have to provide a reference to metadata file in the following application property:

Google

spring.security.saml2.relyingparty.registration.google.entity-id={baseUrl}/api/v1/saml2/service-provider-metadata/{registrationId}
spring.security.saml2.relyingparty.registration.google.acs.location={baseUrl}/api/v1/saml2/login/sso/{registrationId}
spring.security.saml2.relyingparty.registration.google.assertingparty.metadata-uri=file:/IDP_metadata.xml

Microsoft Entra ID

spring.security.saml2.relyingparty.registration.microsoft.entity-id={baseUrl}/api/v1/saml2/service-provider-metadata/{registrationId}
spring.security.saml2.relyingparty.registration.microsoft.acs.location={baseUrl}/api/v1/saml2/login/sso/{registrationId}
spring.security.saml2.relyingparty.registration.microsoft.assertingparty.metadata-uri=file:/IDP_metadata.xml

The IDP_metadata.xml is provided when you set up a SAML application for your Google or Azure cloud domain.

SAML Group-to-Role Mapping

Governor can automatically assign roles to SAML users based on their group memberships in the Identity Provider. This works similarly to LDAP Authorities.

In-house Authority Policy (Default)

By default, role management is controlled at the Governor side. The first SAML user that signs in is granted the OWNER role, and subsequent users are granted the role configured in GOVERNOR_SECURITY_DEFAULTROLE (default: MEMBER).

IdP Authority Policy

To activate automatic role assignment from SAML groups, enable the authorities feature:

governor.security.saml.authorities.enabled=true

Then configure how groups are extracted and mapped to roles:

governor.security.saml.authorities.group-attribute=groups (1)
governor.security.saml.authorities.convert-to-uppercase=true (2)
governor.security.saml.authorities.default-role=MEMBER (3)
1 The SAML assertion attribute containing the list of group names. Default: groups.
2 Convert group names to uppercase before matching. Default: true.
3 The role assigned when no group matches any alias. Default: MEMBER.

Role Aliases

Map your IdP group names to Governor roles using role aliases:

governor.security.saml.authorities.role-aliases.tdk-admins=ADMINISTRATOR
governor.security.saml.authorities.role-aliases.tdk-owners=OWNER
governor.security.saml.authorities.role-aliases.developers=MEMBER

Governor roles are:

  • MEMBER

  • ADMINISTRATOR

  • OWNER

When a user belongs to multiple groups that map to different roles, the highest privilege role is assigned. Priority order: OWNER > ADMINISTRATOR > MEMBER.
When SAML authorities are enabled, user roles are updated on each login based on current IdP group membership. Role management in the Governor UI becomes read-only.

SAML Logout

Governor supports two logout modes for SAML users.

Local Logout (Default)

By default, logging out clears the Governor session and redirects the user to the login page. The user remains signed in to the Identity Provider.

Single Logout (SLO)

When Single Logout is enabled, Governor sends a SAML LogoutRequest to the Identity Provider, signing the user out of both Governor and the IdP.

governor.security.saml.slo-enabled=true (1)
governor.security.saml.default-registration-id=microsoft (2)
1 Enable SAML Single Logout. Default: false.
2 The default SAML provider registration ID used for logout. Required when SLO is enabled.