Skip to main content

Google Workspace SSO with ZITADEL

This guide shows how to enable login with ZITADEL on Google Workspace.

You can configure two types of SAML SSO on Google Workspace:

Both profiles need to be configured differently. Please make sure to configure your application for the correct type. Please refer to Google Help to Set up SSO for your organization in case you need additional information on the Workspace setup.

OpenID Connect

At this time Google supports SSO with OpenID Connect only for few providers.

Prerequisites:

SSO profile for your organization​

Configure SSO profile on Google Workspace​

Open the Google settings for SSO with third-party IdP and click on ADD SSO PROFILE.

SSO with third-party IdP

Download the public certificate from your ZITADEL instance by requesting $YOUR_DOMAIN/saml/v2/certificate

 wget $YOUR_DOMAIN/saml/v2/certificate -O idp.crt

Always replace $YOUR_DOMAIN with your instance domain.

Use the following configuration

SettingValue
Set up SSO with third-party identity providerEnable (check)
Sign-in page URL$YOUR_DOMAIN/saml/v2/SSO
Sign-out page URL$YOUR_DOMAIN/saml/v2/SLO
Verification CertificateUpload the certificate (idp.crt)
Use a domain-specific issuerEnable (check)
Network masksLeave blank
Change password URL$YOUR_DOMAIN/ui/console/users/me?id=security

Create a SAML application in ZITADEL​

Create a new .xml file with the following minimal SAML metadata contents:

<?xml version="1.0"?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="${ENTITYID}">
<md:SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol urn:oasis:names:tc:SAML:1.1:protocol">
<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="${ACSURL}" index="0"/>
</md:SPSSODescriptor>
</md:EntityDescriptor>

Set or replace the variables with the values from the next screen as follows:

<your_domain> is the domain you have verified in Google Workspace.

In your existing project:

Press the "+"-button to add an application Project

Fill in a name for the application and chose the SAML type, then click "Continue". New Application

Either fill in the URL where ZITADEL can read the metadata from, or upload the metadata XML directly, then click "Continue". Add Metadata to Application

Check your application, if everything is correct, press "Create". Create Application

Activate the SSO profile for your organization​

Make sure to enable the SSO profile for your organization.

In the domain-specific service URLs settings select "Automatically redirect users to the third-party IdP in the following SSO profile" and select as SSO profile "SSO profile for your organization".

domain-specific service URLs

Save the settings.

SSO with third-party IdP lower part

Verify the SSO profile for your organization​

Now you should be all set to verify your setup:

  • Open Gmail in an incognito session with the following link: https://mail.google.com/a/<your_domain>
  • Enter your username and credentials
  • You should be redirected to Gmail and logged in

<your_domain> is the domain you have verified in Google Workspace.

Third-party SSO SAML profile​

Configure a third party SSO SAML profile and login users with ZITADEL to Google Workspace.

Add SAML profile on Google Workspace​

Open the Google settings for SSO with third-party IdP and click on ADD SAML PROFILE.

SSO with third-party IdP

Download the public certificate from your ZITADEL instance by requesting $YOUR_DOMAIN/saml/v2/certificate

 wget $YOUR_DOMAIN/saml/v2/certificate -O idp.crt

Always replace $YOUR_DOMAIN with your instance domain.

Use the following configuration

SettingValue
SSO profile nameZITADEL SSO
IDP entity ID$YOUR_DOMAIN/saml/v2/metadata
Sign-in page URL$YOUR_DOMAIN/saml/v2/SSO
Sign-out page URL$YOUR_DOMAIN/saml/v2/SLO
Change password URL$YOUR_DOMAIN/ui/console/users/me?id=security
Verification CertificateUpload the certificate (idp.crt)

Now go ahead and click SAVE

Entity ID and ACS URL​

Open the Google settings for SSO with third-party IdP and click on the SAML Profile ZITADEL SSO

SSO Profile Overview

You can copy the "Entity ID" and "ACS URL" from the "SP details" section.

ZITADEL SSO Profile

Create a SAML application in ZITADEL​

Create a new .xml file with the following minimal SAML metadata contents:

<?xml version="1.0"?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="${ENTITYID}">
<md:SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol urn:oasis:names:tc:SAML:1.1:protocol">
<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="${ACSURL}" index="0"/>
</md:SPSSODescriptor>
</md:EntityDescriptor>

Set or replace the variables with the values from the next screen as follows:

Replace <your_value> with the values from the SSO profile.

In your existing project:

Press the "+"-button to add an application Project

Fill in a name for the application and chose the SAML type, then click "Continue". New Application

Either fill in the URL where ZITADEL can read the metadata from, or upload the metadata XML directly, then click "Continue". Add Metadata to Application

Check your application, if everything is correct, press "Create". Create Application

Activate the SSO profile​

Make sure to enable the SSO profile.

In the domain-specific service URLs settings select "Automatically redirect users to the third-party IdP in the following SSO profile" and select as SSO profile "ZITADEL SSO".

domain-specific service URLs with ZITADEL SSO

Save the settings.

SSO with third-party IdP lower part with ZITADEL SSO

Verify the SAML SSO profile​

Now you should be all set to verify your setup:

  • Open Gmail in an incognito session with the following link: https://mail.google.com/a/<your_domain>
  • Enter your username and credentials
  • You should be redirected to Gmail and logged in

<your_domain> is the domain you have verified in Google Workspace.

Troubleshooting​

Make sure you don't use a super admin account in Google Workspace to test SSO. Super Admin users are not allowed to login with SSO and you might receive an status code 500.