TheArchive/zitadel
1
0
Fork 0
mirror of https://github.com/zitadel/zitadel.git synced 2025-03-01 01:07:23 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: improve idp docs (#5677)

Browse Source 
* docs: improve idp docs

* warn about clear text ldap
This commit is contained in:
Elio Bischof 2023-04-13 17:11:51 +02:00 committed by GitHub
parent 24e3695e08
commit 8745c87ded
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 88 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
docs/docs/guides/integrate/identity-providers/_activate.mdx
View File

@ -1 +1,2 @@
Once you created the IdP, you need to activate it.
Once you created the provider, it is listed in the providers overview.
Activate it by selecting the tick with the tooltip *set as available*.

8
docs/docs/guides/integrate/identity-providers/_how_ldap_idp_works.mdx Normal file
View File

@ -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

8
docs/docs/guides/integrate/identity-providers/_idps_overview.mdx Normal file
View File

@ -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.
![Identity Provider Overview](/img/guides/zitadel_identity_provider_overview.png)
<p>Select the {props.templates} Provider template.</p>

11
docs/docs/guides/integrate/identity-providers/azure-ad.mdx
View File

@ -6,6 +6,7 @@ sidebar_label: Azure AD
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';
@ -64,11 +65,13 @@ To be able to get all the information that ZITADEL needs, you have to configure
<CustomLoginPolicy/>
### Create new Azure AD Provider
### Go to the IdP Providers Overview
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.
<IDPsOverview templates="Microsoft"/>
### Create a new Azure AD Provider
The Microsoft 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:

10
docs/docs/guides/integrate/identity-providers/github.mdx
View File

@ -6,6 +6,7 @@ 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';
@ -49,10 +50,13 @@ Make sure to save the secret, as you will not be able to show it again.
<CustomLoginPolicy/>
### Create new GitHub Provider
### Go to the IdP Providers Overview
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.
<IDPsOverview templates="GitHub or GitHub Enterprise"/>
### Create a new GitHub Provider
The GitHub provider templates have 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:

11
docs/docs/guides/integrate/identity-providers/gitlab.mdx
View File

@ -6,6 +6,7 @@ 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';
@ -50,11 +51,13 @@ Save the ID and the Secret, you will not be able to copy the secret again, if yo
<CustomLoginPolicy/>
### Create new GitLab Provider
### Go to the IdP Providers Overview
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.
<IDPsOverview templates="GitLab or GitLab Self Hosted"/>
### Create a new GitLab Provider
The GitLab provider templates have 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:

10
docs/docs/guides/integrate/identity-providers/google.mdx
View File

@ -6,6 +6,7 @@ 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';
@ -33,10 +34,13 @@ import TestSetup from './_test_setup.mdx';
<CustomLoginPolicy/>
### Create new Google Provider
### Go to the IdP Providers Overview
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.
<IDPsOverview templates="Google"/>
### Create a new Google Provider
The Google provider 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:

33
docs/docs/guides/integrate/identity-providers/ldap.mdx
View File

@ -3,41 +3,42 @@ title: Configure LDAP as Identity Provider
sidebar_label: LDAP
---
import GeneralConfigDescription from './_general_config_description.mdx';
import Intro from './_intro.mdx';
import HowLDAPIDPWorks from './_how_ldap_idp_works.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';
<Intro provider="an LDAP server"/>
## How it works
<HowLDAPIDPWorks/>
## ZITADEL Configuration
### Add custom login policy
<CustomLoginPolicy/>
### Resulting process to connect LDAP
### Go to the IdP Providers Overview
When you wnat to use a LDAP provider in ZITADEL, the following process is followed to login:
<IDPsOverview templates="Active Directory / LDAP"/>
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 a new LDAP Provider
### Create new LDAP Provider
Fill in the following fields in the LDAP template.
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:
:::caution
We highly recommend to use LDAPS or StartTLS enable servers.
Otherwise, your users passwords are sent in clear text through the wire.
:::
**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.
**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
@ -51,7 +52,7 @@ To configure the LDAP template please fill out the following fields:
**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.
**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.

31
docs/docs/guides/integrate/identity-providers/openldap.mdx
View File

@ -3,14 +3,33 @@ title: Configure local OpenLDAP as Identity Provider
sidebar_label: Local OpenLDAP
---
import GeneralConfigDescription from './_general_config_description.mdx';
import Intro from './_intro.mdx';
import HowLDAPIDPWorks from './_how_ldap_idp_works.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';
:::caution
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](/docs/self-hosting/deploy/compose).
:::
:::caution
Beware that this example configuration neighter 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.
:::
<Intro provider="a local OpenLDAP server"/>
## How it works
<HowLDAPIDPWorks/>
## OpenLDAP Configuration
### Basic configuration
@ -135,13 +154,13 @@ ldapadd -x -h localhost -D "cn=admin,dc=example,dc=com" -f example.ldif -w 'Pass
<CustomLoginPolicy/>
### Create new LDAP Provider
### Go to the IdP Providers Overview
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.
<IDPsOverview templates="Active Directory / LDAP"/>
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:
### 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