mirror of
https://github.com/andwati/zitadel.git
synced 2026-10-29 10:32:15 +00:00
docs: identity provider docs (#5565)
* docs: add github identity provider * docs: add github identity provider * docs: add github identity provider * docs: github identity provider * docs: google provider * docs: google provider * docs: gitlab identity provider * docs: gitlab identity provider * docs: general information identity providers * docs: general information identity providers * docs: add ldap and openldap identity provider docs * docs: azure ad * docs: azure ad * docs: rename attribute for azure ad * Update docs/docs/guides/integrate/identity-providers/azure-ad.md Co-authored-by: Elio Bischof <[email protected]> * Update docs/docs/guides/integrate/identity-providers/azure-ad.md Co-authored-by: Elio Bischof <[email protected]> * Update docs/docs/guides/integrate/identity-providers/azure-ad.md Co-authored-by: Elio Bischof <[email protected]> * Update docs/docs/guides/integrate/identity-providers/azure-ad.md Co-authored-by: Elio Bischof <[email protected]> * Update docs/docs/guides/integrate/identity-providers/azure-ad.md Co-authored-by: Elio Bischof <[email protected]> * Update docs/docs/guides/integrate/identity-providers/azure-ad.md Co-authored-by: Elio Bischof <[email protected]> * Update docs/docs/guides/integrate/identity-providers/azure-ad.md Co-authored-by: Elio Bischof <[email protected]> * Update docs/docs/guides/integrate/identity-providers/azure-ad.md Co-authored-by: Elio Bischof <[email protected]> * Update docs/docs/guides/integrate/identity-providers/azure-ad.md Co-authored-by: Elio Bischof <[email protected]> * Update docs/docs/guides/integrate/identity-providers/azure-ad.md Co-authored-by: Elio Bischof <[email protected]> * Update docs/docs/guides/integrate/identity-providers/azure-ad.md Co-authored-by: Elio Bischof <[email protected]> * Update docs/docs/guides/integrate/identity-providers/azure-ad.md Co-authored-by: Elio Bischof <[email protected]> * docs: general config in one file * docs: add ldap and openldap identity provider docs * docs: general describtion add missing providers * docs: typos and rewriting * Update docs/docs/guides/integrate/identity-providers/gitlab.md Co-authored-by: Elio Bischof <[email protected]> * Update docs/docs/guides/integrate/identity-providers/github.md Co-authored-by: Elio Bischof <[email protected]> * Update docs/docs/guides/integrate/identity-providers/github.md Co-authored-by: Elio Bischof <[email protected]> * Update docs/docs/guides/integrate/identity-providers/github.md Co-authored-by: Elio Bischof <[email protected]> * docs: add api idp docs * docs: reuse idp content (#5656) * docs: reuse idp content * docs: generalize prefill action * docs: eliminate prerequisites * Update docs/docs/guides/integrate/identity-providers/github.mdx Co-authored-by: Fabi <[email protected]> * replace zitadel google login * outdent optional action --------- Co-authored-by: Fabi <[email protected]> --------- Co-authored-by: Stefan Benz <[email protected]> Co-authored-by: Elio Bischof <[email protected]>
This commit is contained in:
Fabi
co-authored by
Elio Bischof
Stefan Benz
Elio Bischof
Stefan Benz
parent
080a44bbce
commit
d306e8219f
@@ -0,0 +1 @@
|
||||
Once you created the IdP, you need to activate it.
|
||||
@@ -0,0 +1,10 @@
|
||||
The login policy can be configured on two levels. Once as default on the instance and this can be overwritten for each organization.
|
||||
The only difference is where you configure it. Go either to the settings page of a specific organization or to the settings page of your instance.
|
||||
Instance: $YOUR-DOMAIN/ui/console/settings?id=general
|
||||
Organization: Choose the organization in the menu and go to $YOUR-DOMAIN/ui/console/org-settings?id=login
|
||||
|
||||
1. Go to the Settings
|
||||
2. Modify your login policy in the menu "Login Behavior and Security"
|
||||
3. Enable the attribute "External IDP allowed"
|
||||
|
||||
|
||||
@@ -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>
|
||||
|
||||
:::info
|
||||
Either account creation or account linking have to be enabled. Otherwise, the provider can't be used.
|
||||
:::
|
||||
@@ -0,0 +1,9 @@
|
||||
<p>This guides shows you how to connect {props.provider} as an identity provider in ZITADEL.</p>
|
||||
|
||||
:::info
|
||||
<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>
|
||||
:::
|
||||
@@ -0,0 +1,7 @@
|
||||
import CodeBlock from '@theme/CodeBlock';
|
||||
|
||||
<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 instance settings.
|
||||
If you overwrite the instance 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](/apis/openidoauth/authrequest) 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,108 @@
|
||||
---
|
||||
title: Configure Azure AD as Identity Provider
|
||||
sidebar_label: Azure AD
|
||||
---
|
||||
|
||||
import GeneralConfigDescription from './_general_config_description.mdx';
|
||||
import Intro from './_intro.mdx';
|
||||
import CustomLoginPolicy from './_custom_login_policy.mdx';
|
||||
import TestSetup from './_test_setup.mdx';
|
||||
import Activate from './_activate.mdx';
|
||||
|
||||
<Intro provider="Azure AD"/>
|
||||
|
||||
## Azure AD Configuration
|
||||
|
||||
You need to have access to an AzureAD 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 add the URL:
|
||||
- {your-domain}/ui/login/login/externalidp/callback
|
||||
- Example redirect url for the domain `https://acme-gzoe4x.zitadel.cloud` would look like this: `https://acme-gzoe4x.zitadel.cloud/ui/login/login/externalidp/callback`
|
||||
5. Save the Application (client) ID and the Directory (tenant) ID from the detail page
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
### 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, given_name 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
|
||||
|
||||
### Add custom login policy
|
||||
|
||||
<CustomLoginPolicy/>
|
||||
|
||||
### Create new Azure AD Provider
|
||||
|
||||
Go to the settings of your ZITADEL instance or the organization where you like to add a new **Azure AD** provider.
|
||||
Choose the **Microsoft** provider template.
|
||||
This template has everything you need preconfigured.
|
||||
You only have to add the client ID and secret, you have created in the step before.
|
||||
|
||||
You can configure the following settings if you like, 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`
|
||||
|
||||
**Email Verified**: Azure AD 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 Azure AD 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 Azure AD App.
|
||||
- Organizations: Choose organization if you have Azure AD 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 Azure AD App you have configured "Personal Microsoft accounts only")
|
||||
|
||||
**Tenant ID**: If you have selected either the *Organizations* or *Customers* as the *Tenant Type*, you have to enter the *Directory (Tenant) ID*, copied previously in the Azure App configuration, here.
|
||||
|
||||
<GeneralConfigDescription provider_account="Microsoft account" />
|
||||
|
||||
|
||||
|
||||
### Activate IdP
|
||||
|
||||
<Activate/>
|
||||
|
||||
|
||||
|
||||
## Test the setup
|
||||
|
||||
<TestSetup loginscreen="your Microsoft login"/>
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -1,8 +1,14 @@
|
||||
---
|
||||
title: Configure AzureAD as Identity Provider
|
||||
sidebar_label: AzureAD
|
||||
sidebar_label: AzureAD OIDC (Deprecated)
|
||||
---
|
||||
|
||||
:::caution deprecated
|
||||
|
||||
This configuration is based on the generic OIDC configuration. You can use the [Azure AD Template](./azure-ad) instead.
|
||||
|
||||
:::
|
||||
|
||||
## AzureAD Tenant as Identity Provider for ZITADEL
|
||||
|
||||
This guides shows you how to connect an AzureAD Tenant to ZITADEL.
|
||||
@@ -35,7 +41,6 @@ You can leave the second field empty since we will change this in the next step.
|
||||
For this to work you need to whitelist the redirect URIs from your ZITADEL Instance.
|
||||
In this example our test instance has the domain `test-qcon0h.zitadel.cloud`. In this case we need to whitelist these two entries:
|
||||
|
||||
- `https://test-qcon0h.zitadel.cloud/ui/login/register/externalidp/callback`
|
||||
- `https://test-qcon0h.zitadel.cloud/ui/login/login/externalidp/callback`
|
||||
|
||||
:::info
|
||||
|
||||
@@ -0,0 +1,90 @@
|
||||
---
|
||||
title: Configure GitHub as Identity Provider
|
||||
sidebar_label: GitHub
|
||||
---
|
||||
|
||||
import GeneralConfigDescription from './_general_config_description.mdx';
|
||||
import Intro from './_intro.mdx';
|
||||
import CustomLoginPolicy from './_custom_login_policy.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 provider="GitHub"/>
|
||||
|
||||
## GitHub Configuration
|
||||
|
||||
### Register a new 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
|
||||
|
||||
Fill in the application name and homepage URL.
|
||||
|
||||
You have to add the authorization callback URL, where GitHub should redirect, after the user has authenticated himself.
|
||||
In this example our test instance has the domain `https://acme-gzoe4x.zitadel.cloud`.
|
||||
This results in the following authorization callback URL:
|
||||
`https://acme-gzoe4x.zitadel.cloud/ui/login/login/externalidp/callback`
|
||||
|
||||
:::info
|
||||
To adapt this for you setup just replace the domain
|
||||
:::
|
||||
|
||||
|
||||
|
||||
### 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
|
||||
|
||||
### Add custom login policy
|
||||
|
||||
<CustomLoginPolicy/>
|
||||
|
||||
### Create new GitHub Provider
|
||||
|
||||
Go to the settings of your ZITADEL instance or the organization where you like to add a new GitHub provider.
|
||||
Choose the GitHub provider template. This template has everything you need preconfigured. You only have to add the client ID and secret, you have created in the step before.
|
||||
|
||||
You can configure the following settings if you like, 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.
|
||||
|
||||
<GeneralConfigDescription provider_account="GitHub account" />
|
||||
|
||||
|
||||
|
||||
### Activate IdP
|
||||
|
||||
<Activate/>
|
||||
|
||||
|
||||
|
||||
## Test the setup
|
||||
|
||||
<TestSetup loginscreen="your GitHub login"/>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<UnlinkedOAuth provider="GitHub"/>
|
||||
|
||||
|
||||
|
||||
## Optional: Add ZITADEL action to autofill userdata
|
||||
|
||||
<PrefillAction fields="firstname and lastname" provider="GitHub"/>
|
||||
|
||||
```js reference
|
||||
https://github.com/zitadel/actions/blob/main/examples/github_identity_provider.js
|
||||
```
|
||||
@@ -0,0 +1,92 @@
|
||||
---
|
||||
title: Configure GitLab as Identity Provider
|
||||
sidebar_label: GitLab
|
||||
---
|
||||
|
||||
import GeneralConfigDescription from './_general_config_description.mdx';
|
||||
import Intro from './_intro.mdx';
|
||||
import CustomLoginPolicy from './_custom_login_policy.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 provider="GitLab"/>
|
||||
|
||||
## GitLab Configuration
|
||||
|
||||
### Register a new application
|
||||
|
||||
1. Login to [gitlab.com](https://gitlab.com)
|
||||
2. Select [Edit Profile](https://gitlab.com/-/profile)
|
||||
3. Click on [Applications](https://gitlab.com/-/profile/applications) in the side navigation
|
||||
|
||||
For **GitLab Self-Hosted** go to your GitLab self-hosted instance and follow the same steps as for GitLab.
|
||||
|
||||
Fill in the application name.
|
||||
|
||||
You have to add the redirect URI, where GitLab should redirect, after the user has authenticated himself.
|
||||
In this example our test instance has the domain `https://acme-gzoe4x.zitadel.cloud`.
|
||||
This results in the following redirect URI:
|
||||
`https://acme-gzoe4x.zitadel.cloud/ui/login/login/externalidp/callback`
|
||||
|
||||
:::info
|
||||
To adapt this for you setup just replace the domain
|
||||
:::
|
||||
|
||||
|
||||
|
||||
### 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
|
||||
|
||||
### Add custom login policy
|
||||
|
||||
<CustomLoginPolicy/>
|
||||
|
||||
### Create new GitLab Provider
|
||||
|
||||
Go to the settings of your ZITADEL instance or the organization where you like to add a new Gitlab provider.
|
||||
Choose the GitLab provider template.
|
||||
This template has everything you need preconfigured.
|
||||
Add the client ID and secret you have created in the Gitlab Application.
|
||||
|
||||
You can configure the following settings if you like, 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 informations will be taken to create/update the user within ZITADEL.
|
||||
|
||||
<GeneralConfigDescription provider_account="GitLab account" />
|
||||
|
||||
|
||||
|
||||
### Activate IdP
|
||||
|
||||
<Activate/>
|
||||
|
||||
|
||||
|
||||
## Test the setup
|
||||
|
||||
<TestSetup loginscreen="your GitLab login"/>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<UnlinkedOAuth provider="GitLab"/>
|
||||
|
||||
|
||||
|
||||
## Optional: Add ZITADEL action to autofill userdata
|
||||
|
||||
<PrefillAction fields="firstname and lastname" provider="GitLab"/>
|
||||
|
||||
```js reference
|
||||
https://github.com/zitadel/actions/blob/main/examples/gitlab_identity_provider.js
|
||||
```
|
||||
@@ -1,8 +1,14 @@
|
||||
---
|
||||
title: Configure Google as Identity Provider
|
||||
sidebar_label: Google
|
||||
sidebar_label: Google OIDC (Deprecated)
|
||||
---
|
||||
|
||||
:::caution deprecated
|
||||
|
||||
This configuration is based on the generic OIDC configuration. You can use the [Google Template](./google) instead.
|
||||
|
||||
:::
|
||||
|
||||
## Register an external identity provider
|
||||
|
||||
In this step we will add a new Google identity provider to federate identities with ZITADEL.
|
||||
@@ -11,7 +17,6 @@ In this step we will add a new Google identity provider to federate identities w
|
||||
|
||||
1. Register an OIDC Client in your preferred provider
|
||||
2. Make sure you add the ZITADEL callback redirect uris
|
||||
- {your-domain}/ui/login/register/externalidp/callback
|
||||
- {your-domain}/ui/login/login/externalidp/callback
|
||||
|
||||
> **Information:** Make sure the provider is OIDC 1.0 compliant with a proper Discovery Endpoint
|
||||
|
||||
@@ -0,0 +1,64 @@
|
||||
---
|
||||
title: Configure Google as Identity Provider
|
||||
sidebar_label: Google
|
||||
---
|
||||
|
||||
import GeneralConfigDescription from './_general_config_description.mdx';
|
||||
import Intro from './_intro.mdx';
|
||||
import CustomLoginPolicy from './_custom_login_policy.mdx';
|
||||
import Activate from './_activate.mdx';
|
||||
import TestSetup from './_test_setup.mdx';
|
||||
|
||||
<Intro provider="Google"/>
|
||||
|
||||
## 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. Add the redirect uri
|
||||
- {your-domain}/ui/login/login/externalidp/callback
|
||||
- Example redirect url for the domain `https://acme-gzoe4x.zitadel.cloud` would look like this: `https://acme-gzoe4x.zitadel.cloud/ui/login/login/externalidp/callback`
|
||||
5. Save the Client ID and Client secret
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## ZITADEL Configuration
|
||||
|
||||
### Add custom login policy
|
||||
|
||||
<CustomLoginPolicy/>
|
||||
|
||||
### Create new Google Provider
|
||||
|
||||
Go to the settings of your ZITADEL instance or the organization where you want to add a new Google provider.
|
||||
Choose the Google provider template. This template has everything you need preconfigured.
|
||||
Add the client ID and secret created before on your Google App.
|
||||
|
||||
You can configure the following settings if you like, 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.
|
||||
|
||||
|
||||
<GeneralConfigDescription provider_account="Google account" />
|
||||
|
||||
|
||||
|
||||
### Activate IdP
|
||||
|
||||
<Activate/>
|
||||
|
||||
|
||||
|
||||
## Test the setup
|
||||
|
||||
<TestSetup loginscreen="your Google login"/>
|
||||
|
||||
<!-- TODO: Image highlights GitHub -->
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,74 @@
|
||||
---
|
||||
title: Configure LDAP as Identity Provider
|
||||
sidebar_label: LDAP
|
||||
---
|
||||
|
||||
import GeneralConfigDescription from './_general_config_description.mdx';
|
||||
import Intro from './_intro.mdx';
|
||||
import CustomLoginPolicy from './_custom_login_policy.mdx';
|
||||
import Activate from './_activate.mdx';
|
||||
import TestSetup from './_test_setup.mdx';
|
||||
|
||||
<Intro provider="an LDAP server"/>
|
||||
|
||||
## ZITADEL Configuration
|
||||
|
||||
### Add custom login policy
|
||||
|
||||
<CustomLoginPolicy/>
|
||||
|
||||
### Resulting process to connect LDAP
|
||||
|
||||
When you wnat to use a LDAP provider in ZITADEL, the following process is followed to login:
|
||||
|
||||
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
|
||||
|
||||
### Create new LDAP Provider
|
||||
|
||||
Go to the settings of your ZITADEL instance or the organization where you like to add a new LDAP provider.
|
||||
Choose the LDAP provider template.
|
||||
|
||||
To configure the LDAP template please fill out the following fields:
|
||||
|
||||
**Name**: Name of the identity provider
|
||||
|
||||
**Servers**: List of servers in a format of "schema://host:port", as example "ldap://localhost:389", if TLS should be used then 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.
|
||||
|
||||
**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 provider_account="LDAP user" />
|
||||
|
||||
|
||||
|
||||
### Activate IdP
|
||||
|
||||
<Activate/>
|
||||
|
||||
|
||||
|
||||
## Test the setup
|
||||
|
||||
<TestSetup loginscreen="ZITADELs LDAP login"/>
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,185 @@
|
||||
---
|
||||
title: Configure local OpenLDAP as Identity Provider
|
||||
sidebar_label: Local OpenLDAP
|
||||
---
|
||||
|
||||
import GeneralConfigDescription from './_general_config_description.mdx';
|
||||
import Intro from './_intro.mdx';
|
||||
import CustomLoginPolicy from './_custom_login_policy.mdx';
|
||||
import Activate from './_activate.mdx';
|
||||
import TestSetup from './_test_setup.mdx';
|
||||
|
||||
<Intro provider="a local OpenLDAP server"/>
|
||||
|
||||
## OpenLDAP Configuration
|
||||
|
||||
### Basic configuration
|
||||
|
||||
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
|
||||
|
||||
### Add custom login policy
|
||||
|
||||
<CustomLoginPolicy/>
|
||||
|
||||
### Create new LDAP Provider
|
||||
|
||||
Go to the settings of your ZITADEL instance or the organization where you like to add a new LDAP provider.
|
||||
Choose the LDAP provider template.
|
||||
|
||||
To get basic information on what is possible to configure, please refer to the [LDAP guide](./ldap).
|
||||
To configure the LDAP template to work with the before configured OpenLDAP, please fill out the following fields:
|
||||
|
||||
**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 provider_account="LDAP user" />
|
||||
|
||||
|
||||
|
||||
### Activate IdP
|
||||
|
||||
<Activate/>
|
||||
|
||||
|
||||
|
||||
## Test the setup
|
||||
|
||||
<TestSetup loginscreen="ZITADELs LDAP login"/>
|
||||
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user