mirror of
https://github.com/andwati/zitadel.git
synced 2026-10-22 07:24:26 +00:00
d8ea041c56
## Todos for release - [x] Configure Env in docs project on vercel - [x] Configure Root Path in the docs project on vercel - [ ] Remove old CSP https://github.com/zitadel/website/pull/1592 ## What we did This pull request migrates the project documentation from the old `docs/` directory to the new `apps/docs/` directory, introduces a new documentation system built with Next.js and Fumadocs, and updates all relevant references, configuration files, and documentation to reflect this change. It also adds new configuration and ignore files for the new documentation app, updates CI and linting to exclude the new docs from certain checks, and revises the contributing guidelines accordingly. **Documentation System Migration and New Docs App** * Migrated all documentation from `docs/` to `apps/docs/`, and updated all references in `README.md`, `CONTRIBUTING.md`, and other files to point to the new location. [[1]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L585-L640) [[2]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L660-R607) [[3]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L740-R687) [[4]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L2-R3) [[5]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L30-R30) * Added a new Next.js/Fumadocs-based documentation app under `apps/docs/`, including core app files, layouts, routing, search API, and a comprehensive `README.md` with development and contribution instructions. [[1]](diffhunk://#diff-5a1b07344a2c1b4d3f37b23ff1388b62cd9f57dea3c1cd23d8a0412b7602b132R1-R74) [[2]](diffhunk://#diff-462b9ad1eabbb7d1c29bb9c36e4931eb180fd7190900e6d2babf8f4d66ad1c28R1-R39) [[3]](diffhunk://#diff-e16ae25660ded787b10ac35dea96d5ecaacf895dae0afc8a9bd4382dc79a8c87R1-R7) [apps/docs/app/[[...slug]]/layout.tsxR1-R81](diffhunk://#diff-59e08acde4e805b7aeccef1dcf98f1d71dfc550777e6b9402085cee0e9fa4e0aR1-R81), [apps/docs/app/[[...slug]]/page.tsxR1-R79](diffhunk://#diff-e5df3f80d0fa01e12d63d81f29c57a9d14e846c78fd3beabb2ef768e38fd9580R1-R79), [[4]](diffhunk://#diff-389b34918e040cacaa87cd7201ffa462cc2b0b716736f537e3d3c660ac69353bR1-R7) [[5]](diffhunk://#diff-d3b03416d1c457b19f1c27b26f2db741412df841b875c26ccadc36e4522247f4R1-R29) [[6]](diffhunk://#diff-c8fb8339570a5305809be7c618e14705fd86390dc278e6ce8ba224a7bc8b0c3cR1-R25) **Configuration and Tooling Updates** * Updated `.github/workflows/codeql.yml`, `.golangci.yaml`, and `.github/dependabot.yml` to properly handle the new docs app: excluded `apps/docs` from certain checks, added npm dependency updates for the docs app, and excluded generated content. [[1]](diffhunk://#diff-12783128521e452af0cfac94b99b8d250413c516ec71fe6d97dbea666ff7ba27L8-R14) [[2]](diffhunk://#diff-9917ddc9f1c3304218f7269265b746d997c5c0615478177b5fceecd33ef47cb5R5-R6) [[3]](diffhunk://#diff-9917ddc9f1c3304218f7269265b746d997c5c0615478177b5fceecd33ef47cb5R126-R129) [[4]](diffhunk://#diff-dd4fbda47e51f1e35defb9275a9cd9c212ecde0b870cba89ddaaae65c5f3cd28R89-R106) * Updated `.devcontainer/devcontainer.json` to use the latest Go 1.25.3 version for consistency. **Licensing and Miscellaneous** * Added `apps/docs/` to the list of licensed directories in `LICENSING.md`. These changes ensure the documentation is now maintained in a modern, scalable system and all project tooling is updated to support the new structure. --------- Co-authored-by: Federico Coppede <[email protected]>
212 lines
8.8 KiB
Plaintext
212 lines
8.8 KiB
Plaintext
---
|
|
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.
|
|
|
|
<Callout title="OpenID Connect">
|
|
At this time Google supports SSO with OpenID Connect only for few providers.
|
|
</Callout>
|
|
|
|
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](/guides/manage/console/organizations-overview#primary-domain)
|
|
- A user in Google Workspace (eg, [email protected])
|
|
- A user in ZITADEL with the same username (eg, [email protected]); 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*.
|
|
|
|
|
|
|
|
Download the public certificate from your ZITADEL instance by requesting `${CUSTOM_DOMAIN}/saml/v2/certificate`
|
|
|
|
```bash
|
|
wget ${CUSTOM_DOMAIN}/saml/v2/certificate -O idp.crt
|
|
```
|
|
|
|
Always replace `${CUSTOM_DOMAIN}` with your Custom Domain.
|
|
|
|
Use the following configuration
|
|
|
|
| Setting | Value |
|
|
| --- | --- |
|
|
| Set up SSO with third-party identity provider | Enable (check) |
|
|
| Sign-in page URL | `${CUSTOM_DOMAIN}`/saml/v2/SSO |
|
|
| Sign-out page URL | `${CUSTOM_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 | `${CUSTOM_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
|
|
<?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:
|
|
|
|
- `${ENTITYID}`: `google.com/a/<your_domain>`
|
|
- `${ACSURL}`: `https://www.google.com/a/<your_domain>/acs`
|
|
|
|
`<your_domain>` is the domain you have verified in Google Workspace.
|
|
|
|
In your existing project:
|
|
|
|
Press the "+"-button to add an application
|
|
|
|
|
|
Fill in a name for the application and chose the SAML type, then click "Continue".
|
|
|
|
|
|
Either fill in the URL where ZITADEL can read the metadata from, or upload the metadata XML directly, then click "Continue".
|
|
|
|
|
|
Check your application, if everything is correct, press "Create".
|
|
|
|
|
|
### 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".
|
|
|
|
|
|
|
|
Save the settings.
|
|
|
|
|
|
|
|
### 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](https://admin.google.com/u/1/ac/security/sso) and click on *ADD SAML PROFILE*.
|
|
|
|
|
|
|
|
Download the public certificate from your ZITADEL instance by requesting `${CUSTOM_DOMAIN}/saml/v2/certificate`
|
|
|
|
```bash
|
|
wget ${CUSTOM_DOMAIN}/saml/v2/certificate -O idp.crt
|
|
```
|
|
|
|
Always replace `${CUSTOM_DOMAIN}` with your Custom Domain.
|
|
|
|
Use the following configuration
|
|
|
|
| Setting | Value |
|
|
|--------------------------|----------------------------------------------------|
|
|
| SSO profile name | ZITADEL SSO |
|
|
| IDP entity ID | `${CUSTOM_DOMAIN}`/saml/v2/metadata |
|
|
| Sign-in page URL | `${CUSTOM_DOMAIN}`/saml/v2/SSO |
|
|
| Sign-out page URL | `${CUSTOM_DOMAIN}`/saml/v2/SLO |
|
|
| Change password URL | `${CUSTOM_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*
|
|
|
|
|
|
|
|
You can copy the "Entity ID" and "ACS URL" from the "SP details" section.
|
|
|
|
|
|
|
|
### Create a SAML application in ZITADEL
|
|
|
|
Create a new .xml file with the following minimal SAML metadata contents:
|
|
|
|
```xml
|
|
<?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:
|
|
|
|
- `${ENTITYID}`: `https://accounts.google.com/samlrp/metadata?rpid=<your_value>`
|
|
- `${ACSURL}`: `https://accounts.google.com/samlrp/acs?rpid=<your_value>`
|
|
|
|
Replace `<your_value>` with the values from the [SSO profile](#entity-id-and-acs-url).
|
|
|
|
In your existing project:
|
|
|
|
Press the "+"-button to add an application
|
|
|
|
|
|
Fill in a name for the application and chose the SAML type, then click "Continue".
|
|
|
|
|
|
Either fill in the URL where ZITADEL can read the metadata from, or upload the metadata XML directly, then click "Continue".
|
|
|
|
|
|
Check your application, if everything is correct, press "Create".
|
|
|
|
|
|
### 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".
|
|
|
|
|
|
|
|
Save the settings.
|
|
|
|
|
|
|
|
### 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.
|