mirror of
https://github.com/andwati/zitadel.git
synced 2026-11-22 04:48:46 +00:00
docs: introduce versioned docs and migrate to fuma (#11166)
## 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]>
This commit is contained in:
co-authored by
Federico Coppede
parent
7b6395c348
commit
d8ea041c56
@@ -0,0 +1,9 @@
|
||||
Once you created the provider, it is listed in the providers overview.
|
||||
Activate it by selecting the tick with the tooltip *set as available*.
|
||||
|
||||
If you deactivate a provider, your users with links to it will not be able to authenticate anymore.
|
||||
You can reactivate it and the logins will work again.
|
||||
|
||||
The provider can also be activated via API. As the identity providers are sub-resources of the login settings, this is done by linking the provider to the settings:
|
||||
- [Activate Default Identity Provider](/reference/api/admin/zitadel.admin.v1.AdminService.AddIDPToLoginPolicy)
|
||||
- [Activate Organization Identity Provider](/reference/api/management/zitadel.management.v1.ManagementService.AddIDPToLoginPolicy)
|
||||
@@ -0,0 +1,11 @@
|
||||
1. Go to the Settings
|
||||
- To allow external IdP logins by default, go to your instance default settings at `${CUSTOM_DOMAIN}/ui/console/instance?id=general`
|
||||
- To allow external IdP logins on an organization, go to `${CUSTOM_DOMAIN}/ui/console/org-settings?id=login` and ensure you have the right org context.
|
||||
2. Modify your login policy in the menu "Login Behavior and Security"
|
||||
3. Enable the attribute "External Login allowed"
|
||||
|
||||
You can also change the settings through the API directly either in the default settings or on a specific organization:
|
||||
- [Update Default Login Settings](/reference/api/admin/zitadel.admin.v1.AdminService.UpdateLoginPolicy)
|
||||
- [Update Organization Login Settings](/reference/api/management/zitadel.management.v1.ManagementService.UpdateCustomLoginPolicy)
|
||||
|
||||

|
||||
@@ -0,0 +1,8 @@
|
||||
<p><strong>Automatic creation</strong>: If this setting is enabled the user will be created automatically within ZITADEL, if it doesn't exist.</p>
|
||||
<p><strong>Automatic update</strong>: If this setting is enabled, the user will be updated within ZITADEL, if some user data is changed withing the provider. E.g if the lastname changes on the {props.provider_account}, the information will be changed on the ZITADEL account on the next login.</p>
|
||||
<p><strong>Account creation allowed</strong>: This setting determines if account creation within ZITADEL is allowed or not.</p>
|
||||
<p><strong>Account linking allowed</strong>: This setting determines if account linking is allowed. When logging in with a {props.provider_account}, a linkable ZITADEL account has to exist already.</p>
|
||||
|
||||
<Callout>
|
||||
Either account creation or account linking have to be enabled. Otherwise, the provider can't be used.
|
||||
</Callout>
|
||||
@@ -0,0 +1,12 @@
|
||||
The Generic OAuth Provider allows you to configure any OAuth compliant identity providers.
|
||||
|
||||
The following information you need to fill out by yourself:
|
||||
|
||||
<li><b>Name</b> {props.name}</li>
|
||||
<li><b>Authorization Endpoint</b> {props.authendpoint}</li>
|
||||
<li><b>Token Endpoint</b> {props.tokenendpoint}</li>
|
||||
<li><b>User Endpoint</b> {props.userendpoint}</li>
|
||||
<li><b>ID Attribute</b> {props.id}</li>
|
||||
<li><b>Client-ID</b> {props.clientid}</li>
|
||||
<li><b>Client-Secret</b> {props.clientid}</li>
|
||||
<li><b>Scopes</b>: (openid, profile, email is preconfigured)</li>
|
||||
@@ -0,0 +1,8 @@
|
||||
When you use an LDAP provider in ZITADEL, this is the login process:
|
||||
|
||||
1. ZITADEL tries to connect to the LDAP server with or without TLS depending on the configuration
|
||||
2. If the connection fails, the next server in the list will be used to try again.
|
||||
3. ZITADEL tries a bind with the BindDN and BindPassword to check if it's possible to proceed
|
||||
4. ZITADEL does a SearchQuery to find the UserDN with the provided configuration of base, filters and objectClasses
|
||||
5. ZITADEL tries a bind with the provided loginname and password
|
||||
6. LDAP attributes get mapped to ZITADEL attributes as provided by the configuration
|
||||
@@ -0,0 +1,8 @@
|
||||
Go to the settings page of your instance or organization and choose "Identity Providers".
|
||||
|
||||
In the table you can see all the providers you have configured.
|
||||
Also, you see all provider templates that are available.
|
||||
|
||||

|
||||
|
||||
<p>Select the <b>{props.templates}</b> Provider template.</p>
|
||||
@@ -0,0 +1,9 @@
|
||||
<p>This guides shows you how to connect {props.provider} as an identity provider in ZITADEL.</p>
|
||||
|
||||
<Callout>
|
||||
<p>
|
||||
In ZITADEL you can connect an Identity Provider (IdP) like {props.provider} to your instance and provide it as default to all organizations.
|
||||
Also, you can register the IdP to a specific organization only.
|
||||
If you allow so, your organizations members can do the same in self-service.
|
||||
</p>
|
||||
</Callout>
|
||||
@@ -0,0 +1,5 @@
|
||||
<p>You can use a ZITADEL action if you want to prefill the fields {props.fields} with {props.provider} data.</p>
|
||||
|
||||
1. Go to the users target organizations settings page.
|
||||
2. Add a new action with the body below. Make sure the action name equals the scripts function name. Also change the id in the script to match your provider configurations id.
|
||||
3. Add the action to the flow "External Authentication" and trigger it on "Post Authentication"
|
||||
@@ -0,0 +1,11 @@
|
||||
<p>
|
||||
To test the setup, use incognito mode and browse to your login page. You see a
|
||||
new button which redirects you to {props.loginscreen} screen.
|
||||
</p>
|
||||
|
||||
By default, ZITADEL shows what you define in the default settings.
|
||||
If you overwrite the default settings for an organization, you need to send the organization scope in your auth request.
|
||||
|
||||
The organization scope looks like this: `urn:zitadel:iam:org:id:{id}`.
|
||||
You can [read more about the reserved scopes](/apis/openidoauth/scopes#reserved-scopes)
|
||||
or [use the ZITADEL OIDC Playground](https://zitadel.com/playgrounds/oidc) to see what happens with the login when you send different scopes.
|
||||
@@ -0,0 +1,5 @@
|
||||
<p>
|
||||
New unlinked users are presented with the screen below.
|
||||
<span> {props.provider}</span> is an OAuth provider and does not provide a standardized way to get the user data.
|
||||
This means that ZITADEL has no way to prefill the first and lastname fields.
|
||||
</p>
|
||||
@@ -0,0 +1,15 @@
|
||||
---
|
||||
title: Profile Pre-filling from External IdP
|
||||
sidebar_label: Profile Pre-filling from External IdP
|
||||
---
|
||||
|
||||
import PrefillAction from './_prefill_action.mdx';
|
||||
|
||||
## Automatically pre-fill user data
|
||||
|
||||
<PrefillAction components={props.components} fields="specific fields like firstname, lastname and email verified" provider="your providers"/>
|
||||
|
||||
This action is an example for OKTA. You can also use it for any other provider
|
||||
```js reference
|
||||
https://github.com/zitadel/actions/blob/main/examples/okta_identity_provider.js
|
||||
```
|
||||
@@ -0,0 +1,88 @@
|
||||
---
|
||||
title: Configure Apple as an Identity Provider in ZITADEL
|
||||
sidebar_label: Apple
|
||||
---
|
||||
|
||||
import GeneralConfigDescription from './_general_config_description.mdx';
|
||||
import Intro from './_intro.mdx';
|
||||
import CustomLoginPolicy from './_custom_login_policy.mdx';
|
||||
import IDPsOverview from './_idps_overview.mdx';
|
||||
import Activate from './_activate.mdx';
|
||||
import TestSetup from './_test_setup.mdx';
|
||||
|
||||
<Intro components={props.components} provider="Apple"/>
|
||||
|
||||
## Open the Apple Identity Provider Template
|
||||
|
||||
<IDPsOverview components={props.components} templates="Apple"/>
|
||||
|
||||
Click on the ZITADEL Callback URL to copy it to your clipboard.
|
||||
You will have to paste it in the Apple service later.
|
||||
|
||||

|
||||
|
||||
## Apple Configuration
|
||||
|
||||
### Register a new App
|
||||
|
||||
1. Go to the Identifiers of your Apple Developer Account
|
||||
2. Click the add button "+" on the top left
|
||||
3. Choose App IDs and click "continue"
|
||||
4. Add a description and a unique identifier
|
||||
5. Enable "Sign in with Apple" and click "continue"
|
||||
|
||||
### Register a new service
|
||||
|
||||
1. Go to the Identifiers of your Apple Developer Account: [https://developer.apple.com/account/resources/identifiers/list](https://developer.apple.com/account/resources/identifiers/list)
|
||||
2. Click the add button "+" on the top left
|
||||
3. Choose Services IDs and click "continue"
|
||||
4. Add a description and a unique identifier and click "register"
|
||||
5. Select your registered service from the list and enable sign in with Apple, then click "configure"
|
||||
6. Choose the previously created App in the Primary App ID List
|
||||
7. Add your Custom Domain in the domains and subdomains field
|
||||
- Example domain for `https://acme-gzoe4x.zitadel.cloud` would look like this: `acme-gzoe4x.zitadel.cloud`
|
||||
8. [Paste the ZITADEL Callback URL you copied before](#open-the-apple-identity-provider-template) to the Return URLs
|
||||
|
||||

|
||||
|
||||
### Register a new key
|
||||
|
||||
1. Go to the keys list of your Apple Developer Account: [https://developer.apple.com/account/resources/authkeys/list](https://developer.apple.com/account/resources/authkeys/list)
|
||||
2. Click the add button "+" on the top left
|
||||
3. Give your key a name
|
||||
4. Enable "Sign in with Apple" and click configure
|
||||
5. Choose your app from the list
|
||||
6. Register the key and download it
|
||||
|
||||
## ZITADEL Configuration
|
||||
|
||||
Go back [to the Apple provider template you opened before in ZITADEL](#open-the-apple-identity-provider-template).
|
||||
|
||||
1. Add the Client ID, this is [the identifier of the service you created in your Apple Account](#register-a-new-service)
|
||||
2. Fill the Team ID, you can find it when you login to your Apple Developer account, in your membership
|
||||
3. Enter the [Key ID and upload the Private Key you created before](#register-a-new-key)
|
||||
|
||||
You can optionally configure the following settings.
|
||||
A useful default will be filled if you don't change anything.
|
||||
|
||||
**Scopes**: The scopes define which scopes will be sent to the provider, `name` and `email` are prefilled. This information will be taken to create/update the user within ZITADEL.
|
||||
|
||||
<GeneralConfigDescription components={props.components} provider_account="Apple account" />
|
||||
|
||||
### Activate IdP
|
||||
|
||||
<Activate components={props.components} />
|
||||
|
||||

|
||||
|
||||
### Ensure your Login Policy allows External IDPs
|
||||
|
||||
<CustomLoginPolicy components={props.components} />
|
||||
|
||||
## Test the setup
|
||||
|
||||
<TestSetup components={props.components} loginscreen="your Apple login"/>
|
||||
|
||||

|
||||
|
||||

|
||||
@@ -0,0 +1,112 @@
|
||||
---
|
||||
title: Configure Entra ID as an Identity Provider in ZITADEL
|
||||
sidebar_label: Entra ID
|
||||
---
|
||||
|
||||
import GeneralConfigDescription from './_general_config_description.mdx';
|
||||
import Intro from './_intro.mdx';
|
||||
import CustomLoginPolicy from './_custom_login_policy.mdx';
|
||||
import IDPsOverview from './_idps_overview.mdx';
|
||||
import TestSetup from './_test_setup.mdx';
|
||||
import Activate from './_activate.mdx';
|
||||
|
||||
<Intro components={props.components} provider="Entra ID (former Azure Active Directory)"/>
|
||||
|
||||
## Open the Microsoft Identity Provider Template
|
||||
|
||||
<IDPsOverview components={props.components} templates="Microsoft"/>
|
||||
|
||||
Click on the ZITADEL Callback URL to copy it to your clipboard.
|
||||
You will have to paste it in the Entra ID Client later.
|
||||
|
||||

|
||||
|
||||
## Entra ID Configuration
|
||||
|
||||
You need to have access to an Entra ID Tenant. If you do not yet have one follow [this guide from Microsoft](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant) to create one for free.
|
||||
|
||||
### Register a new client
|
||||
|
||||
1. Browse to the [App registration menus create dialog](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/CreateApplicationBlade/quickStartType~/null/isMSAApp~/false) to create a new app.
|
||||
2. Give the application a name and choose who should be able to login (Single-Tenant, Multi-Tenant, Personal Accounts, etc.) This setting will also have an impact on how to configure the provider later on in ZITADEL.
|
||||
3. Choose "Web" in the redirect uri field and [paste the ZITADEL Callback URL you copied before](#open-the-microsoft-identity-provider-template).
|
||||
4. Save the Application (client) ID and the Directory (tenant) ID from the detail page
|
||||
5. Register the application
|
||||
|
||||

|
||||
|
||||

|
||||
|
||||
### Add client secret
|
||||
|
||||
Generate a new client secret to authenticate your user.
|
||||
|
||||
1. Click on client credentials on the detail page of the application or use the menu "Certificates & secrets"
|
||||
2. Click on "+ New client secret" and enter a description and an expiry date, add the secret afterwards
|
||||
3. Copy the value of the secret. You will not be able to see the value again after some time
|
||||
|
||||

|
||||
|
||||
### Token configuration
|
||||
|
||||
To allow ZITADEL to get the information from the authenticating user you have to configure what kind of optional claims should be returned in the token.
|
||||
|
||||
1. Click on Token configuration in the side menu
|
||||
2. Click on "+ Add optional claim"
|
||||
3. Add email, family_name (last name of the user), given_name (first name of the user) and preferred_username to the id token
|
||||
|
||||

|
||||
|
||||
### API permissions
|
||||
|
||||
To be able to get all the information that ZITADEL needs, you have to configure the correct permissions.
|
||||
|
||||
1. Go to "API permissions" in the side menu
|
||||
2. Make sure the permissions include "Microsoft Graph": email, profile and User.Read
|
||||
3. The "Other permissions granted" should include "Microsoft Graph: openid"
|
||||
|
||||

|
||||
|
||||
## ZITADEL Configuration
|
||||
|
||||
Go back [to the Microsoft provider template you opened before in ZITADEL](#open-the-microsoft-identity-provider-template).
|
||||
Add the [client ID and secret created before on your Entra ID application](#add-client-secret).
|
||||
|
||||
You can optionally configure the following settings.
|
||||
A useful default will be filled if you don't change anything.
|
||||
|
||||
**Scopes**: The scopes define which scopes will be sent to the provider, `openid`, `profile`, and `email` are prefilled.
|
||||
This information will be taken to create/update the user within ZITADEL. Make sure to also add `User.Read`. ZITADEL ensures that at least `openid` and `User.Read` scopes are always sent.
|
||||
|
||||
**Email Verified**: Entra ID doesn't send the email verified claim in the users token, if you don't enable this setting.
|
||||
The user is then created with an unverified email, which results in an email verification message.
|
||||
If you want to avoid that, make sure to enable "Email verified".
|
||||
In that case, the user is created with a verified email address.
|
||||
|
||||
**Tenant Type**: Configure the tenant type according to what you have chosen in the settings of your Entra ID application previously.
|
||||
- Common: Choose common if you want all Microsoft accounts being able to login.
|
||||
In this case, configure "Accounts in any organizational directory and personal Microsoft accounts" in your Entra ID App.
|
||||
- Organizations: Choose organization if you have Entra ID Tenants and no personal accounts. (You have configured either "Accounts in this organization" or "Accounts in any organizational directory" on your Azure APP)
|
||||
- Consumers: Choose this if you want to allow public accounts. (In your Entra ID App you have configured "Personal Microsoft accounts only")
|
||||
|
||||
**Tenant ID**: If you have selected *Tenant ID* as *Tenant Type*, you have to enter the *Directory (Tenant) ID* into the *Tenant ID* field, copied previously from the Azure App configuration.
|
||||
|
||||
<GeneralConfigDescription components={props.components} provider_account="Microsoft account" />
|
||||
|
||||
### Activate IdP
|
||||
|
||||
<Activate components={props.components} />
|
||||
|
||||

|
||||
|
||||
### Ensure your Login Policy allows External IDPs
|
||||
|
||||
<CustomLoginPolicy components={props.components} />
|
||||
|
||||
## Test the setup
|
||||
|
||||
<TestSetup components={props.components} loginscreen="your Microsoft login"/>
|
||||
|
||||

|
||||
|
||||

|
||||
@@ -0,0 +1,129 @@
|
||||
---
|
||||
title: Configure Entra ID as a SAML Service Provider in ZITADEL
|
||||
sidebar_label: Entra ID SAML
|
||||
---
|
||||
|
||||
import GeneralConfigDescription from './_general_config_description.mdx';
|
||||
import Intro from './_intro.mdx';
|
||||
import CustomLoginPolicy from './_custom_login_policy.mdx';
|
||||
import IDPsOverview from './_idps_overview.mdx';
|
||||
import Activate from './_activate.mdx';
|
||||
import PrefillAction from './_prefill_action.mdx';
|
||||
|
||||
<Intro components={props.components} provider="Entra ID (former Azure Active Directory)"/>
|
||||
|
||||
## Entra ID SAML Configuration
|
||||
|
||||
You need to have access to an Entra ID Tenant. If you do not yet have one follow [this guide from Microsoft](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant) to create one for free.
|
||||
|
||||
### Register a new enterprise application in Entra
|
||||
|
||||
We start setting up the enterprise application.
|
||||
|
||||
1. Browse to the [Enterprise App registration menu](https://entra.microsoft.com/#view/Microsoft_AAD_IAM/AppGalleryBladeV2).
|
||||
2. Search for "SAML Toolkit" and click on the "Microsoft Entra SAML Toolkit" card.
|
||||
3. Change the name if wanted and click "Create"
|
||||
|
||||

|
||||
|
||||
### Disable required assignment
|
||||
|
||||
To allow all users to sign in using ZITADEL we need to manually disable required assignment:
|
||||
|
||||
1. Go to Manage > Properties
|
||||
2. Set "Assignment required?" to No
|
||||
3. Hit Save
|
||||
|
||||

|
||||
|
||||
### Setup SAML
|
||||
|
||||
Configure the sign-on method of the app.
|
||||
|
||||
1. Go to Manage > Single sign-on
|
||||
2. Select SAML
|
||||
3. You will be redirected to the Single Sign-On details page
|
||||
4. Copy the URL of SAML Certificates > App Federation Metadata Url to your clipboard
|
||||
|
||||

|
||||
|
||||
## ZITADEL Configuration
|
||||
|
||||
### Go to the IdP Providers Overview
|
||||
|
||||
<IDPsOverview components={props.components} templates="SAML"/>
|
||||
|
||||
### Create a new SAML Service Provider (SP)
|
||||
|
||||
Now we configure the identity provider on ZITADEL.
|
||||
|
||||
1. Set a name like "Microsoft Entra"
|
||||
2. Paste the previously copied URL into the "Metadata URL"-field. The metadata will automatically be fetched from the provided URL after creation.
|
||||
3. Select the "SAML_POST_BINDING" as binding
|
||||
4. Ensure that the "Signed Request"-box is ticked
|
||||
5. Change the options if needed. Microsoft Entra works out of the box using the pre configured options.
|
||||
6. Click Create
|
||||
|
||||
<GeneralConfigDescription components={props.components} provider_account="Microsoft account" />
|
||||
|
||||

|
||||
|
||||
## Configure Basic SAML Configuration
|
||||
|
||||
After you created the SAML provider in ZITADEL, you can copy the URLs you need to configure in your Entra ID application.
|
||||
|
||||

|
||||
|
||||
1. Go to Microsoft Entra > Manage > Single sign-on
|
||||
2. Edit the "Basic SAML Configuration"
|
||||
3. **Identifier (Entity ID)**: Paste the *ZITADEL Metadata URL*.
|
||||
4. **Reply URL (Assertion Consumer Service URL)**: Paste the *ZITADEL ACS Login Form URL*
|
||||
5. **Sign on URL**: Paste the *ZITADEL ACS Login Form URL*
|
||||
6. **Logout URL**: Paste the *ZITADEL Single Logout URL*
|
||||
7. Optionally, you can enable the "Federated Logout", which will log out the user from Entra ID once they terminate their session in ZITADEL using the OIDC End Session Endpoint.
|
||||
8. Click Save
|
||||
|
||||
<Callout>
|
||||
You can ignore the ZITADEL ACS Intent API URL for now.
|
||||
This is relevant if you want to [programmatically sign users in at ZITADEL via a SAML Service Provider](/guides/integrate/login-ui/external-login).
|
||||
</Callout>
|
||||
|
||||

|
||||
|
||||
## Enable the Microsoft Entra Button in ZITADELs Login Page
|
||||
|
||||
Go back to ZITADEL and activate the IdP.
|
||||
|
||||
### Activate IdP
|
||||
|
||||
<Activate components={props.components} />
|
||||
|
||||

|
||||
|
||||
### Ensure your Login Policy allows External IDPs
|
||||
|
||||
<CustomLoginPolicy components={props.components} />
|
||||
|
||||
## Test the setup
|
||||
|
||||
<p>
|
||||
To test the setup, use incognito mode and browse to your login page.
|
||||
You see a new button which redirects you to Microsoft Entra screen.
|
||||
</p>
|
||||
|
||||
By default, ZITADEL shows what you define in the default settings.
|
||||
If you overwrite the default settings for an organization, you need to send the organization scope in your auth request.
|
||||
|
||||

|
||||
|
||||
Click **Microsoft Entra**
|
||||
|
||||

|
||||
|
||||
### Add Action to map user attributes
|
||||
|
||||
<PrefillAction components={props.components} fields="username, firstname, lastname, displayname, email and email verified" provider="Entra"/>
|
||||
|
||||
```js reference
|
||||
https://github.com/zitadel/actions/blob/main/examples/entra_id_saml_prefil_register_form.js
|
||||
```
|
||||
@@ -0,0 +1,68 @@
|
||||
---
|
||||
title: Configure a Generic OIDC Identity Provider in ZITADEL
|
||||
sidebar_label: Generic OIDC
|
||||
id: generic-oidc
|
||||
---
|
||||
|
||||
import GeneralConfigDescription from './_general_config_description.mdx';
|
||||
import Intro from './_intro.mdx';
|
||||
import CustomLoginPolicy from './_custom_login_policy.mdx';
|
||||
import IDPsOverview from './_idps_overview.mdx';
|
||||
import Activate from './_activate.mdx';
|
||||
import PrefillAction from './_prefill_action.mdx';
|
||||
import TestSetup from './_test_setup.mdx';
|
||||
|
||||
<Intro components={props.components} provider="your OIDC Provider"/>
|
||||
|
||||
## Open the Generic OIDC Provider Template
|
||||
|
||||
<IDPsOverview components={props.components} templates="Generic OIDC"/>
|
||||
|
||||
Click on the ZITADEL Callback URL to copy it to your clipboard.
|
||||
You will have to paste this URL in your external OIDC provider's application configuration later.
|
||||
|
||||

|
||||
|
||||
## OIDC Provider Configuration
|
||||
|
||||
### Register a new client/application
|
||||
|
||||
1. Log in to your external OIDC Provider's dashboard or management console.
|
||||
2. Navigate to the applications, clients, or integrations section (name may vary depending on your provider).
|
||||
3. Create a new application or client and select "OIDC" or "OpenID Connect" as the type.
|
||||
4. Set a name for the application.
|
||||
5. [Paste the ZITADEL Callback URL you copied before](#open-the-generic-oidc-provider-template) into the "redirect URIs" or "sign-in redirect URIs" field.
|
||||
6. Save or copy the generated **Client ID** and **Client Secret**.
|
||||
|
||||
> The exact steps and terminology may vary for each provider. Refer to your provider's documentation if you don't see these options.
|
||||
|
||||
## ZITADEL Configuration
|
||||
|
||||
1. Return to [the Generic OIDC Provider template in ZITADEL](#open-the-generic-oidc-provider-template).
|
||||
2. Enter the **Client ID** and **Client Secret** from your OIDC provider's application.
|
||||
3. Give the provider a name (e.g., "My OIDC Provider"). This name will appear as a button on the ZITADEL login screen.
|
||||
4. Enter the **Issuer URL** of your OIDC provider (e.g., `https://your-provider.example.com`).
|
||||
|
||||
You can optionally configure the following settings. ZITADEL provides sensible defaults if you leave these unchanged.
|
||||
|
||||
**Scopes**: The scopes define which information ZITADEL will request from the provider. `openid`, `profile`, and `email` are pre-filled.
|
||||
This information is used to create or update the user within ZITADEL.
|
||||
ZITADEL ensures that at least the `openid` scope is always sent.
|
||||
|
||||
**Use PKCE**: If enabled, Proof Key for Code Exchange (PKCE) will be used to secure the authorization code flow in addition to the client secret.
|
||||
|
||||
<GeneralConfigDescription components={props.components} provider_account="OIDC provider account" />
|
||||
|
||||
### Activate IdP
|
||||
|
||||
<Activate components={props.components} />
|
||||
|
||||

|
||||
|
||||
### Ensure your Login Policy allows External IDPs
|
||||
|
||||
<CustomLoginPolicy components={props.components} />
|
||||
|
||||
## Test the setup
|
||||
|
||||
<TestSetup components={props.components} loginscreen="your OIDC provider login"/>
|
||||
@@ -0,0 +1,90 @@
|
||||
---
|
||||
title: Configure GitHub as an Identity Provider in ZITADEL
|
||||
sidebar_label: GitHub
|
||||
---
|
||||
|
||||
import GeneralConfigDescription from './_general_config_description.mdx';
|
||||
import Intro from './_intro.mdx';
|
||||
import CustomLoginPolicy from './_custom_login_policy.mdx';
|
||||
import IDPsOverview from './_idps_overview.mdx';
|
||||
import Activate from './_activate.mdx';
|
||||
import TestSetup from './_test_setup.mdx';
|
||||
import UnlinkedOAuth from './_unlinked_oauth.mdx';
|
||||
import PrefillAction from './_prefill_action.mdx';
|
||||
|
||||
<Intro components={props.components} provider="GitHub"/>
|
||||
|
||||
## Open the GitHub Identity Provider Template
|
||||
|
||||
<IDPsOverview components={props.components} templates="GitHub or GitHub Enterprise Server"/>
|
||||
|
||||
Click on the ZITADEL Callback URL to copy it to your clipboard.
|
||||
You will have to paste it to the GitHub OAuth application later.
|
||||
|
||||

|
||||
|
||||
## GitHub Configuration
|
||||
|
||||
### Register a new application
|
||||
|
||||
1. Create a new OAuth application
|
||||
- For **GitHub** browse to the [Register a new OAuth application](https://github.com/settings/applications/new). You can find this link withing [Settings](https://github.com/settings/profile) - [Developer Settings](https://github.com/settings/apps) - - [OAuth Apps](https://github.com/settings/developers).
|
||||
- For **GitHub Enterprise** go to your GitHub Enterprise home page and then to Settings - Developer Settings - OAuth Apps - Register a new application/New OAuth App
|
||||
2. Fill in the application name and homepage URL.
|
||||
3. [Paste the ZITADEL Callback URL you copied before](#open-the-github-identity-provider-template) to the Authorization callback URL field.
|
||||
4. Click "Register application".
|
||||
|
||||

|
||||
|
||||
### Client ID and secret
|
||||
|
||||
After clicking "Register application", you see the detail page of the application you have just created.
|
||||
Copy the client ID directly from the detail page.
|
||||
Generate a new secret by clicking "Generate new client secret".
|
||||
Make sure to save the secret, as you will not be able to show it again.
|
||||
|
||||

|
||||
|
||||
## ZITADEL Configuration
|
||||
|
||||
Go back [to the GitHub provider template you opened before in ZITADEL](#open-the-github-identity-provider-template).
|
||||
Add the [client ID and secret you created before when you registered your GitHub OAuth application](#client-id-and-secret).
|
||||
|
||||
You can optionally configure the following settings.
|
||||
A useful default will be filled if you don't change anything.
|
||||
|
||||
**Scopes**: The scopes define which scopes will be sent to the provider, `openid`, `profile`, and `email` are prefilled.
|
||||
This information is used to create and/or update the user within ZITADEL.
|
||||
ZITADEL ensures that at least the `openid`-scope is always sent.
|
||||
|
||||
<GeneralConfigDescription components={props.components} provider_account="GitHub account" />
|
||||
|
||||
### Activate IdP
|
||||
|
||||
<Activate components={props.components} />
|
||||
|
||||

|
||||
|
||||
### Ensure your Login Policy allows External IDPs
|
||||
|
||||
<CustomLoginPolicy components={props.components} />
|
||||
|
||||
## Test the setup
|
||||
|
||||
<TestSetup components={props.components} loginscreen="your GitHub login"/>
|
||||
|
||||

|
||||
|
||||

|
||||
|
||||
<UnlinkedOAuth components={props.components} provider="GitHub"/>
|
||||
|
||||

|
||||
|
||||
## Optional: Add ZITADEL action to autofill userdata
|
||||
|
||||
<PrefillAction components={props.components} fields="firstname and lastname" provider="GitHub"/>
|
||||
|
||||
```js reference
|
||||
https://github.com/zitadel/actions/blob/main/examples/github_identity_provider.js
|
||||
```
|
||||
@@ -0,0 +1,88 @@
|
||||
---
|
||||
title: Configure GitLab as an Identity Provider in ZITADEL
|
||||
sidebar_label: GitLab
|
||||
---
|
||||
|
||||
import GeneralConfigDescription from './_general_config_description.mdx';
|
||||
import Intro from './_intro.mdx';
|
||||
import CustomLoginPolicy from './_custom_login_policy.mdx';
|
||||
import IDPsOverview from './_idps_overview.mdx';
|
||||
import Activate from './_activate.mdx';
|
||||
import TestSetup from './_test_setup.mdx';
|
||||
import UnlinkedOAuth from './_unlinked_oauth.mdx';
|
||||
import PrefillAction from './_prefill_action.mdx';
|
||||
|
||||
<Intro components={props.components} provider="GitLab"/>
|
||||
|
||||
## Open the GitLab Identity Provider Template
|
||||
|
||||
<IDPsOverview components={props.components} templates="GitLab or GitLab Self Hosted"/>
|
||||
|
||||
Click on the ZITADEL Callback URL to copy it to your clipboard.
|
||||
You will have to paste it to the GitLab Application later.
|
||||
|
||||

|
||||
|
||||
## GitLab Configuration
|
||||
|
||||
### Register a new application
|
||||
|
||||
1. Login to [gitlab.com](https://gitlab.com) or to your GitLab self-hosted instance
|
||||
2. Select [Edit Profile](https://gitlab.com/-/profile)
|
||||
3. Click on [Applications](https://gitlab.com/-/profile/applications) in the side navigation
|
||||
4. Fill in the application name
|
||||
5. [Paste the ZITADEL Callback URL you copied before](#open-the-gitlab-identity-provider-template) to the Redirect URI field.
|
||||
|
||||

|
||||
|
||||
### Client ID and secret
|
||||
|
||||
After clicking "Save application", you will see the detail page of the application you have just created.
|
||||
To be able to connect GitLab to ZITADEL you will need a client ID and a client secret.
|
||||
Save the ID and the Secret, you will not be able to copy the secret again, if you lose it you have to generate a new one.
|
||||
|
||||

|
||||
|
||||
## ZITADEL Configuration
|
||||
|
||||
Go back [to the GitLab provider template you opened before in ZITADEL](#open-the-gitlab-identity-provider-template).
|
||||
Add the [client ID and secret you created before when you registered your GitLab application](#client-id-and-secret).
|
||||
|
||||
You can optionally configure the following settings.
|
||||
A useful default will be filled if you don't change anything.
|
||||
|
||||
**Scopes**: The scopes define which scopes will be sent to the provider, `openid`, `profile`, and `email` are prefilled.
|
||||
This information will be taken to create/update the user within ZITADEL.
|
||||
ZITADEL ensures that at least the `openid`-scope is always sent.
|
||||
|
||||
<GeneralConfigDescription components={props.components} provider_account="GitLab account" />
|
||||
|
||||
### Activate IdP
|
||||
|
||||
<Activate components={props.components} />
|
||||
|
||||

|
||||
|
||||
### Ensure your Login Policy allows External IDPs
|
||||
|
||||
<CustomLoginPolicy components={props.components} />
|
||||
|
||||
## Test the setup
|
||||
|
||||
<TestSetup components={props.components} loginscreen="your GitLab login"/>
|
||||
|
||||

|
||||
|
||||

|
||||
|
||||
<UnlinkedOAuth components={props.components} provider="GitLab"/>
|
||||
|
||||

|
||||
|
||||
## Optional: Add ZITADEL action to autofill userdata
|
||||
|
||||
<PrefillAction components={props.components} fields="firstname and lastname" provider="GitLab"/>
|
||||
|
||||
```js reference
|
||||
https://github.com/zitadel/actions/blob/main/examples/gitlab_identity_provider.js
|
||||
```
|
||||
@@ -0,0 +1,74 @@
|
||||
---
|
||||
title: Configure Google as an Identity Provider in ZITADEL
|
||||
sidebar_label: Google
|
||||
---
|
||||
|
||||
import GeneralConfigDescription from './_general_config_description.mdx';
|
||||
import Intro from './_intro.mdx';
|
||||
import CustomLoginPolicy from './_custom_login_policy.mdx';
|
||||
import IDPsOverview from './_idps_overview.mdx';
|
||||
import Activate from './_activate.mdx';
|
||||
import TestSetup from './_test_setup.mdx';
|
||||
import { ResponsivePlayer } from "@/components/player";
|
||||
|
||||
<Intro components={props.components} provider="Google"/>
|
||||
|
||||
<ResponsivePlayer controls url='https://www.youtube.com/watch?v=wg-ee-EnHdE' />
|
||||
|
||||
## Open the Google Identity Provider Template
|
||||
|
||||
<IDPsOverview components={props.components} templates="Google"/>
|
||||
|
||||
Click on the ZITADEL Callback URL to copy it to your clipboard.
|
||||
You will have to paste it in the Google Cloud Platform later.
|
||||
|
||||

|
||||
|
||||
## Google Configuration
|
||||
|
||||
### Register a new client
|
||||
|
||||
1. Go to the Google Cloud Platform and choose your project: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)
|
||||
2. Click on "+ CREATE CREDENTIALS" and choose "OAuth client ID"
|
||||
3. Choose "Web application" as application type and give a name
|
||||
4. [Paste the ZITADEL Callback URL you copied before](#open-the-google-identity-provider-template) into the authorized redirect URIs
|
||||
|
||||

|
||||
|
||||
### Client ID and secret
|
||||
|
||||
You will need the Client ID and Client secret to configure the Google Identity Provider in ZITADEL.
|
||||
|
||||

|
||||
|
||||
## ZITADEL Configuration
|
||||
|
||||
Go back [to the Google provider template you opened before in ZITADEL](#open-the-google-identity-provider-template).
|
||||
Add the [client ID and secret created before on your Google App](#client-id-and-client-secret).
|
||||
|
||||
You can optionally configure the following settings.
|
||||
A useful default will be filled if you don't change anything.
|
||||
|
||||
**Scopes**: The scopes define which scopes will be sent to the provider, `openid`, `profile`, and `email` are prefilled.
|
||||
This information will be taken to create/update the user within ZITADEL.
|
||||
ZITADEL ensures that at least the `openid`-scope is always sent.
|
||||
|
||||
<GeneralConfigDescription components={props.components} provider_account="Google account" />
|
||||
|
||||
### Activate IdP
|
||||
|
||||
<Activate components={props.components} />
|
||||
|
||||

|
||||
|
||||
### Ensure your Login Policy allows External IDPs
|
||||
|
||||
<CustomLoginPolicy components={props.components} />
|
||||
|
||||
## Test the setup
|
||||
|
||||
<TestSetup components={props.components} loginscreen="your Google login"/>
|
||||
|
||||

|
||||
|
||||

|
||||
@@ -0,0 +1,148 @@
|
||||
---
|
||||
title: Let Users Login with Preferred Identity Provider
|
||||
sidebar_label: Login users with SSO
|
||||
---
|
||||
|
||||
## External Identity Providers and SSO authentication
|
||||
|
||||
An **Identity Provider (IdP)** is a service that creates and maintains identity information and then provides authentication services to your applications. Incorporating SSO (Single Sign-On) authentication allows users to access multiple services with a single set of credentials, enhancing user convenience and security. As you develop your application, you want to give users the freedom to choose an Identity Provider they use to sign in to your application, despite having your own IdP (e.g., ZITADEL). Many users already have trusted accounts with popular IdPs like Google, GitHub, or LinkedIn, making these services effective identity brokers in the SSO landscape. Or it could be an IdP they’re already using in the workplace, such as EntraID or Auth0, which supports SSO authentication. These can be identified as *External Identity Providers*. Allowing them to use these accounts for signing into your application means they don’t need to create new usernames and passwords, thereby significantly enhancing their convenience and the likelihood they’ll engage with your product.
|
||||
|
||||
Using external IdPs can also improve security and user trust in your application. These major IdPs have robust security measures in place, reducing the burden on your application to manage secure passwords. Furthermore, by leveraging external IdPs as part of an SSO framework, you're aligning with a user-centric approach, prioritizing their preferences and simplifying their access to your services.
|
||||
|
||||
However, integrating these external IdPs with your system requires a clear understanding of the connection process with your IdP, acting as an identity broker to facilitate SSO authentication . This ensures that you can offer this flexibility without compromising on security or user experience. Integrating external IdPs alongside your own offers the best of both worlds: the ease and security of established accounts through SSO and the tailored experience of your application.
|
||||
|
||||
## Where ZITADEL fits in
|
||||
|
||||
ZITADEL positions itself as the central hub or the identity broker in the interaction between your application and various external IdPs. It handles the orchestration of authentication requests and manages the seamless flow of identity verification between your application and the chosen IdP. This is achieved through a process known as federation, where ZITADEL acts as a federated identity provider, integrating IdPs via authentication protocols like OpenID Connect and SAML.
|
||||
|
||||
## Adding external identity providers to your application
|
||||
|
||||
With ZITADEL, you can enhance your application's accessibility by integrating social login IdPs such as Google or other IdPs such as EntraID (formerly known as AzureAD) and Auth0. For organizations with bespoke identity solutions, ZITADEL supports integration with custom-built IdPs that adhere to OpenID Connect or SAML protocols. By default, ZITADEL can serve as the primary user store for your applications. This centralizes user management and simplifies the authentication process, allowing users to sign in with their email and password, or via the external IdPs you've integrated.
|
||||
|
||||
ZITADEL excels in B2B scenarios by offering the flexibility to configure different IdPs for distinct customers, enhancing ease of use and customization. For instance, you could have Customer A utilize EntraID for authentication, while Customer B uses Okta. This versatility enables you to tailor authentication solutions to meet the specific needs of each customer, streamlining their access while maintaining a centralized management system.
|
||||
|
||||
## The advantages of using ZITADEL
|
||||
|
||||
The benefits of integrating ZITADEL for managing external IdPs are multiple:
|
||||
|
||||
- **No need for custom authentication code**: Your application only needs to interact with ZITADEL, which handles all communications with external IdPs. This abstraction saves you from the complexity of direct integration with multiple IdPs.
|
||||
|
||||
- **Unified protocol handling**: ZITADEL abstracts away the specific protocols used by different IdPs. Your application communicates with ZITADEL using a standard protocol (e.g., OpenID Connect), while ZITADEL takes care of the rest.
|
||||
|
||||
- **Centralized user management**: All user profiles are managed within ZITADEL, allowing for a unified view of user identities regardless of the IdP used for authentication.
|
||||
|
||||
- **Dynamic profile synchronization**: When users update their profiles on an external IdP, those changes are reflected in ZITADEL at the next login, ensuring that user data remains current.
|
||||
|
||||
- **Simplified account linking**: ZITADEL can link identities from multiple IdPs to a single user profile, facilitating a cohesive user experience across different authentication methods.
|
||||
|
||||
## The user journey
|
||||
|
||||
- **Integration with external identity providers**: ZITADEL supports integrating a variety of external identity providers, including social logins like Google or GitHub, as well as custom IdPs that use OpenID Connect or SAML protocols.
|
||||
|
||||
- **Initiation of sign-in process**: Users select to sign in with an external IdP within your application.
|
||||
|
||||
- **Redirection to ZITADEL**: The application redirects the user to ZITADEL, which guides them to their chosen external IdP for authentication.
|
||||
|
||||
- **User authentication**: After successfully logging in at the external IdP site, users are redirected back to the application through ZITADEL, bringing along authentication tokens and profile information.
|
||||
|
||||
- **Account linking for new users**: If the user's identity from the external IdP does not exist in ZITADEL, they're presented with two options before moving forward:
|
||||
- **Create a new account**: Choosing this option creates a new ZITADEL account linked to the external IdP.
|
||||
- **Linking with an existing local account**: Users have the option to link their new external identity to an existing local account in ZITADEL, enabling future logins with either their local account or the external IdP.
|
||||
|
||||
- **Profile pre-filling from external IdP**: ZITADEL uses information from the external IdP to pre-fill the user's profile, simplifying the account creation or linking process.
|
||||
|
||||
- **User option to update profile**: Users can review and, if necessary, update their pre-filled profile information.
|
||||
|
||||
- **Session creation and access granting**: After the account is created or linked and the profile is set, the application grants access by creating a session for the user based on their authenticated identity.
|
||||
|
||||
## Setting up external identity providers in ZITADEL
|
||||
|
||||
In ZITADEL, you have the flexibility to link an external Identity Provider (IdP) to your entire instance, making it the default option for all organizations within your instance, or to connect it exclusively to a specific organization. This setup allows organization members to leverage similar capabilities in self-service if permitted.
|
||||
|
||||
### Adjusting the custom login policy
|
||||
|
||||
The login policy can be set as a default at the instance level and can be customized for each organization. The configuration process varies slightly depending on your focus:
|
||||
|
||||
- **For default settings**, navigate to: `${CUSTOM_DOMAIN}/ui/console/instance?id=general`
|
||||
- **For specific organization settings**, select the organization from the menu and visit: `${CUSTOM_DOMAIN}/ui/console/org-settings?id=login`
|
||||
|
||||
Once in the settings:
|
||||
- Access the **Login Behavior and Security** section to modify your login policy. Here, ensure you enable the option for **External IDP Allowed**.
|
||||
|
||||

|
||||
|
||||
### Configuring IdP Providers
|
||||
|
||||
Access the settings page of your instance or the specific organization and select **Identity Providers**.
|
||||
|
||||
The ZITADEL Management Console will display a list of all the IdPs you've configured, along with available provider templates. Selecting any listed IdP will guide you through the process of configuring that specific Identity Provider.
|
||||
|
||||

|
||||
|
||||
## Available guides
|
||||
|
||||
In the guides below, some of which utilize the Generic OIDC or SAML templates for configuration, you'll learn how to configure and set up your preferred external Identity Provider (IdP) in ZITADEL.
|
||||
|
||||
- [Google](./google)
|
||||
- [Entra ID (OIDC)](./azure-ad-oidc)
|
||||
- [Entra ID SAML](./azure-ad-saml)
|
||||
- [GitHub](./github)
|
||||
- [GitLab](./gitlab)
|
||||
- [Apple](./apple)
|
||||
- [LDAP](./ldap)
|
||||
- [Local OpenLDAP](./openldap.mdx)
|
||||
- [OKTA generic OIDC](./okta-oidc)
|
||||
- [OKTA SAML](./okta_saml)
|
||||
- [Keycloak generic OIDC](./keycloak)
|
||||
- [MockSAML](./mocksaml)
|
||||
- [JWT IdP](./jwt_idp)
|
||||
|
||||
### Configuring IdPs without predefined templates
|
||||
|
||||
If ZITADEL doesn't offer a specific template for your Identity Provider (IdP) and your IdP is fully compliant with OpenID Connect (OIDC), you have the option to use the generic OIDC provider configuration.
|
||||
|
||||
For those utilizing a SAML Service Provider, the SAML Service Provider option is available. You can learn how to set up a SAML Service Provider with our [MockSAML example](/guides/integrate/identity-providers/mocksaml).
|
||||
|
||||
Should you wish to transition from a generic OIDC provider to Entra ID (formerly Azure Active Directory) or Google, consider following this [guide](/guides/integrate/identity-providers/migrate).
|
||||
|
||||
## Key settings on the templates
|
||||
|
||||
When configuring external IdP templates in ZITADEL, several common settings enable customized integration to suit your application's authentication flow. Below is a generic explanation of these settings:
|
||||
|
||||
- **Scopes**: Specifies the permissions your application requests from the user's account on the external IdP. Common scopes include `openid`, `profile`, and `email`, essential for accessing basic user information for authentication and account management in ZITADEL. You can specify additional scopes based on your application's requirements and the information needed from the external IdP.
|
||||
|
||||
- **Automatic creation**: When enabled, this allows ZITADEL to automatically create a new user account if someone logs in with their external IdP credentials and no corresponding account exists in ZITADEL. This facilitates a smooth user onboarding experience by eliminating the need for manual account creation.
|
||||
|
||||
- **Automatic update**: This feature, when activated, allows ZITADEL to automatically update a user's profile information whenever changes are detected in the user's account on the external IdP. For example, if a user changes their last name in their Google or Microsoft account, ZITADEL will reflect this update in the user's account upon their next login.
|
||||
|
||||
- **Account creation allowed (manually)**: Determines whether new user accounts can be created in ZITADEL through the external IdP authentication process. Enabling this setting is crucial for allowing users who are new to your application to register and create accounts seamlessly via their existing external IdP accounts. However, if you rely on the **automatic creation** and want to prevent users to manually create their accounts or edit information during the automatic process, you need to disable this option.
|
||||
|
||||
- **Account linking allowed (manually)**: Enables existing ZITADEL accounts to be linked with identities from external IdPs. It requires that a linkable ZITADEL account already exists for the user attempting to log in with an external IdP. Account linking is beneficial for users who wish to associate multiple login methods with their ZITADEL account, providing flexibility and convenience in how they access your application. However, if you rely on an **automatic linking option** and want to prevent users to manually link their accounts, you need to disable this option.
|
||||
|
||||
- **Automatic linking options**: Enables existing ZITADEL accounts to be linked with identities from external IdPs. If not disabled, ZITADEL will check for an existing account with the configured criteria (username or email) and prompt the user to link the account.
|
||||
|
||||
## Configure external IdPs at the organization level or on the default settings
|
||||
|
||||
Deciding whether to configure an external Identity Provider (IdP) at the organization level or in the default settings in ZITADEL depends on the scope of access and management you intend to provide. Here’s when to choose each option:
|
||||
|
||||
### Create an external IdP on an organization
|
||||
|
||||
- **Targeted access control**: When you want to allow authentication through the external IdP specifically for users of a particular organization. This is useful for businesses that manage multiple organizations within ZITADEL and require distinct authentication strategies for each.
|
||||
|
||||
- **Customized authentication flow**: If different organizations have unique requirements or policies around user authentication, configuring an IdP at the organization level allows for customized authentication flows that cater to the specific needs of each organization.
|
||||
|
||||
- **Delegated administration**: Enabling organizations to manage their own IdPs empowers them to administer their authentication mechanisms independently. This is beneficial in scenarios where organizations have the autonomy to choose their preferred IdPs or when they manage their user base directly.
|
||||
|
||||
### Create an external IdP as default
|
||||
|
||||
- **Unified authentication strategy**: When you aim to provide a consistent authentication experience across all organizations within your ZITADEL instance. Configuring an IdP in the default settings applies the same authentication mechanism universally, simplifying management and user experience.
|
||||
|
||||
- **Centralized management**: Setting up an IdP in the default settings is ideal for scenarios where a single administrative body oversees user authentication across all organizations. This approach centralizes the management of external IdPs, making it easier to maintain and update authentication policies.
|
||||
|
||||
- **Broad access needs**: If all users, regardless of their organization, require access to external IdPs for authentication, configuring the IdP in the default settings ensures that these options are available universally. This is particularly useful for platforms that serve a wide range of users with common access requirements.
|
||||
|
||||
## References
|
||||
|
||||
- [Identity brokering in ZITADEL](/concepts/features/identity-brokering)
|
||||
- [The ZITADEL API reference for managing external IdPs](/reference/api/admin)
|
||||
- [Handle external logins in a custom login UI](/guides/integrate/login-ui/external-login)
|
||||
@@ -0,0 +1,161 @@
|
||||
---
|
||||
title: JWT IdP
|
||||
sidebar_label: JWT IdP
|
||||
---
|
||||
|
||||
## In simple terms
|
||||
|
||||
A **JWT Identity Provider (JWT IdP)** allows ZITADEL to accept a JSON Web Token (JWT) issued and signed by an external system as proof that a user has already been authenticated elsewhere. In this flow, ZITADEL does not perform authentication itself, but relies on the trustworthiness and validity of the provided JWT.
|
||||
|
||||
## When should I use JWT IdP?
|
||||
|
||||
Use JWT IdP if:
|
||||
- You have an existing application or Web Application Firewall (WAF) that authenticates users and is able to generate a JWT for them.
|
||||
- You want users to access new applications via ZITADEL without re-authentication, effectively reusing an existing session.
|
||||
- You want to enable silent single sign-on (SSO) between legacy and new apps.
|
||||
- You wish to federate authentication with a system that can't act as a full OpenID Connect provider, but can issue JWTs.
|
||||
|
||||
Do **not** use JWT IdP if:
|
||||
- You need ZITADEL to interactively authenticate users (e.g., password-based logins).
|
||||
- There is no secure way to transfer or validate the JWT.
|
||||
|
||||
---
|
||||
|
||||
## Configuring a JWT as an Identity Provider in ZITADEL
|
||||
|
||||
Configuring JWT IdP enables ZITADEL to accept a JWT generated by an external authentication system, such as your WAF or a legacy app. The typical setup involves obtaining the JWT from the user's previously established session.
|
||||
|
||||
To configure JWT IdP in ZITADEL, you need to provide:
|
||||
- The endpoint to obtain the JWT.
|
||||
- Information ZITADEL requires to validate the JWT, including issuer, signature keys, and which HTTP header carries the JWT.
|
||||
|
||||
---
|
||||
|
||||
## Authentication using JWT IdP
|
||||
|
||||
The authentication flow with JWT IdP looks like this:
|
||||
|
||||

|
||||
|
||||
**Step-by-Step Process**
|
||||
|
||||
1. **User authenticates in the existing app (Server-side & Browser):**
|
||||
- The user logs in to the current application, with authentication managed (often) by a WAF or legacy system.
|
||||
- The WAF or app creates a session and can issue a JWT representing that session.
|
||||
|
||||
2. **User accesses new app (Browser):**
|
||||
- The user visits the new application, possibly via a link from the existing app.
|
||||
- If no session is found, the new app initiates an OIDC login via ZITADEL.
|
||||
- The user either selects the JWT IdP in the ZITADEL UI,
|
||||
- **or** the application uses a [custom scope](/apis/openidoauth/scopes#reserved-scopes) to pre-select the JWT IdP in the OIDC Authorization Request.
|
||||
|
||||
3. **ZITADEL redirects to the JWT Endpoint (Browser):**
|
||||
- ZITADEL redirects the user's browser to the configured JWT Endpoint (usually behind the WAF).
|
||||
|
||||
- **Purpose:**
|
||||
Redirecting the browser ensures that any existing session cookies for the previous app/WAF are available, letting the WAF determine the authenticated user and issue the appropriate JWT.
|
||||
|
||||
4. **WAF/session gateway attaches JWT and proxies request to ZITADEL (Server-side):**
|
||||
- The JWT Endpoint (behind the WAF) uses the session (from browser cookies) to ascertain the authenticated user.
|
||||
- The WAF/server injects the JWT into a specific HTTP header (never as a URL parameter) and forwards (proxies) the user’s request with **all original query parameters intact** to ZITADEL’s JWT receiving endpoint.
|
||||
- This preserves critical OIDC flow state.
|
||||
|
||||
- **How to proxy the request (example):**
|
||||
The example below shows a simplified "serverless/WAF proxy" approach to:
|
||||
- obtain/generate the JWT,
|
||||
- forward all the user's query params,
|
||||
- and place the JWT in the appropriate HTTP header when proxying to ZITADEL.
|
||||
|
||||
```js
|
||||
export default {
|
||||
async fetch(request, env, ctx) {
|
||||
// 1. Obtain the JWT for the current session (implementation will vary)
|
||||
const jwt = await getJwtForCurrentSession(request, env);
|
||||
|
||||
// 2. Prepare the ZITADEL endpoint URL and copy all query params
|
||||
const userUrl = new URL(request.url);
|
||||
// Important: The ZITADEL_JWT_IDP_ENDPOINT should be your ZITADEL custom domain plus "/idps/jwt"
|
||||
// For example: https://accounts.test.com/idps/jwt
|
||||
const zitadelUrl = new URL(env.ZITADEL_JWT_IDP_ENDPOINT);
|
||||
userUrl.searchParams.forEach((v, k) => zitadelUrl.searchParams.set(k, v));
|
||||
|
||||
// 3. Proxy request, attaching JWT in the configured HTTP header
|
||||
const zitadelReq = new Request(zitadelUrl.toString(), {
|
||||
method: "GET",
|
||||
headers: {
|
||||
"x-custom-tkn": jwt, // Use header name as set in ZITADEL JWT IdP settings
|
||||
"Accept": request.headers.get("Accept") || "*/*",
|
||||
},
|
||||
redirect: "manual",
|
||||
});
|
||||
|
||||
// 4. Send to ZITADEL and relay its response to the browser
|
||||
const zitadelResp = await fetch(zitadelReq);
|
||||
return new Response(zitadelResp.body, {
|
||||
status: zitadelResp.status,
|
||||
headers: zitadelResp.headers,
|
||||
});
|
||||
}
|
||||
}
|
||||
```
|
||||
*(Replace `getJwtForCurrentSession` with your logic for retrieving/creating a JWT from the user's WAF session.
|
||||
Note: `env.ZITADEL_JWT_IDP_ENDPOINT` should be set to the custom domain of your ZITADEL instance
|
||||
with the `/idps/jwt` path, e.g. `https://accounts.test.com/idps/jwt`.)*
|
||||
|
||||
5. **ZITADEL receives and validates the JWT (Server-side):**
|
||||
- ZITADEL extracts the JWT from the configured HTTP header.
|
||||
- ZITADEL verifies that:
|
||||
- The **signature** matches using keys from the Keys Endpoint.
|
||||
- The `issuer` (`iss` claim) matches the configured issuer.
|
||||
- The JWT is **not expired**.
|
||||
- **Note:**
|
||||
- ZITADEL **does not** re-authenticate the user.
|
||||
- ZITADEL **does not** issue this JWT.
|
||||
- ZITADEL only verifies authenticity and validity.
|
||||
- The JWT is treated as an external ID token, similar to third-party IdPs.
|
||||
|
||||
6. **Login completes (Browser):**
|
||||
- ZITADEL finishes the OIDC flow.
|
||||
- The browser is redirected to the application’s callback endpoint.
|
||||
- The app exchanges the code for tokens, and the user is now logged in—without extra authentication steps.
|
||||
|
||||
---
|
||||
|
||||
## Terms and Example Values
|
||||
|
||||
Here’s a reference integration scenario:
|
||||
|
||||
- **Existing Application:** `apps.test.com/existing/`
|
||||
- **New Application:** `new.test.com`
|
||||
- **ZITADEL Login UI:** `accounts.test.com`
|
||||
|
||||
Sample **JWT IdP Configuration**:
|
||||
|
||||
- **JWT Endpoint:**
|
||||
Where ZITADEL redirects users to retrieve the JWT:
|
||||
`https://apps.test.com/existing/auth-new`
|
||||
|
||||
- **Issuer:**
|
||||
The `iss` claim ZITADEL expects in the JWT:
|
||||
`https://issuer.test.internal`
|
||||
|
||||
- **Keys Endpoint:**
|
||||
Where ZITADEL fetches public keys for signature verification:
|
||||
`https://issuer.test.internal/keys`
|
||||
|
||||
- **Header Name:**
|
||||
The HTTP header delivering the JWT (defaults to `Authorization` if not set):
|
||||
`x-custom-tkn`
|
||||
|
||||
**Clarifications and Best Practices:**
|
||||
- **Why must the JWT Endpoint be on the same domain as the existing app?**
|
||||
This ensures browser sessions (cookies) are correctly sent and recognized by the WAF or app, so the right JWT can be generated.
|
||||
- **Why are cookies sent automatically?**
|
||||
Browsers automatically include relevant cookies when redirecting within the same domain, enabling server-side authentication seamlessly.
|
||||
- **Why send the JWT in a header, not as a parameter?**
|
||||
HTTP headers are more secure for transmitting sensitive tokens, prevent them from being exposed in URLs or logs, and avoid user tampering.
|
||||
|
||||
When ZITADEL performs signature validation, it uses the Keys Endpoint to:
|
||||
- Verify the JWT’s signature
|
||||
- Check the issuer matches the JWT IdP configuration
|
||||
- Ensure the JWT is not expired
|
||||
@@ -0,0 +1,76 @@
|
||||
---
|
||||
title: Configure Keycloak as an Identity Provider in ZITADEL
|
||||
sidebar_label: Keycloak generic OIDC
|
||||
id: keycloak
|
||||
---
|
||||
|
||||
import GeneralConfigDescription from './_general_config_description.mdx';
|
||||
import Intro from './_intro.mdx';
|
||||
import CustomLoginPolicy from './_custom_login_policy.mdx';
|
||||
import IDPsOverview from './_idps_overview.mdx';
|
||||
import Activate from './_activate.mdx';
|
||||
import TestSetup from './_test_setup.mdx';
|
||||
|
||||
<Intro components={props.components} provider="Keycloak"/>
|
||||
|
||||
## Open the Generic OIDC Provider Template
|
||||
|
||||
<IDPsOverview components={props.components} templates="Generic OIDC"/>
|
||||
|
||||
Click on the ZITADEL Callback URL to copy it to your clipboard.
|
||||
You will have to paste it in the Keycloak Client later.
|
||||
|
||||

|
||||
|
||||
## Keycloak Configuration
|
||||
|
||||
### Register a new client
|
||||
|
||||
1. Login to your Keycloak account and go to the clients list: `$KEYCLOAK-DOMAIN/auth/admin/$REALM/console/#/$REALM/clients`
|
||||
2. Click on "Create Client"
|
||||
3. Choose OpenID Connect as Client Type and give your client an ID
|
||||
4. Enable Client authentication and the standard flow and direct access grants as authentication flow
|
||||
5. [Paste the ZITADEL Callback URL you copied before](#open-the-generic-oidc-provider-template) to the redirect URIs
|
||||
6. Go to the credentials tab and copy the secret
|
||||
|
||||

|
||||

|
||||
|
||||
## ZITADEL configuration
|
||||
|
||||
1. Go back [to the Generic OIDC Provider template you opened before in ZITADEL](#open-the-generic-oidc-provider-template).
|
||||
2. Add the [client ID and secret created before on your Keycloak Client](#register-a-new-client).
|
||||
3. Give the provider a name, e.g. Keycloak. This name will be displayed on the login screen button.
|
||||
4. Add the issuer URL of your Keycloak realm with the path /auth/realms/$REALM, e.g. `https://lemur-0.cloud-iam.com/auth/realms/acme`
|
||||
|
||||
You can optionally configure the following settings.
|
||||
A useful default will be filled if you don't change anything.
|
||||
|
||||
**Scopes**: The scopes define which scopes will be sent to the provider, `openid`, `profile`, and `email` are prefilled.
|
||||
This information will be taken to create/update the user within ZITADEL.
|
||||
ZITADEL ensures that at least the `openid`-scope is always sent.
|
||||
|
||||
**Use PKCE**: If enabled, the provider will use Proof Key for Code Exchange (PKCE) to secure the authorization code flow
|
||||
in addition to the client secret.
|
||||
|
||||
<GeneralConfigDescription components={props.components} provider_account="Keycloak account" />
|
||||
|
||||

|
||||
|
||||
### Activate IdP
|
||||
|
||||
<Activate components={props.components} />
|
||||
|
||||

|
||||
|
||||
### Ensure your Login Policy allows External IDPs
|
||||
|
||||
<CustomLoginPolicy components={props.components} />
|
||||
|
||||
## Test the setup
|
||||
|
||||
<TestSetup components={props.components} loginscreen="your Keycloak login"/>
|
||||
|
||||

|
||||
|
||||

|
||||
@@ -0,0 +1,76 @@
|
||||
---
|
||||
title: Configure LDAP as an Identity Provider in ZITADEL
|
||||
sidebar_label: LDAP
|
||||
---
|
||||
|
||||
import Intro from './_intro.mdx';
|
||||
import CustomLoginPolicy from './_custom_login_policy.mdx';
|
||||
import IDPsOverview from './_idps_overview.mdx';
|
||||
import GeneralConfigDescription from './_general_config_description.mdx';
|
||||
import Activate from './_activate.mdx';
|
||||
import TestSetup from './_test_setup.mdx';
|
||||
|
||||
import HowLDAPIDPWorks from './_how_ldap_idp_works.mdx'
|
||||
|
||||
<Intro components={props.components} provider="an LDAP server"/>
|
||||
|
||||
## How it works
|
||||
|
||||
<HowLDAPIDPWorks components={props.components} />
|
||||
|
||||
## ZITADEL Configuration
|
||||
|
||||
### Go to the IdP Providers Overview
|
||||
|
||||
<IDPsOverview components={props.components} templates="Active Directory / LDAP"/>
|
||||
|
||||
### Create a new LDAP Provider
|
||||
|
||||
Fill in the following fields in the LDAP template.
|
||||
|
||||
<Callout type="warn">
|
||||
We highly recommend to use LDAPS or StartTLS enable servers.
|
||||
Otherwise, your users passwords are sent in clear text through the wire.
|
||||
</Callout>
|
||||
|
||||
**Name**: Name of the identity provider
|
||||
|
||||
**Servers**: List of servers in a format of "schema://host:port", as example "ldap://localhost:389". If possible, replace "ldap" with "ldaps" with the corresponding port.
|
||||
|
||||
**BaseDN**: BaseDN which will be used with each request to the LDAP server
|
||||
|
||||
**BindDn** and **BindPassword**: BindDN and password used to connect to the LDAP for the SearchQuery, should be an admin or user with enough permissions to search for the users to login.
|
||||
|
||||
**Userbase**: Base used for the user, normally "dn" but can also be configured.
|
||||
|
||||
**User filters**: Attributes of the user which are "or"-joined in the query for the user, used value is the input of the loginname, for example if you try to login with [email protected] and filters "uid" and "email" the resulting SearchQuery contains "(|([email protected])([email protected]))"
|
||||
|
||||
**User Object Classes**: ObjectClasses which are "and"-joined in the SearchQuery and the user has to have in the LDAP.
|
||||
|
||||
**LDAP Attributes**: Mapping of LDAP attributes to ZITADEL attributes, the ID attributes is required, the rest depends on usage of the identity provider
|
||||
|
||||
**StartTLS**: If this setting is enabled after the initial connection ZITADEL tries to build a TLS connection. If your LDAP server doesn't support LDAPS, at least it should support StartTLS.
|
||||
|
||||
**Timeout**: If this setting is set all connection run with a set timeout, if it is 0s the default timeout of 60s is used.
|
||||
|
||||
<GeneralConfigDescription components={props.components} provider_account="LDAP user" />
|
||||
|
||||

|
||||
|
||||
### Activate IdP
|
||||
|
||||
<Activate components={props.components} />
|
||||
|
||||

|
||||
|
||||
### Ensure your Login Policy allows External IDPs
|
||||
|
||||
<CustomLoginPolicy components={props.components} />
|
||||
|
||||
## Test the setup
|
||||
|
||||
<TestSetup components={props.components} loginscreen="ZITADELs LDAP login"/>
|
||||
|
||||

|
||||
|
||||

|
||||
@@ -0,0 +1,82 @@
|
||||
---
|
||||
title: Configure LinkedIn as an OAuth Identity Provider in ZITADEL
|
||||
sidebar_label: LinkedIn generic OAuth
|
||||
id: linkedin-oauth
|
||||
---
|
||||
|
||||
import GeneralConfigDescription from './_general_config_description.mdx';
|
||||
import Intro from './_intro.mdx';
|
||||
import CustomLoginPolicy from './_custom_login_policy.mdx';
|
||||
import IDPsOverview from './_idps_overview.mdx';
|
||||
import GenericOAuth from './_generic_oauth.mdx';
|
||||
import Activate from './_activate.mdx';
|
||||
import PrefillAction from './_prefill_action.mdx';
|
||||
import TestSetup from './_test_setup.mdx';
|
||||
|
||||
<Intro components={props.components} provider="LinkedIn"/>
|
||||
|
||||
## LinkedIn Configuration
|
||||
|
||||
### Register a new client
|
||||
|
||||
1. Go to the LinkedIn Developer console and create a new App: https://www.linkedin.com/developers/apps/new
|
||||
2. Add your App Name, your Company Page and a Logo
|
||||
3. Add "Sign In with LinkedIn using OpenID Connect" by clicking "Request access"
|
||||
4. Go to the Auth Settings of the App and add the following URL to the "Authorized redirect URLs"
|
||||
- Login V1: `${CUSTOM_DOMAIN}/ui/login/login/externalidp/callback`
|
||||
- Example redirect url for the domain `https://acme.zitadel.cloud` would look like this: `https://acme.zitadel.cloud/ui/login/login/externalidp/callback`
|
||||
- Login V2: `${LOGINGV2_DOMAIN}/idps/callback`
|
||||
- In this case the url would look like this: `https://acme.zitadel.cloud/idps/callback`
|
||||
5. Verify the app as your company
|
||||
6. In the Auth - OAuth 2.0 scopes section you should see `openid`, `profile` and `email` listed
|
||||
7. Save Client ID and Primary Client Secret from the Application credentials
|
||||
|
||||

|
||||
|
||||
## ZITADEL Configuration
|
||||
|
||||
### Add custom login policy
|
||||
|
||||
<CustomLoginPolicy components={props.components} />
|
||||
|
||||
### Go to the IdP Providers Overview
|
||||
|
||||
<IDPsOverview components={props.components} templates="Generic OAuth"/>
|
||||
|
||||
### Create a new Generic OAuth Provider
|
||||
|
||||
<GenericOAuth components={props.components}
|
||||
name=": e.g. LinkedIn"
|
||||
authendpoint="https://www.linkedin.com/oauth/v2/authorization"
|
||||
tokenendpoint="https://www.linkedin.com/oauth/v2/accessToken"
|
||||
userendpoint="https://api.linkedin.com/v2/userinfo"
|
||||
id="sub"
|
||||
clientid=": Client id from the application previously created in your LinkedIn account"
|
||||
clientsecret=": Client Secret from the application previously created in your LinkedIn account"
|
||||
/>
|
||||
|
||||
<GeneralConfigDescription components={props.components} provider_account="LinkedIn account" />
|
||||
|
||||

|
||||
|
||||
### Activate IdP
|
||||
|
||||
<Activate components={props.components} />
|
||||
|
||||

|
||||
|
||||
## Test the setup
|
||||
|
||||
<TestSetup components={props.components} loginscreen="your LinkedIn login"/>
|
||||
|
||||

|
||||
|
||||

|
||||
|
||||
## Optional: Add ZITADEL action to autofill userdata
|
||||
|
||||
<PrefillAction components={props.components} fields="firstname, lastname, username, email and email verified" provider="LinkedIn"/>
|
||||
|
||||
```js reference
|
||||
https://github.com/zitadel/actions/blob/main/examples/linkedin_identity_provider.js
|
||||
```
|
||||
@@ -0,0 +1,59 @@
|
||||
---
|
||||
title: Migrate from Generic Provider to specific Identity Provider
|
||||
sidebar_label: Migrate IdP
|
||||
---
|
||||
|
||||
## Migrate Generic OIDC Provider
|
||||
|
||||
You can migrate from a generic OIDC provider to the following supported templates:
|
||||
|
||||
- Entra ID (former Azure Active Directory)
|
||||
- Google
|
||||
|
||||
To migrate, you either use the [Migrate Generic OIDC Identity Provider (Instance)](/reference/api/admin/zitadel.admin.v1.AdminService.MigrateGenericOIDCProvider) or [Migrate Generic OIDC Identity Provider (Organization)](/reference/api/management/zitadel.management.v1.ManagementService.MigrateGenericOIDCProvider) API request.
|
||||
These calls change the type of the provider and don't delete any linked users.
|
||||
|
||||
<Callout title="Linked users will not notice the change and be able to login as usual.">
|
||||
</Callout>
|
||||
|
||||
### Google Configuration
|
||||
|
||||
The available configuration is described in [Google Configuration](./google).
|
||||
|
||||
### Entra ID Configuration
|
||||
|
||||
The available configuration is described in [Entra ID Configuration](./azure-ad-oidc).
|
||||
|
||||
## Migrate with Terraform
|
||||
|
||||
Please note that you only have to perform this migration if you already have an existing IDP with linked users, that should not loose the connection to the provider.
|
||||
If that isn't your case please just add a new provider from scratch.
|
||||
To migrate to a specific provider, you need to follow a few essential steps:
|
||||
1. Create a desired IDP as Terraform resource for example [Google](https://registry.terraform.io/providers/zitadel/zitadel/latest/docs/resources/idp_google).
|
||||
2. Remove the old terraform resource from the state as to not destroy the migrated IDP accidentally.
|
||||
```bash
|
||||
# terraform state rm *address*
|
||||
terraform state rm zitadel_idp_oidc.oidc_idp
|
||||
```
|
||||
|
||||
After this command you can also remove the resource from the terraform files, as it is not managed anymore but also not deleted.
|
||||
|
||||
3. Make the corresponding API call to [migrate the IDP](./migrate#migrate-generic-oidc-provider), save the ID of the IDP for the import
|
||||
4. Before applying the Terraform resources again, import the new IDP resource.
|
||||
```bash
|
||||
#resource "zitadel_idp_google" "google" {
|
||||
# name = "Google"
|
||||
# client_id = "182902..."
|
||||
# client_secret = "GOCSPX-*****"
|
||||
# scopes = ["openid", "profile", "email"]
|
||||
# is_linking_allowed = false
|
||||
# is_creation_allowed = true
|
||||
# is_auto_creation = false
|
||||
# is_auto_update = true
|
||||
#}
|
||||
|
||||
# terraform import zitadel_idp_google.*resource_name* *id*:*client_secret*
|
||||
terraform import zitadel_idp_google.google 222302827723096428:GOCSPX-*****
|
||||
```
|
||||
|
||||
You have now migrated your provider and you should be able to apply the resource again. There should be no changes and the IDP is maintained by Terraform again.
|
||||
@@ -0,0 +1,274 @@
|
||||
---
|
||||
title: Configure MockSAML as an Identity Provider in ZITADEL
|
||||
sidebar_label: MockSAML
|
||||
id: mocksaml
|
||||
---
|
||||
|
||||
import GeneralConfigDescription from './_general_config_description.mdx';
|
||||
import Intro from './_intro.mdx';
|
||||
import CustomLoginPolicy from './_custom_login_policy.mdx';
|
||||
import IDPsOverview from './_idps_overview.mdx';
|
||||
import Activate from './_activate.mdx';
|
||||
import TestSetup from './_test_setup.mdx';
|
||||
import PrefillAction from './_prefill_action.mdx';
|
||||
|
||||
<Intro components={props.components} provider="MockSAML"/>
|
||||
|
||||
<Callout type="warn">
|
||||
MockSAML is not intended for any production environment, only for test purposes
|
||||
</Callout>
|
||||
|
||||
## MockSAML
|
||||
|
||||
### Download metadata
|
||||
|
||||
You can either download the metadata under [https://mocksaml.com/api/saml/metadata?download=true](https://mocksaml.com/api/saml/metadata?download=true) or skip this step and
|
||||
fill in the URL when creating the SAML Provider in ZITADEL.
|
||||
|
||||
## ZITADEL configuration
|
||||
|
||||
### Go to the IdP providers overview
|
||||
|
||||
<IDPsOverview components={props.components} templates="SAML"/>
|
||||
|
||||
### Create a new SAML ServiceProvider
|
||||
|
||||
The SAML provider template has everything you need preconfigured.
|
||||
Add the metadata.xml or the URL to the metadata which are accessible by you ZITADEL instance.
|
||||
All the necessary configuration is contained in the metadata which has to be exchanged by the ServiceProvider and the IdentityProvider.
|
||||
|
||||
<GeneralConfigDescription components={props.components} provider_account="SAML account" />
|
||||
|
||||

|
||||
|
||||
### Download metadata
|
||||
|
||||
Normally, you would need to download the ServiceProvider metadata from ZITADEL to upload to the IdentityProvider.
|
||||
They are available under `https://${CUSTOMDOMAIN}/idps/\{ID of the provider in ZITADEL}/saml/metadata`, but this step can be skipped due to the fact that MockSAML is only for testing purposes.
|
||||
|
||||
### Activate IdP
|
||||
|
||||
<Activate components={props.components} />
|
||||
|
||||

|
||||
|
||||
### Ensure your Login Policy allows External IDPs
|
||||
|
||||
<CustomLoginPolicy components={props.components} />
|
||||
|
||||
## Configure an action to autofill user data
|
||||
|
||||
### Required for Login V2
|
||||
The creation of users in ZITADEL will fail if the required fields to create a user are not set.
|
||||
|
||||
**Actions V2** can be used to map the SAML attributes returned by the IDP to the required fields in ZITADEL.
|
||||
See the [Actions V2 Response Manipulation](/guides/integrate/actions/testing-response-manipulation)
|
||||
guide for more information on setting up a Target and an Execution. In short,
|
||||
* Create an Actions V2 Target of type `REST Call`
|
||||
* Create an Execution of type `Response` on the method `/zitadel.user.v2.UserService/RetrieveIdentityProviderIntent`
|
||||
|
||||
The following minimal example modifies the response of `/zitadel.user.v2.UserService/RetrieveIdentityProviderIntent` to set the required fields
|
||||
for user creation. This example is specific to MockSAML, please adjust the attributes according to your IDP.
|
||||
|
||||
``` go
|
||||
package main
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"io"
|
||||
"log"
|
||||
"net/http"
|
||||
|
||||
"github.com/muhlemmer/gu"
|
||||
"github.com/zitadel/zitadel-go/v3/pkg/client/zitadel/user/v2"
|
||||
"google.golang.org/protobuf/encoding/protojson"
|
||||
)
|
||||
|
||||
type contextResponse struct {
|
||||
Request *retrieveIdentityProviderIntentRequestWrapper `json:"request"`
|
||||
Response *retrieveIdentityProviderIntentResponseWrapper `json:"response"`
|
||||
}
|
||||
|
||||
// RetrieveIdentityProviderIntentRequestWrapper necessary to marshal and unmarshal the JSON into the proto message correctly
|
||||
type retrieveIdentityProviderIntentRequestWrapper struct {
|
||||
user.RetrieveIdentityProviderIntentRequest
|
||||
}
|
||||
|
||||
func (r *retrieveIdentityProviderIntentRequestWrapper) MarshalJSON() ([]byte, error) {
|
||||
data, err := protojson.Marshal(r)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return data, nil
|
||||
}
|
||||
|
||||
func (r *retrieveIdentityProviderIntentRequestWrapper) UnmarshalJSON(data []byte) error {
|
||||
return protojson.Unmarshal(data, r)
|
||||
}
|
||||
|
||||
// RetrieveIdentityProviderIntentResponseWrapper necessary to marshal and unmarshal the JSON into the proto message correctly
|
||||
type retrieveIdentityProviderIntentResponseWrapper struct {
|
||||
user.RetrieveIdentityProviderIntentResponse
|
||||
}
|
||||
|
||||
func (r *retrieveIdentityProviderIntentResponseWrapper) MarshalJSON() ([]byte, error) {
|
||||
data, err := protojson.Marshal(r)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return data, nil
|
||||
}
|
||||
|
||||
func (r *retrieveIdentityProviderIntentResponseWrapper) UnmarshalJSON(data []byte) error {
|
||||
return protojson.Unmarshal(data, r)
|
||||
}
|
||||
|
||||
// call HandleFunc to read the response body, manipulate the content and return the response
|
||||
func call(w http.ResponseWriter, req *http.Request) {
|
||||
// read the body content
|
||||
sentBody, err := io.ReadAll(req.Body)
|
||||
if err != nil {
|
||||
// if there was an error while reading the body return an error
|
||||
http.Error(w, "error", http.StatusInternalServerError)
|
||||
return
|
||||
}
|
||||
defer req.Body.Close()
|
||||
|
||||
// read the response into the expected structure
|
||||
request := new(contextResponse)
|
||||
if err := json.Unmarshal(sentBody, request); err != nil {
|
||||
http.Error(w, "error", http.StatusInternalServerError)
|
||||
return
|
||||
}
|
||||
|
||||
// build the response from the received response
|
||||
resp := request.Response
|
||||
// manipulate the received response to send back as response
|
||||
if err = manipulateResponse(resp); err != nil {
|
||||
http.Error(w, "error modifying response", http.StatusInternalServerError)
|
||||
return
|
||||
}
|
||||
|
||||
// marshal the response into json
|
||||
data, err := json.Marshal(resp)
|
||||
if err != nil {
|
||||
// if there was an error while marshalling the json
|
||||
http.Error(w, "error marshaling response", http.StatusInternalServerError)
|
||||
return
|
||||
}
|
||||
|
||||
// return the manipulated response
|
||||
w.Write(data)
|
||||
}
|
||||
|
||||
type rawInformation struct {
|
||||
Attributes struct {
|
||||
Email []string `json:"email"`
|
||||
FirstName []string `json:"firstName"`
|
||||
Id []string `json:"id"`
|
||||
LastName []string `json:"lastName"`
|
||||
} `json:"attributes"`
|
||||
Id string `json:"id"`
|
||||
}
|
||||
|
||||
func manipulateResponse(resp *retrieveIdentityProviderIntentResponseWrapper) error {
|
||||
if resp == nil || resp.IdpInformation == nil || resp.IdpInformation.RawInformation == nil {
|
||||
log.Println("missing IDP/User information in the IDP response")
|
||||
return nil
|
||||
}
|
||||
// retrieve raw information from the IDP
|
||||
var rawInfoBytes []byte
|
||||
var err error
|
||||
if rawInfoBytes, err = resp.IdpInformation.RawInformation.MarshalJSON(); err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
// NOTE: the raw information struct used here is specific to MockSAML.
|
||||
// Please adapt this to your IDP.
|
||||
var rawInfo rawInformation
|
||||
if err = json.Unmarshal(rawInfoBytes, &rawInfo); err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
if len(rawInfo.Attributes.Email) == 0 ||
|
||||
len(rawInfo.Attributes.FirstName) == 0 ||
|
||||
len(rawInfo.Attributes.LastName) == 0 {
|
||||
log.Println("missing required attributes in the IDP response")
|
||||
return nil
|
||||
}
|
||||
|
||||
// to create a new user.
|
||||
if resp.AddHumanUser != nil {
|
||||
// set the required fields to create a new user in Zitadel based on the information returned by the IDP
|
||||
username := rawInfo.Attributes.Email[0]
|
||||
resp.IdpInformation.UserName = username
|
||||
|
||||
resp.AddHumanUser.Profile = &user.SetHumanProfile{
|
||||
GivenName: rawInfo.Attributes.FirstName[0],
|
||||
FamilyName: rawInfo.Attributes.LastName[0],
|
||||
}
|
||||
resp.AddHumanUser.Email = &user.SetHumanEmail{
|
||||
Email: rawInfo.Attributes.Email[0],
|
||||
Verification: &user.SetHumanEmail_IsVerified{IsVerified: true},
|
||||
}
|
||||
resp.AddHumanUser.Username = gu.Ptr(username)
|
||||
resp.AddHumanUser.IdpLinks = []*user.IDPLink{
|
||||
{
|
||||
UserName: username,
|
||||
UserId: resp.GetIdpInformation().GetUserId(),
|
||||
IdpId: resp.GetIdpInformation().GetIdpId(),
|
||||
},
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func main() {
|
||||
// handle the HTTP call under "/call"
|
||||
http.HandleFunc("/call", call)
|
||||
|
||||
// start an HTTP server with the before defined function to handle the endpoint under "http://localhost:8090"
|
||||
http.ListenAndServe(":8090", nil)
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
### Optional for Login V1 (using Actions V1)
|
||||
|
||||
<PrefillAction components={props.components} fields="firstname, lastname, email, display name and username" provider="mockSaml"/>
|
||||
|
||||
NOTE: The name of the action should be the same as the function name. In this example, the action should be named `mapSAMLIDPAttrs`
|
||||
|
||||
```js
|
||||
function mapSAMLIDPAttrs(ctx, api) {
|
||||
if (ctx.v1.externalUser.externalIdpId != "external-idp-id") {
|
||||
return
|
||||
}
|
||||
// the attribute names below represent the ones used by MockSAML, please adjust accordingly for your IDP.
|
||||
let firstname = ctx.v1.providerInfo.attributes["firstName"];
|
||||
let lastname = ctx.v1.providerInfo.attributes["lastName"];
|
||||
let email = ctx.v1.providerInfo.attributes["email"];
|
||||
let username = ctx.v1.providerInfo.attributes["email"];
|
||||
if (firstname != undefined) {
|
||||
api.setFirstName(firstname[0]);
|
||||
}
|
||||
if (lastname != undefined) {
|
||||
api.setLastName(lastname[0]);
|
||||
}
|
||||
if (email != undefined) {
|
||||
api.setEmail(email[0]);
|
||||
api.setEmailVerified(true);
|
||||
}
|
||||
if (username != undefined) {
|
||||
api.setPreferredUsername(username[0]);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Test the setup
|
||||
|
||||
<TestSetup components={props.components} loginscreen="your SAML login"/>
|
||||
|
||||

|
||||
|
||||

|
||||
@@ -0,0 +1,81 @@
|
||||
---
|
||||
title: Configure OKTA as an OIDC Identity Provider in ZITADEL
|
||||
sidebar_label: OKTA generic OIDC
|
||||
id: okta-oidc
|
||||
---
|
||||
|
||||
import GeneralConfigDescription from './_general_config_description.mdx';
|
||||
import Intro from './_intro.mdx';
|
||||
import CustomLoginPolicy from './_custom_login_policy.mdx';
|
||||
import IDPsOverview from './_idps_overview.mdx';
|
||||
import Activate from './_activate.mdx';
|
||||
import PrefillAction from './_prefill_action.mdx';
|
||||
import TestSetup from './_test_setup.mdx';
|
||||
|
||||
<Intro components={props.components} provider="OKTA"/>
|
||||
|
||||
## Open the Generic OIDC Provider Template
|
||||
|
||||
<IDPsOverview components={props.components} templates="Generic OIDC"/>
|
||||
|
||||
Click on the ZITADEL Callback URL to copy it to your clipboard.
|
||||
You will have to paste it in the OKTA application later.
|
||||
|
||||

|
||||
|
||||
## OKTA Configuration
|
||||
|
||||
### Register a new client
|
||||
|
||||
1. Login to your OKTA Account and go to the applications list: `OKTA-DOMAIN/admin/apps/active^
|
||||
2. Click on "Create App Integration" and choose "OIDC - OpenID Connect"
|
||||
3. Choose Web application as Application type and give a name
|
||||
4. [Paste the ZITADEL Callback URL you copied before](#open-the-generic-oidc-provider-template) to the Sign-in redirect URIs
|
||||
5. Save the clientid and client secret
|
||||
|
||||

|
||||
|
||||
## ZITADEL Configuration
|
||||
|
||||
1. Go back [to the Generic OIDC Provider template you opened before in ZITADEL](#open-the-generic-oidc-provider-template).
|
||||
2. Add the [client ID and secret created before on your Web application](#register-a-new-client).
|
||||
3. Give the provider a name, e.g. OKTA. This name will be displayed on the login screen button.
|
||||
4. Add the issuer URL of your OKTA account, e.g. `https://trial-1925566.okta.com`
|
||||
|
||||
You can optionally configure the following settings.
|
||||
A useful default will be filled if you don't change anything.
|
||||
|
||||
**Scopes**: The scopes define which scopes will be sent to the provider, `openid`, `profile`, and `email` are prefilled.
|
||||
This information will be taken to create/update the user within ZITADEL.
|
||||
ZITADEL ensures that at least the `openid`-scope is always sent.
|
||||
|
||||
**Use PKCE**: If enabled, the provider will use Proof Key for Code Exchange (PKCE) to secure the authorization code flow
|
||||
in addition to the client secret.
|
||||
|
||||
<GeneralConfigDescription components={props.components} provider_account="OKTA account" />
|
||||
|
||||
### Activate IdP
|
||||
|
||||
<Activate components={props.components} />
|
||||
|
||||

|
||||
|
||||
### Ensure your Login Policy allows External IDPs
|
||||
|
||||
<CustomLoginPolicy components={props.components} />
|
||||
|
||||
## Test the setup
|
||||
|
||||
<TestSetup components={props.components} loginscreen="your OKTA login"/>
|
||||
|
||||

|
||||
|
||||

|
||||
|
||||
## Optional: Add ZITADEL action to autofill userdata
|
||||
|
||||
<PrefillAction components={props.components} fields="firstname, lastname and email verified" provider="Okta"/>
|
||||
|
||||
```js reference
|
||||
https://github.com/zitadel/actions/blob/main/examples/okta_identity_provider.js
|
||||
```
|
||||
@@ -0,0 +1,122 @@
|
||||
---
|
||||
title: Configure OKTA as a SAML Identity Provider in ZITADEL
|
||||
sidebar_label: OKTA SAML
|
||||
id: okta-saml
|
||||
---
|
||||
|
||||
import GeneralConfigDescription from './_general_config_description.mdx';
|
||||
import Intro from './_intro.mdx';
|
||||
import CustomLoginPolicy from './_custom_login_policy.mdx';
|
||||
import IDPsOverview from './_idps_overview.mdx';
|
||||
import Activate from './_activate.mdx';
|
||||
import PrefillAction from './_prefill_action.mdx';
|
||||
import TestSetup from './_test_setup.mdx';
|
||||
|
||||
<Intro components={props.components} provider="OKTA"/>
|
||||
|
||||
## ZITADEL Configuration
|
||||
|
||||
### Go to the IdP Providers Overview
|
||||
|
||||
<IDPsOverview components={props.components} templates="SAML"/>
|
||||
|
||||
### Create a new SAML Provider
|
||||
|
||||
To be able to create the application in OKTA we need the provider id from ZITADEL.
|
||||
1. Create a new SAML Provider with a name and a random text in the Metadata Xml field.
|
||||
We will fill that as soon as we have done the configuration in OKTA.
|
||||
2. Save Configuration
|
||||
|
||||
As an alternative you can add the SAML identity provider through the API, either on the default settings or on a specific organization:
|
||||
- [Add Default SAML Identity Provider](/reference/api/admin/zitadel.admin.v1.AdminService.AddSAMLProvider)
|
||||
- [Add SAML Identity Provider on Organization](/reference/api/management/zitadel.management.v1.ManagementService.AddSAMLProvider)
|
||||
|
||||

|
||||
|
||||
After you created the SAML Provider in ZITADEL, you can copy the URLs you need to configure in your OKTA application.
|
||||
|
||||

|
||||
|
||||
## OKTA Configuration
|
||||
|
||||
### Register a new client
|
||||
|
||||
1. Log in to your OKTA Account and go to the applications list: `OKTA-DOMAIN/admin/apps/active`
|
||||
2. Click on "Create App Integration" and choose "SAML 2.0"
|
||||
3. Give the application a name
|
||||
4. Click on the ZITADEL URLs that your SAML IDP shows since you created it in ZITADEL and paste them accordingly:
|
||||
- **Single sign-on URL**: Paste the *ZITADEL ACS Login Form URL*.
|
||||
- **Audience URI (SP Entity ID)**: Paste the *ZITADEL Metadata URL*
|
||||
5. Save the configuration
|
||||
6. Copy the metadata URL from the details
|
||||
|
||||

|
||||
|
||||
### Add Attribute Statements
|
||||
|
||||
To send the user data from OKTA to ZITADEL you have to add some attribute mappings in your SAML Settings
|
||||
You can define the name by yourself, just ensure you use the same later on in the ZITADEL Action we will add.
|
||||
|
||||
Add the following three mappings:
|
||||
|
||||
| Name | Name format | Value |
|
||||
| ------------ | ----------- |--------------- |
|
||||
| givenname | Basic | user.firstName |
|
||||
| surname | Basic | user.lastName |
|
||||
| emailaddress | Basic | user.email |
|
||||
|
||||

|
||||
|
||||
### Assign Users to Application
|
||||
|
||||
To allow users to authenticate with that app go to the "Assign" Tab.
|
||||
1. Click the Assign Button
|
||||
2. Choose Assign To People
|
||||
3. Select the users you like to be able to authenticate
|
||||
|
||||

|
||||
|
||||
## Finish ZITADEL Configuration
|
||||
|
||||
You are now finished with the configuration in OKTA and you can switch back to your identity provider configuration in ZITADEL.
|
||||
|
||||
### Add Metadata Xml
|
||||
|
||||
Add [the metadata URL you have saved before from OKTA](#register-a-new-client) to the Metadata URL.
|
||||
As soon as you have saved the provider, and you have a look at the detail you should now see the Metadata Xml field filled.
|
||||
|
||||
If you prefer changing the configuration through the API you can update the SAML provider on the default settings or a specific organization:
|
||||
- [Update Default SAML Identity Provider](/reference/api/admin/zitadel.admin.v1.AdminService.UpdateSAMLProvider)
|
||||
- [Update SAML Identity Provider on Organization](/reference/api/management/zitadel.management.v1.ManagementService.UpdateSAMLProvider)
|
||||
|
||||

|
||||
|
||||
You can also fill the optional fields if needed:
|
||||
|
||||
<GeneralConfigDescription components={props.components} provider_account="OKTA account" />
|
||||
|
||||
### Activate IdP
|
||||
|
||||
<Activate components={props.components} />
|
||||
|
||||

|
||||
|
||||
### Ensure your Login Policy allows External IDPs
|
||||
|
||||
<CustomLoginPolicy components={props.components} />
|
||||
|
||||
## Test the setup
|
||||
|
||||
<TestSetup components={props.components} loginscreen="your OKTA login"/>
|
||||
|
||||

|
||||
|
||||

|
||||
|
||||
### Add Action to map user attributes
|
||||
|
||||
<PrefillAction components={props.components} fields="username, firstname, lastname, email and email verified" provider="OKTA"/>
|
||||
|
||||
```js reference
|
||||
https://github.com/zitadel/actions/blob/main/examples/okta_saml_prefil_register_form.js
|
||||
```
|
||||
@@ -0,0 +1,330 @@
|
||||
---
|
||||
title: Configure OneLogin as a SAML Identity Provider in ZITADEL
|
||||
sidebar_label: OneLogin SAML
|
||||
id: onelogin-saml
|
||||
---
|
||||
|
||||
import GeneralConfigDescription from './_general_config_description.mdx';
|
||||
import Intro from './_intro.mdx';
|
||||
import CustomLoginPolicy from './_custom_login_policy.mdx';
|
||||
import IDPsOverview from './_idps_overview.mdx';
|
||||
import Activate from './_activate.mdx';
|
||||
import TestSetup from './_test_setup.mdx';
|
||||
|
||||
<Intro components={props.components} provider="OneLogin"/>
|
||||
|
||||
## OneLogin SAML configuration
|
||||
|
||||
You need access to a OneLogin admin portal with permission to create and configure SAML applications.
|
||||
|
||||
We’ll first configure OneLogin sufficiently to **export IdP metadata**, which we then import into ZITADEL.
|
||||
After the ZITADEL SAML provider exists, we’ll return to OneLogin and finish the SAML configuration using the ZITADEL URLs.
|
||||
|
||||
### Create a new SAML application for ZITADEL
|
||||
|
||||
1. Sign in to the **OneLogin admin portal**.
|
||||
2. Go to **Applications > Applications** (or **Apps > Add Apps**, depending on your UI).
|
||||
3. Click **Add App**.
|
||||
4. In **Find Applications**, search for:
|
||||
- **SAML Test Connector (IdP w/ attr)** (recommended), or
|
||||
- **SAML Custom Connector (Advanced)** if you prefer a more generic connector.
|
||||
5. Select the connector and set:
|
||||
- **Display Name** – for example: `ZITADEL SAML`.
|
||||
- Any optional icon or description you like.
|
||||
6. Click **Save** to create the application.
|
||||
|
||||

|
||||
|
||||
### Export OneLogin IdP metadata
|
||||
|
||||
Now export OneLogin IdP metadata so ZITADEL can trust OneLogin as an identity provider.
|
||||
|
||||
1. In the OneLogin admin portal, open the **ZITADEL SAML** application.
|
||||
2. To export the full metadata XML:
|
||||
- In the top-right corner, open the **More Actions** menu.
|
||||
- Select **SAML Metadata** to download the metadata XML file.
|
||||
3. Alternatively, you can copy the **Issuer URL**, open it in a browser, and save the XML response.
|
||||
This URL often serves as an IdP metadata endpoint.
|
||||
|
||||
Keep either:
|
||||
|
||||
- the **IdP Metadata URL** (Issuer URL that returns XML), or
|
||||
- the **IdP metadata XML file**,
|
||||
|
||||
ready for the ZITADEL configuration steps.
|
||||
|
||||
## ZITADEL configuration
|
||||
|
||||
### Go to the IdP providers overview
|
||||
|
||||
<IDPsOverview components={props.components} templates="SAML"/>
|
||||
|
||||
### Create a new SAML Service Provider
|
||||
|
||||
The SAML provider template has everything you need preconfigured.
|
||||
Add the metadata XML or the URL to the metadata which is accessible by your ZITADEL instance.
|
||||
All the necessary configuration is contained in the metadata which has to be exchanged between the Service Provider and the Identity Provider.
|
||||
|
||||
<GeneralConfigDescription components={props.components} provider_account="OneLogin" />
|
||||
|
||||

|
||||
|
||||
After saving, open the newly created **OneLogin SAML provider** in ZITADEL.
|
||||
In the details view you will find the **ZITADEL Service Provider** URLs, such as:
|
||||
|
||||
- **ZITADEL Metadata URL**
|
||||
- **ZITADEL ACS Login Form URL** (for Login V1 and standard login flows)
|
||||
- **ZITADEL Single Logout URL**
|
||||
- **ZITADEL ACS Intent API URL** (for Login V2 and programmatic SAML flows)
|
||||
|
||||
For a typical browser-based login using the ZITADEL hosted login V2 you will use the:
|
||||
|
||||
- **ZITADEL ACS Intent API URL**, and
|
||||
- **ZITADEL Metadata URL**.
|
||||
|
||||
You’ll need these URLs in the next step when finishing the OneLogin configuration.
|
||||
|
||||
### Complete OneLogin configuration with ZITADEL URLs
|
||||
|
||||
Now that ZITADEL is configured, return to OneLogin and finish the SAML configuration of the ZITADEL app.
|
||||
|
||||
1. In the OneLogin admin portal, open the **ZITADEL SAML** application.
|
||||
2. Go to the **Configuration** tab (or the section where SAML SP settings such as ACS and Audience are configured).
|
||||
3. Fill in the SAML settings using the values from the ZITADEL SAML provider:
|
||||
|
||||
- **ACS (Consumer) URL / SAML Consumer URL**
|
||||
Set this to the **ZITADEL ACS Intent API URL**.
|
||||
|
||||
- **Recipient** (if present as a separate field)
|
||||
Set this to the **ZITADEL ACS Intent API URL** as well.
|
||||
|
||||
- **Audience / SP Entity ID / SAML Audience**
|
||||
Set this to the **ZITADEL Metadata URL**.
|
||||
|
||||
- **Single Logout URL** (optional but recommended)
|
||||
Set this to the **ZITADEL Single Logout URL**.
|
||||
|
||||
- **ACS (Consumer) URL Validator** (if present)
|
||||
For testing, you can use a permissive value like `.*`, then tighten it later to match the exact ACS URL.
|
||||
|
||||

|
||||
|
||||
4. Save your changes.
|
||||
|
||||
> _Optional: Import ZITADEL SP metadata_
|
||||
> Some OneLogin SAML connectors provide an **Upload Metadata** or **Upload metadata file** option.
|
||||
> In that case you can:
|
||||
> - Download the SP metadata XML from the **ZITADEL Metadata URL**, and
|
||||
> - Upload the XML file in OneLogin instead of manually filling in ACS and Audience.
|
||||
> This will automatically populate many of the SAML settings and certificates.
|
||||
|
||||
5. Assign users or groups to the **ZITADEL SAML** application in OneLogin (for example via the **Users** or **Access** tab), so they can use it for SSO.
|
||||
|
||||
### Configure SAML attributes in OneLogin
|
||||
|
||||
To provision users correctly in ZITADEL, configure which attributes OneLogin sends in the SAML assertion.
|
||||
|
||||
1. In the OneLogin admin portal, open the **ZITADEL SAML** application.
|
||||
2. Go to the **Parameters** tab.
|
||||
3. Add or edit parameters so that at least the following are sent and **included in the SAML assertion**:
|
||||
|
||||
- `email` → mapped to the user’s email address (for example **Email**).
|
||||
- `firstName` → mapped to the user’s first name (for example **First Name**).
|
||||
- `lastName` → mapped to the user’s last name (for example **Last Name**).
|
||||
|
||||
4. Ensure the **NameID** is set to a unique identifier (commonly the user’s email address), if your OneLogin connector requires it.
|
||||
5. Save your changes.
|
||||
|
||||
These attributes are later available in ZITADEL’s **IdP information** and can be mapped to ZITADEL user fields via Actions V2.
|
||||
|
||||
### Activate IdP
|
||||
|
||||
<Activate components={props.components} />
|
||||
|
||||

|
||||
|
||||
### Ensure your Login Policy allows External IdPs
|
||||
|
||||
<CustomLoginPolicy components={props.components} />
|
||||
|
||||
## Configure an action to autofill user data
|
||||
|
||||
### Required for Login V2
|
||||
|
||||
The creation of users in ZITADEL will fail if the required fields to create a user are not set.
|
||||
|
||||
**Actions V2** can be used to map the SAML attributes returned by the IdP to the required fields in ZITADEL.
|
||||
See the [Actions V2 Response Manipulation](/guides/integrate/actions/testing-response-manipulation)
|
||||
guide for more information on setting up a Target and an Execution. In short,
|
||||
|
||||
* Create an Actions V2 Target of type `REST Call`.
|
||||
* Create an Execution of type `Response` on the method `/zitadel.user.v2.UserService/RetrieveIdentityProviderIntent`.
|
||||
|
||||
The following minimal example modifies the response of `/zitadel.user.v2.UserService/RetrieveIdentityProviderIntent` to set the required fields
|
||||
for user creation. This is just an example, please adjust the attributes according to your IdP.
|
||||
|
||||
``` go
|
||||
package main
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"io"
|
||||
"log"
|
||||
"net/http"
|
||||
|
||||
"github.com/muhlemmer/gu"
|
||||
"github.com/zitadel/zitadel-go/v3/pkg/client/zitadel/user/v2"
|
||||
"google.golang.org/protobuf/encoding/protojson"
|
||||
)
|
||||
|
||||
type contextResponse struct {
|
||||
Request *retrieveIdentityProviderIntentRequestWrapper `json:"request"`
|
||||
Response *retrieveIdentityProviderIntentResponseWrapper `json:"response"`
|
||||
}
|
||||
|
||||
// RetrieveIdentityProviderIntentRequestWrapper necessary to marshal and unmarshal the JSON into the proto message correctly
|
||||
type retrieveIdentityProviderIntentRequestWrapper struct {
|
||||
user.RetrieveIdentityProviderIntentRequest
|
||||
}
|
||||
|
||||
func (r *retrieveIdentityProviderIntentRequestWrapper) MarshalJSON() ([]byte, error) {
|
||||
data, err := protojson.Marshal(r)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return data, nil
|
||||
}
|
||||
|
||||
func (r *retrieveIdentityProviderIntentRequestWrapper) UnmarshalJSON(data []byte) error {
|
||||
return protojson.Unmarshal(data, r)
|
||||
}
|
||||
|
||||
// RetrieveIdentityProviderIntentResponseWrapper necessary to marshal and unmarshal the JSON into the proto message correctly
|
||||
type retrieveIdentityProviderIntentResponseWrapper struct {
|
||||
user.RetrieveIdentityProviderIntentResponse
|
||||
}
|
||||
|
||||
func (r *retrieveIdentityProviderIntentResponseWrapper) MarshalJSON() ([]byte, error) {
|
||||
data, err := protojson.Marshal(r)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return data, nil
|
||||
}
|
||||
|
||||
func (r *retrieveIdentityProviderIntentResponseWrapper) UnmarshalJSON(data []byte) error {
|
||||
return protojson.Unmarshal(data, r)
|
||||
}
|
||||
|
||||
// call HandleFunc to read the response body, manipulate the content and return the response
|
||||
func call(w http.ResponseWriter, req *http.Request) {
|
||||
// read the body content
|
||||
sentBody, err := io.ReadAll(req.Body)
|
||||
if err != nil {
|
||||
// if there was an error while reading the body return an error
|
||||
http.Error(w, "error", http.StatusInternalServerError)
|
||||
return
|
||||
}
|
||||
defer req.Body.Close()
|
||||
|
||||
// read the response into the expected structure
|
||||
request := new(contextResponse)
|
||||
if err := json.Unmarshal(sentBody, request); err != nil {
|
||||
http.Error(w, "error", http.StatusInternalServerError)
|
||||
return
|
||||
}
|
||||
|
||||
// build the response from the received response
|
||||
resp := request.Response
|
||||
// manipulate the received response to send back as response
|
||||
if err = manipulateResponse(resp); err != nil {
|
||||
http.Error(w, "error modifying response", http.StatusInternalServerError)
|
||||
return
|
||||
}
|
||||
|
||||
// marshal the response into json
|
||||
data, err := json.Marshal(resp)
|
||||
if err != nil {
|
||||
// if there was an error while marshalling the json
|
||||
http.Error(w, "error marshaling response", http.StatusInternalServerError)
|
||||
return
|
||||
}
|
||||
|
||||
// return the manipulated response
|
||||
w.Write(data)
|
||||
}
|
||||
|
||||
type rawInformation struct {
|
||||
Attributes struct {
|
||||
Email []string `json:"email"`
|
||||
FirstName []string `json:"firstName"`
|
||||
Id []string `json:"id"`
|
||||
LastName []string `json:"lastName"`
|
||||
} `json:"attributes"`
|
||||
Id string `json:"id"`
|
||||
}
|
||||
|
||||
func manipulateResponse(resp *retrieveIdentityProviderIntentResponseWrapper) error {
|
||||
if resp == nil || resp.IdpInformation == nil || resp.IdpInformation.RawInformation == nil {
|
||||
log.Println("missing IdP/User information in the IdP response")
|
||||
return nil
|
||||
}
|
||||
// retrieve raw information from the IdP
|
||||
var rawInfoBytes []byte
|
||||
var err error
|
||||
if rawInfoBytes, err = resp.IdpInformation.RawInformation.MarshalJSON(); err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
// NOTE: the raw information struct used here is just an example.
|
||||
// Please adapt this to your IdP.
|
||||
var rawInfo rawInformation
|
||||
if err = json.Unmarshal(rawInfoBytes, &rawInfo); err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
if len(rawInfo.Attributes.Email) == 0 ||
|
||||
len(rawInfo.Attributes.FirstName) == 0 ||
|
||||
len(rawInfo.Attributes.Id) == 0 ||
|
||||
len(rawInfo.Attributes.LastName) == 0 {
|
||||
log.Println("missing required attributes in the IdP response")
|
||||
return nil
|
||||
}
|
||||
|
||||
// to create a new user.
|
||||
if resp.AddHumanUser != nil {
|
||||
// set the required fields to create a new user in ZITADEL based on the information returned by the IdP
|
||||
resp.IdpInformation.UserName = rawInfo.Attributes.Email[0]
|
||||
|
||||
resp.AddHumanUser.Profile = &user.SetHumanProfile{
|
||||
GivenName: rawInfo.Attributes.FirstName[0],
|
||||
FamilyName: rawInfo.Attributes.LastName[0],
|
||||
}
|
||||
resp.AddHumanUser.Email = &user.SetHumanEmail{
|
||||
Email: rawInfo.Attributes.Email[0],
|
||||
Verification: &user.SetHumanEmail_IsVerified{IsVerified: true},
|
||||
}
|
||||
resp.AddHumanUser.Username = gu.Ptr(rawInfo.Attributes.Email[0])
|
||||
resp.AddHumanUser.IdpLinks = []*user.IDPLink{
|
||||
{
|
||||
UserName: rawInfo.Attributes.Email[0],
|
||||
},
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func main() {
|
||||
// handle the HTTP call under "/call"
|
||||
http.HandleFunc("/call", call)
|
||||
|
||||
// start an HTTP server with the before defined function to handle the endpoint under "http://localhost:8090"
|
||||
http.ListenAndServe(":8090", nil)
|
||||
}
|
||||
```
|
||||
|
||||
## Test the setup
|
||||
|
||||
<TestSetup components={props.components} loginscreen="your OneLogin login"/>
|
||||
|
||||

|
||||
@@ -0,0 +1,232 @@
|
||||
---
|
||||
title: Configure Local OpenLDAP as an Identity Provider in ZITADEL
|
||||
sidebar_label: Local OpenLDAP
|
||||
---
|
||||
|
||||
import Intro from './_intro.mdx';
|
||||
import CustomLoginPolicy from './_custom_login_policy.mdx';
|
||||
import IDPsOverview from './_idps_overview.mdx';
|
||||
import GeneralConfigDescription from './_general_config_description.mdx';
|
||||
import Activate from './_activate.mdx';
|
||||
import TestSetup from './_test_setup.mdx';
|
||||
|
||||
import HowLDAPIDPWorks from './_how_ldap_idp_works.mdx'
|
||||
|
||||
<Callout type="warn">
|
||||
This guide shows you how you can configure an LDAP server locally.
|
||||
ZITADEL needs access to the LDAP server, so this won't work in ZITADEL Cloud.
|
||||
You have to spin up your own local ZITADEL.
|
||||
The easiest way to do so is [by following the Docker Compose installation guide](/self-hosting/deploy/compose).
|
||||
</Callout>
|
||||
|
||||
<Callout type="caution">
|
||||
Beware that this example configuration neither supports LDAPS nor StartTLS.
|
||||
We highly recommend to enable LDAPS or StartTLS in your production setup.
|
||||
Otherwise, your users passwords are sent in clear text through the wire.
|
||||
</Callout>
|
||||
|
||||
<Intro components={props.components} provider="a local OpenLDAP server"/>
|
||||
|
||||
## How it works
|
||||
|
||||
<HowLDAPIDPWorks components={props.components} />
|
||||
|
||||
## OpenLDAP Configuration
|
||||
|
||||
### Basic configuration
|
||||
|
||||
You can run OpenLdap via `docker-compose` using the following:
|
||||
```
|
||||
version: '2'
|
||||
|
||||
networks:
|
||||
my-network:
|
||||
driver: bridge
|
||||
services:
|
||||
openldap:
|
||||
image: bitnami/openldap:latest
|
||||
ports:
|
||||
- '389:1389'
|
||||
environment:
|
||||
- LDAP_ADMIN_USERNAME=admin
|
||||
- LDAP_ADMIN_PASSWORD=Password1!
|
||||
- LDAP_USERS=test
|
||||
- LDAP_PASSWORDS=Password1!
|
||||
- LDAP_ROOT=dc=example,dc=com
|
||||
- LDAP_ADMIN_DN=cn=admin,dc=example,dc=com
|
||||
networks:
|
||||
- my-network
|
||||
volumes:
|
||||
- 'openldap_data:/bitnami/openldap'
|
||||
volumes:
|
||||
openldap_data:
|
||||
driver: local
|
||||
````
|
||||
|
||||
Alternatively, you can run LDAP locally. To run LDAP locally to test it with ZITADEL please refer to [OpenLDAP](https://www.openldap.org/) with [slapd](https://www.openldap.org/software/man.cgi?query=slapd).
|
||||
|
||||
For a quickstart guide please refer to their [official documentation](https://www.openldap.org/doc/admin22/quickstart.html).
|
||||
|
||||
A basic configuration would be like this
|
||||
```
|
||||
#
|
||||
# See slapd.conf(5) for details on configuration options.
|
||||
# This file should NOT be world readable.
|
||||
#
|
||||
include /usr/local/etc/openldap/schema/core.schema
|
||||
include /usr/local/etc/openldap/schema/cosine.schema
|
||||
include /usr/local/etc/openldap/schema/inetorgperson.schema
|
||||
include /usr/local/etc/openldap/schema/nis.schema
|
||||
include /usr/local/etc/openldap/schema/misc.schema
|
||||
|
||||
# Define global ACLs to disable default read access.
|
||||
|
||||
# Do not enable referrals until AFTER you have a working directory
|
||||
# service AND an understanding of referrals.
|
||||
#referral ldap://root.openldap.org
|
||||
|
||||
pidfile /usr/local/var/run/slapd.pid
|
||||
argsfile /usr/local/var/run/slapd.args
|
||||
|
||||
# Load dynamic backend modules:
|
||||
modulepath /usr/local/Cellar/openldap/2.4.53/libexec/openldap
|
||||
moduleload back_mdb.la
|
||||
moduleload back_ldap.la
|
||||
|
||||
# Sample security restrictions
|
||||
# Require integrity protection (prevent hijacking)
|
||||
# Require 112-bit (3DES or better) encryption for updates
|
||||
# Require 63-bit encryption for simple bind
|
||||
# security ssf=1 update_ssf=112 simple_bind=64
|
||||
|
||||
# Sample access control policy:
|
||||
# Root DSE: allow anyone to read it
|
||||
# Subschema (sub)entry DSE: allow anyone to read it
|
||||
# Other DSEs:
|
||||
# Allow self write access
|
||||
# Allow authenticated users read access
|
||||
# Allow anonymous users to authenticate
|
||||
# Directives needed to implement policy:
|
||||
# access to dn.base="" by * read
|
||||
# access to dn.base="cn=Subschema" by * read
|
||||
# access to *
|
||||
# by self write
|
||||
# by users read
|
||||
# by anonymous auth
|
||||
#
|
||||
# if no access controls are present, the default policy
|
||||
# allows anyone and everyone to read anything but restricts
|
||||
# updates to rootdn. (e.g., "access to * by * read")
|
||||
#
|
||||
# rootdn can always read and write EVERYTHING!
|
||||
|
||||
#######################################################################
|
||||
# MDB database definitions
|
||||
#######################################################################
|
||||
|
||||
database ldif
|
||||
#maxsize 1073741824
|
||||
suffix "dc=example,dc=com"
|
||||
rootdn "cn=admin,dc=example,dc=com"
|
||||
# Cleartext passwords, especially for the rootdn, should
|
||||
# be avoid. See slappasswd(8) and slapd.conf(5) for details.
|
||||
# Use of strong authentication encouraged.
|
||||
rootpw {SSHA}6FTOTIITpkP9IAf22VjHqu4JisyBmW5A
|
||||
# The database directory MUST exist prior to running slapd AND
|
||||
# should only be accessible by the slapd and slap tools.
|
||||
# Mode 700 recommended.
|
||||
directory /usr/local/var/openldap-data
|
||||
# Indices to maintain
|
||||
#index objectClass eq
|
||||
```
|
||||
|
||||
Which is the default configuration with an admin user under the DN `cn=admin,dc=example,dc=com` and password `Password1!`, BaseDN `"dc=example,dc=com` and database set to `ldif`.
|
||||
In addition, there are some schemas included which can be used to create the users.
|
||||
|
||||
### Example users
|
||||
|
||||
For a basic structure and an example user you can use this structure in a `.ldif` file:
|
||||
```
|
||||
dn: dc=example,dc=com
|
||||
dc: example
|
||||
description: Company
|
||||
objectClass: dcObject
|
||||
objectClass: organization
|
||||
o: Example, Inc.
|
||||
|
||||
dn: ou=people, dc=example,dc=com
|
||||
ou: people
|
||||
description: All people in organisation
|
||||
objectclass: organizationalunit
|
||||
|
||||
dn: cn=test,ou=people,dc=example,dc=com
|
||||
objectclass: inetOrgPerson
|
||||
cn: testuser
|
||||
sn: test
|
||||
uid: test
|
||||
userpassword: {SHA}qUqP5cyxm6YcTAhz05Hph5gvu9M=
|
||||
mail: [email protected]
|
||||
description: Person
|
||||
ou: Human Resources
|
||||
```
|
||||
|
||||
Which in essence creates a user with DN `cn=test,ou=people,dc=example,dc=com`, uid `test` and password `test`.
|
||||
|
||||
The user can be applied after OpenLDAP is running with
|
||||
```bash
|
||||
ldapadd -x -h localhost -D "cn=admin,dc=example,dc=com" -f example.ldif -w 'Password1!'
|
||||
```
|
||||
|
||||
## ZITADEL Configuration
|
||||
|
||||
### Go to the IdP Providers Overview
|
||||
|
||||
<IDPsOverview components={props.components} templates="Active Directory / LDAP"/>
|
||||
|
||||
### Create a new LDAP Provider
|
||||
|
||||
Fill in the template fields with the exact values listed below. The fields are described in the [LDAP guide](./ldap#create-a-new-ldap-provider).
|
||||
|
||||
**Name**: OpenLDAP
|
||||
|
||||
**Servers**: "ldap://localhost:389"
|
||||
|
||||
**BaseDN**: "dc=example,dc=com"
|
||||
|
||||
**BindDn**: "cn=admin,dc=example,dc=com"
|
||||
|
||||
**BindPassword**: "Password1!"
|
||||
|
||||
**Userbase**: "dn"
|
||||
|
||||
**User filters**: "uid"
|
||||
|
||||
**User Object Classes**: "inetOrgPerson"
|
||||
|
||||
**LDAP Attributes**: id attributes = "uid"
|
||||
|
||||
**StartTLS**: For this example should be left untouched, if this setting is enabled after the initial connection ZITADEL tries to build a TLS connection.
|
||||
|
||||
**Timeout**: Can be left empty, if this setting is set all connection run with a set timeout, if it is 0s the default timeout of 60s is used.
|
||||
|
||||
<GeneralConfigDescription components={props.components} provider_account="LDAP user" />
|
||||
|
||||

|
||||
|
||||
### Activate IdP
|
||||
|
||||
<Activate components={props.components} />
|
||||
|
||||

|
||||
|
||||
### Ensure your Login Policy allows External IDPs
|
||||
|
||||
<CustomLoginPolicy components={props.components} />
|
||||
|
||||
## Test the setup
|
||||
|
||||
<TestSetup components={props.components} loginscreen="ZITADELs LDAP login"/>
|
||||
|
||||

|
||||
|
||||

|
||||
@@ -0,0 +1,345 @@
|
||||
---
|
||||
title: Configure PingFederate as a SAML Identity Provider in ZITADEL
|
||||
sidebar_label: PingFederate SAML
|
||||
id: pingfederate-saml
|
||||
---
|
||||
|
||||
import GeneralConfigDescription from './_general_config_description.mdx';
|
||||
import Intro from './_intro.mdx';
|
||||
import CustomLoginPolicy from './_custom_login_policy.mdx';
|
||||
import IDPsOverview from './_idps_overview.mdx';
|
||||
import Activate from './_activate.mdx';
|
||||
import TestSetup from './_test_setup.mdx';
|
||||
|
||||
<Intro components={props.components} provider="PingFederate"/>
|
||||
|
||||
## PingFederate SAML configuration
|
||||
|
||||
You need access to a PingFederate administrative console with permission to create **SP Connections**.
|
||||
|
||||
We’ll first configure PingFederate sufficiently to **export IdP metadata**, which we then import into ZITADEL.
|
||||
After the ZITADEL SAML provider exists, we’ll return to PingFederate and finish the SP configuration using the ZITADEL URLs.
|
||||
|
||||
### Create a new SP Connection for ZITADEL
|
||||
|
||||
1. Sign in to the **PingFederate admin console**.
|
||||
2. Go to **Applications > SP Connections**.
|
||||
3. Select **Create New** (or **Add Connection**).
|
||||
4. When asked how to create the connection, choose **Manually Configure Connection** (do not import metadata yet).
|
||||
5. On the **Connection Type** screen, choose:
|
||||
- **Browser SSO** as the connection type.
|
||||
- **SAML 2.0** as the protocol.
|
||||
6. On **General Settings**:
|
||||
- Set a **Connection Name**, for example: `ZITADEL SAML`.
|
||||
- Optionally set an ID or description to identify the connection.
|
||||
|
||||
### Configure Browser SSO
|
||||
|
||||
1. In the new connection wizard, go to **Browser SSO**.
|
||||
2. Make sure **SAML 2.0** Browser SSO is enabled for this connection.
|
||||
3. Proceed to **Assertion Creation**:
|
||||
- Keep the default **NameID** attribute.
|
||||
- Add additional attributes you want to send to ZITADEL (you need at least `email`, `given_name` (first name of the user), `family_name` (last name of the user), and you can send optional attributes like `display_name`).
|
||||
4. In **Attribute Mapping**, map the contract attributes to your directory/user store fields.
|
||||
|
||||
### Export PingFederate IdP metadata
|
||||
|
||||
Now export IdP metadata for this connection so ZITADEL can trust PingFederate.
|
||||
|
||||
1. In PingFederate, go to **System > Protocol Metadata > Metadata Export**.
|
||||
2. Select **SAML 2.0**.
|
||||
3. Set the **Role** to **IdP** (Identity Provider).
|
||||
4. Choose to generate **connection-specific metadata** and select the SP Connection you created for ZITADEL.
|
||||
5. Choose a transfer method:
|
||||
- **Metadata URL** – PingFederate publishes metadata at a URL you can copy; or
|
||||
- **File download** – export the metadata as an XML file.
|
||||
|
||||
Keep either:
|
||||
|
||||
- the **Metadata URL**, or
|
||||
- the **XML file** contents,
|
||||
|
||||
ready for the ZITADEL configuration steps.
|
||||
|
||||
## ZITADEL configuration
|
||||
|
||||
### Go to the IdP providers overview
|
||||
|
||||
<IDPsOverview components={props.components} templates="SAML"/>
|
||||
|
||||
### Create a new SAML Service Provider
|
||||
|
||||
The SAML provider template has everything you need preconfigured.
|
||||
Add the metadata.xml or the URL to the metadata which are accessible by your ZITADEL instance.
|
||||
All the necessary configuration is contained in the metadata which has to be exchanged by the ServiceProvider and the IdentityProvider.
|
||||
|
||||
<GeneralConfigDescription components={props.components} provider_account="PingFederate" />
|
||||
|
||||

|
||||
|
||||
After saving, open the newly created PingFederate SAML provider in ZITADEL.
|
||||
In the details view you will find the **ZITADEL Service Provider** URLs, such as:
|
||||
|
||||
- **ZITADEL Metadata URL**
|
||||
- **ZITADEL ACS Login Form URL** (for Login V1)
|
||||
- **ZITADEL Single Logout URL**
|
||||
- **ZITADEL ACS Intent API URL** (for Login V2 and programmatic SAML flows)
|
||||
|
||||
You’ll need these in the next step.
|
||||
|
||||
### Import ZITADEL metadata into PingFederate (recommended)
|
||||
|
||||
Now that ZITADEL is configured, you can let PingFederate **consume ZITADEL’s SP metadata URL**.
|
||||
This allows PingFederate to:
|
||||
|
||||
- Auto-fill the ZITADEL **ACS URL**, **entity ID**, and **SLO URLs**.
|
||||
- Import and keep up-to-date the **verification/encryption certificates** from the metadata.
|
||||
|
||||
#### Create a Partner Metadata URL for ZITADEL
|
||||
|
||||
1. In the PingFederate admin console, go to:
|
||||
**System > Protocol Metadata > Partner Metadata URLs**.
|
||||
2. Click **Add New URL**.
|
||||
3. On the **URL** tab:
|
||||
- **Name** – `ZITADEL SP Metadata` (or similar).
|
||||
- **URL** – paste the **ZITADEL Metadata URL** you copied from ZITADEL.
|
||||
- Keep **Validate Metadata Signature** enabled (recommended) unless you have a reason to disable it.
|
||||
4. Click **Load Metadata**.
|
||||
5. On the **Certificate Summary** tab, review the certificate information associated with the metadata.
|
||||
6. On the **Summary** tab, click **Done**, then **Save**.
|
||||
|
||||
PingFederate can now use this metadata URL to configure and automatically update the SP connection.
|
||||
|
||||
### Import SP metadata into the ZITADEL SP Connection
|
||||
|
||||
With the partner metadata URL defined, apply it to your existing SP Connection for ZITADEL.
|
||||
|
||||
1. Go to **Applications > SP Connections**.
|
||||
2. Edit the SP Connection you created for ZITADEL.
|
||||
3. Go to the **Import Metadata** tab.
|
||||
4. Select **URL**.
|
||||
5. From the **Metadata URL** drop-down, select the **ZITADEL SP Metadata** entry you created.
|
||||
- If you don’t see it, click **Manage Partner Metadata URLs** and verify it exists and loads correctly.
|
||||
6. Ensure **Enable Automatic Reloading** is checked if you want PingFederate to periodically refresh metadata (recommended).
|
||||
7. Click **Load Metadata**.
|
||||
|
||||
PingFederate will:
|
||||
|
||||
- Read the SP metadata from ZITADEL,
|
||||
- Populate the **ACS URL**, SLO URLs, and other protocol settings for the connection, and
|
||||
- Import the SP’s **signing/encryption certificates** for signature verification and encryption.
|
||||
|
||||
You can review the updated values on:
|
||||
|
||||
- **Browser SSO > Protocol Settings** (ACS URL, bindings, SLO URLs), and
|
||||
- **Credentials > Signature Verification / Encryption** (certificates imported from metadata).
|
||||
|
||||
If needed, you can still override specific settings manually, but using the metadata URL is the preferred way to keep endpoints and certificates in sync.
|
||||
|
||||
#### If you need to update the SP Connection with ZITADEL URLs
|
||||
|
||||
1. In PingFederate, open the **SP Connection** you created for ZITADEL.
|
||||
2. Go to the **Browser SSO / Protocol Settings** (exact naming may vary by version).
|
||||
3. Update the SP settings:
|
||||
|
||||
- **Assertion Consumer Service (ACS) URL**
|
||||
Set this to the **ZITADEL ACS Intent API URL** from the SAML provider details.
|
||||
|
||||
- **SP Entity ID / Audience / Partner Entity ID**
|
||||
Set this to the **ZITADEL Metadata URL**.
|
||||
|
||||
- **Single Logout (optional)**
|
||||
If you want SAML Single Logout, configure PingFederate’s logout behavior to call the **ZITADEL Single Logout URL** using the appropriate binding (typically HTTP-Redirect).
|
||||
|
||||
4. Save and **activate** the connection changes in PingFederate.
|
||||
|
||||
### Activate IdP
|
||||
|
||||
<Activate components={props.components} />
|
||||
|
||||

|
||||
|
||||
### Ensure your Login Policy allows External IdPs
|
||||
|
||||
<CustomLoginPolicy components={props.components} />
|
||||
|
||||
## Configure an action to autofill user data
|
||||
|
||||
### Required for Login V2
|
||||
The creation of users in ZITADEL will fail if the required fields to create a user are not set.
|
||||
|
||||
**Actions V2** can be used to map the SAML attributes returned by the IdP to the required fields in ZITADEL.
|
||||
See the [Actions V2 Response Manipulation](/guides/integrate/actions/testing-response-manipulation)
|
||||
guide for more information on setting up a Target and an Execution. In short,
|
||||
* Create an Actions V2 Target of type `REST Call`
|
||||
* Create an Execution of type `Response` on the method `/zitadel.user.v2.UserService/RetrieveIdentityProviderIntent`
|
||||
|
||||
The following minimal example modifies the response of `/zitadel.user.v2.UserService/RetrieveIdentityProviderIntent` to set the required fields
|
||||
for user creation. This is just an example, please adjust the attributes according to your IdP.
|
||||
|
||||
``` go
|
||||
package main
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"io"
|
||||
"log"
|
||||
"net/http"
|
||||
|
||||
"github.com/muhlemmer/gu"
|
||||
"github.com/zitadel/zitadel-go/v3/pkg/client/zitadel/user/v2"
|
||||
"google.golang.org/protobuf/encoding/protojson"
|
||||
)
|
||||
|
||||
type contextResponse struct {
|
||||
Request *retrieveIdentityProviderIntentRequestWrapper `json:"request"`
|
||||
Response *retrieveIdentityProviderIntentResponseWrapper `json:"response"`
|
||||
}
|
||||
|
||||
// RetrieveIdentityProviderIntentRequestWrapper necessary to marshal and unmarshal the JSON into the proto message correctly
|
||||
type retrieveIdentityProviderIntentRequestWrapper struct {
|
||||
user.RetrieveIdentityProviderIntentRequest
|
||||
}
|
||||
|
||||
func (r *retrieveIdentityProviderIntentRequestWrapper) MarshalJSON() ([]byte, error) {
|
||||
data, err := protojson.Marshal(r)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return data, nil
|
||||
}
|
||||
|
||||
func (r *retrieveIdentityProviderIntentRequestWrapper) UnmarshalJSON(data []byte) error {
|
||||
return protojson.Unmarshal(data, r)
|
||||
}
|
||||
|
||||
// RetrieveIdentityProviderIntentResponseWrapper necessary to marshal and unmarshal the JSON into the proto message correctly
|
||||
type retrieveIdentityProviderIntentResponseWrapper struct {
|
||||
user.RetrieveIdentityProviderIntentResponse
|
||||
}
|
||||
|
||||
func (r *retrieveIdentityProviderIntentResponseWrapper) MarshalJSON() ([]byte, error) {
|
||||
data, err := protojson.Marshal(r)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return data, nil
|
||||
}
|
||||
|
||||
func (r *retrieveIdentityProviderIntentResponseWrapper) UnmarshalJSON(data []byte) error {
|
||||
return protojson.Unmarshal(data, r)
|
||||
}
|
||||
|
||||
// call HandleFunc to read the response body, manipulate the content and return the response
|
||||
func call(w http.ResponseWriter, req *http.Request) {
|
||||
// read the body content
|
||||
sentBody, err := io.ReadAll(req.Body)
|
||||
if err != nil {
|
||||
// if there was an error while reading the body return an error
|
||||
http.Error(w, "error", http.StatusInternalServerError)
|
||||
return
|
||||
}
|
||||
defer req.Body.Close()
|
||||
|
||||
// read the response into the expected structure
|
||||
request := new(contextResponse)
|
||||
if err := json.Unmarshal(sentBody, request); err != nil {
|
||||
http.Error(w, "error", http.StatusInternalServerError)
|
||||
return
|
||||
}
|
||||
|
||||
// build the response from the received response
|
||||
resp := request.Response
|
||||
// manipulate the received response to send back as response
|
||||
if err = manipulateResponse(resp); err != nil {
|
||||
http.Error(w, "error modifying response", http.StatusInternalServerError)
|
||||
return
|
||||
}
|
||||
|
||||
// marshal the response into json
|
||||
data, err := json.Marshal(resp)
|
||||
if err != nil {
|
||||
// if there was an error while marshalling the json
|
||||
http.Error(w, "error marshaling response", http.StatusInternalServerError)
|
||||
return
|
||||
}
|
||||
|
||||
// return the manipulated response
|
||||
w.Write(data)
|
||||
}
|
||||
|
||||
type rawInformation struct {
|
||||
Attributes struct {
|
||||
Email []string `json:"email"`
|
||||
FirstName []string `json:"firstName"`
|
||||
Id []string `json:"id"`
|
||||
LastName []string `json:"lastName"`
|
||||
} `json:"attributes"`
|
||||
Id string `json:"id"`
|
||||
}
|
||||
|
||||
func manipulateResponse(resp *retrieveIdentityProviderIntentResponseWrapper) error {
|
||||
if resp == nil || resp.IdpInformation == nil || resp.IdpInformation.RawInformation == nil {
|
||||
log.Println("missing IdP/User information in the IdP response")
|
||||
return nil
|
||||
}
|
||||
// retrieve raw information from the IdP
|
||||
var rawInfoBytes []byte
|
||||
var err error
|
||||
if rawInfoBytes, err = resp.IdpInformation.RawInformation.MarshalJSON(); err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
// NOTE: the raw information struct used here is just an example.
|
||||
// Please adapt this to your IdP.
|
||||
var rawInfo rawInformation
|
||||
if err = json.Unmarshal(rawInfoBytes, &rawInfo); err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
if len(rawInfo.Attributes.Email) == 0 ||
|
||||
len(rawInfo.Attributes.FirstName) == 0 ||
|
||||
len(rawInfo.Attributes.Id) == 0 ||
|
||||
len(rawInfo.Attributes.LastName) == 0 {
|
||||
log.Println("missing required attributes in the IdP response")
|
||||
return nil
|
||||
}
|
||||
|
||||
// to create a new user.
|
||||
if resp.AddHumanUser != nil {
|
||||
// set the required fields to create a new user in Zitadel based on the information returned by the IdP
|
||||
resp.IdpInformation.UserName = rawInfo.Attributes.Email[0]
|
||||
|
||||
resp.AddHumanUser.Profile = &user.SetHumanProfile{
|
||||
GivenName: rawInfo.Attributes.FirstName[0],
|
||||
FamilyName: rawInfo.Attributes.LastName[0],
|
||||
}
|
||||
resp.AddHumanUser.Email = &user.SetHumanEmail{
|
||||
Email: rawInfo.Attributes.Email[0],
|
||||
Verification: &user.SetHumanEmail_IsVerified{IsVerified: true},
|
||||
}
|
||||
resp.AddHumanUser.Username = gu.Ptr(rawInfo.Attributes.Email[0])
|
||||
resp.AddHumanUser.IdpLinks = []*user.IDPLink{
|
||||
{
|
||||
UserName: rawInfo.Attributes.Email[0],
|
||||
},
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func main() {
|
||||
// handle the HTTP call under "/call"
|
||||
http.HandleFunc("/call", call)
|
||||
|
||||
// start an HTTP server with the before defined function to handle the endpoint under "http://localhost:8090"
|
||||
http.ListenAndServe(":8090", nil)
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
## Test the setup
|
||||
|
||||
<TestSetup components={props.components} loginscreen="your PingFederate login"/>
|
||||
|
||||

|
||||
Reference in New Issue
Block a user