From 8745c87ded7e6c3c9ca3762021906274d4534d83 Mon Sep 17 00:00:00 2001 From: Elio Bischof Date: Thu, 13 Apr 2023 17:11:51 +0200 Subject: [PATCH] docs: improve idp docs (#5677) * docs: improve idp docs * warn about clear text ldap --- .../identity-providers/_activate.mdx | 3 +- .../_how_ldap_idp_works.mdx | 8 +++++ .../identity-providers/_idps_overview.mdx | 8 +++++ .../integrate/identity-providers/azure-ad.mdx | 11 ++++--- .../integrate/identity-providers/github.mdx | 10 ++++-- .../integrate/identity-providers/gitlab.mdx | 11 ++++--- .../integrate/identity-providers/google.mdx | 10 ++++-- .../integrate/identity-providers/ldap.mdx | 33 ++++++++++--------- .../integrate/identity-providers/openldap.mdx | 31 +++++++++++++---- 9 files changed, 88 insertions(+), 37 deletions(-) create mode 100644 docs/docs/guides/integrate/identity-providers/_how_ldap_idp_works.mdx create mode 100644 docs/docs/guides/integrate/identity-providers/_idps_overview.mdx diff --git a/docs/docs/guides/integrate/identity-providers/_activate.mdx b/docs/docs/guides/integrate/identity-providers/_activate.mdx index 1ddfeab8e..689d35cb7 100644 --- a/docs/docs/guides/integrate/identity-providers/_activate.mdx +++ b/docs/docs/guides/integrate/identity-providers/_activate.mdx @@ -1 +1,2 @@ -Once you created the IdP, you need to activate it. \ No newline at end of file +Once you created the provider, it is listed in the providers overview. +Activate it by selecting the tick with the tooltip *set as available*. \ No newline at end of file diff --git a/docs/docs/guides/integrate/identity-providers/_how_ldap_idp_works.mdx b/docs/docs/guides/integrate/identity-providers/_how_ldap_idp_works.mdx new file mode 100644 index 000000000..dcba962dc --- /dev/null +++ b/docs/docs/guides/integrate/identity-providers/_how_ldap_idp_works.mdx @@ -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 diff --git a/docs/docs/guides/integrate/identity-providers/_idps_overview.mdx b/docs/docs/guides/integrate/identity-providers/_idps_overview.mdx new file mode 100644 index 000000000..cee2718c1 --- /dev/null +++ b/docs/docs/guides/integrate/identity-providers/_idps_overview.mdx @@ -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) + +

Select the {props.templates} Provider template.

\ No newline at end of file diff --git a/docs/docs/guides/integrate/identity-providers/azure-ad.mdx b/docs/docs/guides/integrate/identity-providers/azure-ad.mdx index c61773540..0df515284 100644 --- a/docs/docs/guides/integrate/identity-providers/azure-ad.mdx +++ b/docs/docs/guides/integrate/identity-providers/azure-ad.mdx @@ -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 -### 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. + + +### 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: diff --git a/docs/docs/guides/integrate/identity-providers/github.mdx b/docs/docs/guides/integrate/identity-providers/github.mdx index aa58ee6dd..749bb915b 100644 --- a/docs/docs/guides/integrate/identity-providers/github.mdx +++ b/docs/docs/guides/integrate/identity-providers/github.mdx @@ -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. -### 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. + + +### 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: diff --git a/docs/docs/guides/integrate/identity-providers/gitlab.mdx b/docs/docs/guides/integrate/identity-providers/gitlab.mdx index 25e8e19a5..64600dbd4 100644 --- a/docs/docs/guides/integrate/identity-providers/gitlab.mdx +++ b/docs/docs/guides/integrate/identity-providers/gitlab.mdx @@ -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 -### 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. + + +### 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: diff --git a/docs/docs/guides/integrate/identity-providers/google.mdx b/docs/docs/guides/integrate/identity-providers/google.mdx index ad8ba0625..9fd0ff7ab 100644 --- a/docs/docs/guides/integrate/identity-providers/google.mdx +++ b/docs/docs/guides/integrate/identity-providers/google.mdx @@ -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'; -### 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. + + +### 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: diff --git a/docs/docs/guides/integrate/identity-providers/ldap.mdx b/docs/docs/guides/integrate/identity-providers/ldap.mdx index 632752aab..fb573cfcf 100644 --- a/docs/docs/guides/integrate/identity-providers/ldap.mdx +++ b/docs/docs/guides/integrate/identity-providers/ldap.mdx @@ -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'; +## How it works + + + ## ZITADEL Configuration ### Add custom login policy -### 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: + -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. diff --git a/docs/docs/guides/integrate/identity-providers/openldap.mdx b/docs/docs/guides/integrate/identity-providers/openldap.mdx index 95b7a7b67..3b3c04513 100644 --- a/docs/docs/guides/integrate/identity-providers/openldap.mdx +++ b/docs/docs/guides/integrate/identity-providers/openldap.mdx @@ -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. +::: + +## How it works + + + ## OpenLDAP Configuration ### Basic configuration @@ -135,13 +154,13 @@ ldapadd -x -h localhost -D "cn=admin,dc=example,dc=com" -f example.ldif -w 'Pass -### 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. + -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