# Single Sign-On

> Source: https://docs.synthesized.io/tdk/latest/user_guide/060_security_compliance/authentication/sso
> For the complete documentation index, see [llms.txt](https://docs.synthesized.io/llms.txt).

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](https://docs.spring.io/spring-boot/docs/current-SNAPSHOT/reference/htmlsingle/#web.security.oauth2) 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](https://docs.synthesized.io/tdk/latest/user_guide/060_security_compliance/authentication/ldap_activedirectory#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:

```properties
governor.security.saml.authorities.enabled=true
```

Then configure how groups are extracted and mapped to roles:

```properties
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)
```

<table><tbody><tr><td><i class="conum" data-value="1"></i><b>1</b></td><td>The SAML assertion attribute containing the list of group names. Default: <code>groups</code>.</td></tr><tr><td><i class="conum" data-value="2"></i><b>2</b></td><td>Convert group names to uppercase before matching. Default: <code>true</code>.</td></tr><tr><td><i class="conum" data-value="3"></i><b>3</b></td><td>The role assigned when no group matches any alias. Default: <code>MEMBER</code>.</td></tr></tbody></table>

#### Role Aliases

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

```properties
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`

> **NOTE**
> When a user belongs to multiple groups that map to different roles, the **highest privilege** role is assigned. Priority order: `OWNER` > `ADMINISTRATOR` > `MEMBER`.

> **NOTE**
> 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.

```properties
governor.security.saml.slo-enabled=true (1)
governor.security.saml.default-registration-id=microsoft (2)
```

<table><tbody><tr><td><i class="conum" data-value="1"></i><b>1</b></td><td>Enable SAML Single Logout. Default: <code>false</code>.</td></tr><tr><td><i class="conum" data-value="2"></i><b>2</b></td><td>The default SAML provider registration ID used for logout. Required when SLO is enabled.</td></tr></tbody></table>