diff --git a/docs/docs/guides/integrate/services/google-workspace.md b/docs/docs/guides/integrate/services/google-workspace.md new file mode 100644 index 0000000000..a515f89a3b --- /dev/null +++ b/docs/docs/guides/integrate/services/google-workspace.md @@ -0,0 +1,211 @@ +--- +title: Google Workspace SSO with ZITADEL +sidebar_label: Google Workspace +--- + +This guide shows how to enable login with ZITADEL on Google Workspace. + +You can configure two types of SAML SSO on Google Workspace: + +- [SSO profile for your organization](#sso-profile-for-your-organization) +- [Third-party SSO SAML profile](#third-party-sso-saml-profile) + +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](https://support.google.com/a/answer/12032922) in case you need additional information on the Workspace setup. + +:::info OpenID Connect +At this time Google supports SSO with OpenID Connect only for few providers. +::: + +Prerequisites: + +- You need to have a domain registered with your Google Workspace account to configure SSO profiles +- Make sure that you [verify the same domain also in your ZITADEL organization and set it as primary domain](/docs/guides/manage/console/organizations#domain-verification-and-primary-domain) +- A user in Google Workspace (eg, road.runner@acme.com) +- A user in ZITADEL with the same username (eg, road.runner@acme.com); make sure you verify the domain to set the username. This is different than the user's email address + +## SSO profile for your organization + +### Configure SSO profile on Google Workspace + +Open the Google settings for [SSO with third-party IdP](https://admin.google.com/u/1/ac/security/sso) and click on *ADD SSO PROFILE*. + +![SSO with third-party IdP](/img/guides/integrate/services/google-workspace-sso-overview.png) + +Download the public certificate from your ZITADEL instance by requesting `$YOUR_DOMAIN/saml/v2/certificate` + +```bash + wget $YOUR_DOMAIN/saml/v2/certificate -O idp.crt +``` + +Always replace `$YOUR_DOMAIN` with your instance domain. + +Use the following configuration + +| Setting | Value | +| --- | --- | +| Set up SSO with third-party identity provider | Enable (check) | +| Sign-in page URL | $YOUR_DOMAIN/saml/v2/SSO | +| Sign-out page URL | $YOUR_DOMAIN/saml/v2/SLO | +| Verification Certificate | Upload the certificate (idp.crt) | +| Use a domain-specific issuer | Enable (check) | +| Network masks | Leave 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 + + + + + + +``` + +Set or replace the variables with the values from the next screen as follows: + +- `${ENTITYID}`: google.com/a/ +- `${ACSURL}`: https://www.google.com/a//acs + +`` is the domain you have verified in Google Workspace. + +In your existing project: + +Press the "+"-button to add an application +![Project](/img/saml/zitadel/project.png) + +Fill in a name for the application and chose the SAML type, then click "Continue". +![New Application](/img/saml/zitadel/application_saml.png) + +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](/img/saml/zitadel/application_saml_metadata.png) + +Check your application, if everything is correct, press "Create". +![Create Application](/img/saml/zitadel/application_saml_create.png) + +### Activate the SSO profile for your organization + +Make sure to enable the SSO profile for your organization. + +In the [domain-specific service URLs](https://admin.google.com/u/1/ac/security/sso/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](/img/guides/integrate/services/google-workspace-domain-sepcific-urls.png) + +Save the settings. + +![SSO with third-party IdP lower part](/img/guides/integrate/services/google-workspace-sso-bottom.png) + +### 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/ +- Enter your username and credentials +- You should be redirected to Gmail and logged in + +`` 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](https://admin.google.com/u/1/ac/security/sso) and click on *ADD SAML PROFILE*. + +![SSO with third-party IdP](/img/guides/integrate/services/google-workspace-sso-overview.png) + +Download the public certificate from your ZITADEL instance by requesting `$YOUR_DOMAIN/saml/v2/certificate` + +```bash + wget $YOUR_DOMAIN/saml/v2/certificate -O idp.crt +``` + +Always replace `$YOUR_DOMAIN` with your instance domain. + +Use the following configuration + +| Setting | Value | +| --- | --- | +| SSO profile name | ZITADEL 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 Certificate | Upload 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](https://admin.google.com/u/1/ac/security/sso) and click on the SAML Profile *ZITADEL SSO* + +![SSO Profile Overview](/img/guides/integrate/services/google-workspace-sso-zitadel.png) + +You can copy the "Entity ID" and "ACS URL" from the "SP details" section. + +![ZITADEL SSO Profile](/img/guides/integrate/services/google-workspace-zitadel-profile-configured.png) + +### Create a SAML application in ZITADEL + +Create a new .xml file with the following minimal SAML metadata contents: + +```xml + + + + + + +``` + +Set or replace the variables with the values from the next screen as follows: + +- `${ENTITYID}`: https://accounts.google.com/samlrp/metadata?rpid= +- `${ACSURL}`: https://accounts.google.com/samlrp/acs?rpid= + +Replace `` with the values from the [SSO profile](#entity-id-and-acs-url). + +In your existing project: + +Press the "+"-button to add an application +![Project](/img/saml/zitadel/project.png) + +Fill in a name for the application and chose the SAML type, then click "Continue". +![New Application](/img/saml/zitadel/application_saml.png) + +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](/img/saml/zitadel/application_saml_metadata.png) + +Check your application, if everything is correct, press "Create". +![Create Application](/img/saml/zitadel/application_saml_create.png) + +### Activate the SSO profile + +Make sure to enable the SSO profile. + +In the [domain-specific service URLs](https://admin.google.com/u/1/ac/security/sso/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](/img/guides/integrate/services/google-workspace-zitadel-set-profile.png) + +Save the settings. + +![SSO with third-party IdP lower part with ZITADEL SSO](/img/guides/integrate/services/google-workspace-sso-zitadel.png) + +### 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/ +- Enter your username and credentials +- You should be redirected to Gmail and logged in + +`` 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. diff --git a/docs/sidebars.js b/docs/sidebars.js index df47119f3f..55e1ebd8c6 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -282,15 +282,10 @@ module.exports = { }, collapsed: true, items: [ - "guides/integrate/services/gitlab-self-hosted", - "guides/integrate/services/cloudflare-oidc", - "guides/integrate/services/aws-saml", - "guides/integrate/services/google-cloud", - "guides/integrate/services/atlassian-saml", - "guides/integrate/services/gitlab-saml", - "guides/integrate/services/auth0-oidc", - "guides/integrate/services/auth0-saml", - "guides/integrate/services/pingidentity-saml", + { + type: 'autogenerated', + dirName: 'guides/integrate/services', + }, { type: 'link', label: 'Nextcloud', diff --git a/docs/static/img/guides/integrate/services/google-workspace-domain-sepcific-urls.png b/docs/static/img/guides/integrate/services/google-workspace-domain-sepcific-urls.png new file mode 100644 index 0000000000..e8ebd2f467 Binary files /dev/null and b/docs/static/img/guides/integrate/services/google-workspace-domain-sepcific-urls.png differ diff --git a/docs/static/img/guides/integrate/services/google-workspace-sso-bottom.png b/docs/static/img/guides/integrate/services/google-workspace-sso-bottom.png new file mode 100644 index 0000000000..8eba71b0bd Binary files /dev/null and b/docs/static/img/guides/integrate/services/google-workspace-sso-bottom.png differ diff --git a/docs/static/img/guides/integrate/services/google-workspace-sso-overview.png b/docs/static/img/guides/integrate/services/google-workspace-sso-overview.png new file mode 100644 index 0000000000..d32124d72d Binary files /dev/null and b/docs/static/img/guides/integrate/services/google-workspace-sso-overview.png differ diff --git a/docs/static/img/guides/integrate/services/google-workspace-sso-zitadel.png b/docs/static/img/guides/integrate/services/google-workspace-sso-zitadel.png new file mode 100644 index 0000000000..11a1f107d8 Binary files /dev/null and b/docs/static/img/guides/integrate/services/google-workspace-sso-zitadel.png differ diff --git a/docs/static/img/guides/integrate/services/google-workspace-zitadel-profile-configured.png b/docs/static/img/guides/integrate/services/google-workspace-zitadel-profile-configured.png new file mode 100644 index 0000000000..7ab469e011 Binary files /dev/null and b/docs/static/img/guides/integrate/services/google-workspace-zitadel-profile-configured.png differ diff --git a/docs/static/img/guides/integrate/services/google-workspace-zitadel-profile.png b/docs/static/img/guides/integrate/services/google-workspace-zitadel-profile.png new file mode 100644 index 0000000000..21b22f6528 Binary files /dev/null and b/docs/static/img/guides/integrate/services/google-workspace-zitadel-profile.png differ diff --git a/docs/static/img/guides/integrate/services/google-workspace-zitadel-set-profile.png b/docs/static/img/guides/integrate/services/google-workspace-zitadel-set-profile.png new file mode 100644 index 0000000000..ebd8ddff39 Binary files /dev/null and b/docs/static/img/guides/integrate/services/google-workspace-zitadel-set-profile.png differ