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 <elio@zitadel.com>

* Update docs/docs/guides/integrate/identity-providers/azure-ad.md

Co-authored-by: Elio Bischof <elio@zitadel.com>

* Update docs/docs/guides/integrate/identity-providers/azure-ad.md

Co-authored-by: Elio Bischof <elio@zitadel.com>

* Update docs/docs/guides/integrate/identity-providers/azure-ad.md

Co-authored-by: Elio Bischof <elio@zitadel.com>

* Update docs/docs/guides/integrate/identity-providers/azure-ad.md

Co-authored-by: Elio Bischof <elio@zitadel.com>

* Update docs/docs/guides/integrate/identity-providers/azure-ad.md

Co-authored-by: Elio Bischof <elio@zitadel.com>

* Update docs/docs/guides/integrate/identity-providers/azure-ad.md

Co-authored-by: Elio Bischof <elio@zitadel.com>

* Update docs/docs/guides/integrate/identity-providers/azure-ad.md

Co-authored-by: Elio Bischof <elio@zitadel.com>

* Update docs/docs/guides/integrate/identity-providers/azure-ad.md

Co-authored-by: Elio Bischof <elio@zitadel.com>

* Update docs/docs/guides/integrate/identity-providers/azure-ad.md

Co-authored-by: Elio Bischof <elio@zitadel.com>

* Update docs/docs/guides/integrate/identity-providers/azure-ad.md

Co-authored-by: Elio Bischof <elio@zitadel.com>

* Update docs/docs/guides/integrate/identity-providers/azure-ad.md

Co-authored-by: Elio Bischof <elio@zitadel.com>

* 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 <elio@zitadel.com>

* Update docs/docs/guides/integrate/identity-providers/github.md

Co-authored-by: Elio Bischof <elio@zitadel.com>

* Update docs/docs/guides/integrate/identity-providers/github.md

Co-authored-by: Elio Bischof <elio@zitadel.com>

* Update docs/docs/guides/integrate/identity-providers/github.md

Co-authored-by: Elio Bischof <elio@zitadel.com>

* 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 <fabienne.gerschwiler@gmail.com>

* replace zitadel google login

* outdent optional action

---------

Co-authored-by: Fabi <fabienne.gerschwiler@gmail.com>

---------

Co-authored-by: Stefan Benz <stefan@caos.ch>
Co-authored-by: Elio Bischof <elio@zitadel.com>

console/src/assets/i18n/de.json

@@ -1699,7 +1699,7 @@
     "AZUREADTENANTTYPES": {
       "0": "Common",
       "1": "Organizations",
-      "2": "Customers"
+      "2": "Consumers"
     },
     "ADD": "Identitätsanbieter hinzufügen",
     "AZUREADTENANTTYPE": "Tenant Typ",

console/src/assets/i18n/en.json

@@ -1695,7 +1695,7 @@
     "AZUREADTENANTTYPES": {
       "0": "Common",
       "1": "Organizations",
-      "2": "Customers"
+      "2": "Consumers"
     },
     "AZUREADTENANTTYPE": "Tenant Type",
     "AZUREADTENANTID": "Tenant ID",

console/src/assets/i18n/fr.json

@@ -1703,7 +1703,7 @@
     "AZUREADTENANTTYPES": {
       "0": "Common",
       "1": "Organizations",
-      "2": "Customers"
+      "2": "Consumers"
     },
     "AZUREADTENANTTYPE": "Type de locataire",
     "AZUREADTENANTID": "ID du locataire",

console/src/assets/i18n/it.json

@@ -1704,7 +1704,7 @@
     "AZUREADTENANTTYPES": {
       "0": "Common",
       "1": "Organizations",
-      "2": "Customers"
+      "2": "Consumers"
     },
     "ADD": "Aggiungi fornitore di identità",
     "AZUREADTENANTTYPE": "Tipo tenant",

console/src/assets/i18n/pl.json

@@ -1703,7 +1703,7 @@
     "AZUREADTENANTTYPES": {
       "0": "Common",
       "1": "Organizations",
-      "2": "Customers"
+      "2": "Consumers"
     },
     "AZUREADTENANTTYPE": "Rodzaj najemcy",
     "AZUREADTENANTID": "Identyfikator najemcy",

console/src/assets/i18n/zh.json

@@ -1702,7 +1702,7 @@
     "AZUREADTENANTTYPES": {
       "0": "Common",
       "1": "Organizations",
-      "2": "Customers"
+      "2": "Consumers"
     },
     "AZUREADTENANTTYPE": "租户类型",
     "AZUREADTENANTID": "租户编号",

docs/README.md

@@ -12,6 +12,13 @@ To add a new site to the already existing structure simply save the `md` file in
 yarn install
 ```
 
+## Generate
+
+```
+yarn generate
+```
+
+
 ## Local Development
 
 ```

docs/docs/guides/integrate/identity-providers/_activate.mdx

@@ -0,0 +1 @@
+Once you created the IdP, you need to activate it.

docs/docs/guides/integrate/identity-providers/_custom_login_policy.mdx

@@ -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"
+
+![Allow External IDP](/img/guides/zitadel_allow_external_idp.png)

docs/docs/guides/integrate/identity-providers/_general_config_description.mdx

@@ -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.
+:::

docs/docs/guides/integrate/identity-providers/_intro.mdx

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

docs/docs/guides/integrate/identity-providers/_prefill_action.mdx

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

docs/docs/guides/integrate/identity-providers/_test_setup.mdx

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

docs/docs/guides/integrate/identity-providers/_unlinked_oauth.mdx

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

docs/docs/guides/integrate/identity-providers/azure-ad.mdx

@@ -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
+
+![Azure App Registration](/img/guides/azure_app_registration.png)
+
+![Azure Client ID and Tenant ID](/img/guides/azure_client_tenant_id.png)
+
+### 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
+
+![Azure Client Secret](/img/guides/azure_client_secret.png)
+
+### 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
+
+![Azure Token configuration](/img/guides/azure_token_configuration.png)
+
+### 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"
+
+![Azure API permissions](/img/guides/azure_api_permissions.png)
+
+## 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" />
+
+![Azure Provider](/img/guides/zitadel_azure_provider.png)
+
+### Activate IdP
+
+<Activate/>
+
+![Activate Azure AD](/img/guides/zitadel_activate_azure.png)
+
+## Test the setup
+
+<TestSetup loginscreen="your Microsoft login"/>
+
+![Azure AD Button](/img/guides/zitadel_login_azure.png)
+
+![Azure AD Login](/img/guides/microsoft_login.png)

docs/docs/guides/integrate/identity-providers/azuread-oidc.md

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

docs/docs/guides/integrate/identity-providers/github.mdx

@@ -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
+:::
+
+![Register an OAuth application](/img/guides/github_oauth_app_registration.png)
+
+### 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.
+
+![Client ID and Secret](/img/guides/github_oauth_client_id_secret.png)
+
+## 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" />
+
+![GitHub Provider](/img/guides/zitadel_github_create_provider.png)
+
+### Activate IdP
+
+<Activate/>
+
+![Activate the GitHub](/img/guides/zitadel_activate_github.png)
+
+## Test the setup
+
+<TestSetup loginscreen="your GitHub login"/>
+
+![GitHub Button](/img/guides/zitadel_login_github.png)
+
+![GitHub Login](/img/guides/github_login.png)
+
+<UnlinkedOAuth provider="GitHub"/>
+
+![GitHub Login](/img/guides/zitadel_login_external_not_found_registration.png)
+
+## 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
+```

docs/docs/guides/integrate/identity-providers/gitlab.mdx

@@ -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
+:::
+
+![Register an OAuth application](/img/guides/gitlab_app_registration.png)
+
+### 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.
+
+![Client ID and Secret](/img/guides/gitlab_app_id_secret.png)
+
+## 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" />
+
+![GitLab Provider](/img/guides/zitadel_gitlab_create_provider.png)
+
+### Activate IdP
+
+<Activate/>
+
+![Activate the GitLab](/img/guides/zitadel_activate_gitlab.png)
+
+## Test the setup
+
+<TestSetup loginscreen="your GitLab login"/>
+
+![GitLab Button](/img/guides/zitadel_login_gitlab.png)
+
+![GitLab Login](/img/guides/gitlab_login.png)
+
+<UnlinkedOAuth provider="GitLab"/>
+
+![GitLab Login](/img/guides/zitadel_login_external_not_found_registration.png)
+
+## 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
+```

docs/docs/guides/integrate/identity-providers/google-oidc.mdx

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

docs/docs/guides/integrate/identity-providers/google.mdx

@@ -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
+
+![Google OAuth App Registration](/img/guides/google_oauth_app_registration.png)
+
+![Google Client ID and Secret](/img/guides/google_client_id_secret.png)
+
+## 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" />
+
+![Google Provider](/img/guides/zitadel_google_create_provider.png)
+
+### Activate IdP
+
+<Activate/>
+
+![Activate the Google Provider](/img/guides/zitadel_activate_google.png)
+
+## Test the setup
+
+<TestSetup loginscreen="your Google login"/>
+
+<!-- TODO: Image highlights GitHub -->
+![Google Button](/img/guides/zitadel_login_google.png)
+
+![Google Login](/img/guides/google_login.png)

docs/docs/guides/integrate/identity-providers/ldap.mdx

@@ -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 user@example.com and filters "uid" and "email" the resulting SearchQuery contains "(|(uid=user@example.com)(email=user@example.com))"
+
+**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" />
+
+![LDAP Provider](/img/guides/zitadel_ldap_create_provider.png)
+
+### Activate IdP
+
+<Activate/>
+
+![Activate the LDAP Provider](/img/guides/zitadel_activate_ldap.png)
+
+## Test the setup
+
+<TestSetup loginscreen="ZITADELs LDAP login"/>
+
+![LDAP Button](/img/guides/zitadel_login_ldap.png)
+
+![LDAP Login](/img/guides/zitadel_login_ldap_input.png)

docs/docs/guides/integrate/identity-providers/openldap.mdx

@@ -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: test@example.com
+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" />
+
+![LDAP Provider](/img/guides/zitadel_ldap_create_provider.png)
+
+### Activate IdP
+
+<Activate/>
+
+![Activate the LDAP Provider](/img/guides/zitadel_activate_ldap.png)
+
+## Test the setup
+
+<TestSetup loginscreen="ZITADELs LDAP login"/>
+
+![LDAP Button](/img/guides/zitadel_login_ldap.png)
+
+![LDAP Login](/img/guides/zitadel_login_ldap_input.png)

docs/sidebars.js

@@ -126,12 +126,6 @@ module.exports = {
     {
       type: "category",
       label: "Integrate",
-      collapsed: true,
-      link: {
-        type: 'generated-index',
-        title: 'Overview',
-        slug: 'guides/integrate',
-      },
       items: [
 
         {
@@ -150,6 +144,12 @@ module.exports = {
           collapsed: true,
           items: [
             "guides/integrate/identity-providers/introduction",
+            "guides/integrate/identity-providers/google",
+            "guides/integrate/identity-providers/azure-ad",
+            "guides/integrate/identity-providers/github",
+            "guides/integrate/identity-providers/gitlab",
+            "guides/integrate/identity-providers/ldap",
+            "guides/integrate/identity-providers/openldap",
             "guides/integrate/identity-providers/google-oidc",
             "guides/integrate/identity-providers/azuread-oidc",
           ],
@@ -294,7 +294,7 @@ module.exports = {
             title: "Auth API",
             slug: "/apis/auth",
             description:
-                "The authentication API (aka Auth API) is used for all operations on the currently logged in user. The user id is taken from the sub claim in the token.",
+              "The authentication API (aka Auth API) is used for all operations on the currently logged in user. The user id is taken from the sub claim in the token.",
 
           },
           items: require("./docs/apis/auth/sidebar.js"),
@@ -307,7 +307,7 @@ module.exports = {
             title: "Management API",
             slug: "/apis/mgmt",
             description:
-                "The management API is as the name states the interface where systems can mutate IAM objects like, organizations, projects, clients, users and so on if they have the necessary access rights. To identify the current organization you can send a header x-zitadel-orgid or if no header is set, the organization of the authenticated user is set.",
+              "The management API is as the name states the interface where systems can mutate IAM objects like, organizations, projects, clients, users and so on if they have the necessary access rights. To identify the current organization you can send a header x-zitadel-orgid or if no header is set, the organization of the authenticated user is set.",
           },
           items: require("./docs/apis/mgmt/sidebar.js"),
         },
@@ -319,7 +319,7 @@ module.exports = {
             title: "Admin API",
             slug: "/apis/admin",
             description:
-                "This API is intended to configure and manage one ZITADEL instance itself.",
+              "This API is intended to configure and manage one ZITADEL instance itself.",
           },
           items: require("./docs/apis/admin/sidebar.js"),
         },
@@ -331,9 +331,9 @@ module.exports = {
             title: "System API",
             slug: "/apis/system",
             description:
-                "This API is intended to manage the different ZITADEL instances within the system.\n" +
-                "\n" +
-                "Checkout the guide how to access the ZITADEL System API.",
+              "This API is intended to manage the different ZITADEL instances within the system.\n" +
+              "\n" +
+              "Checkout the guide how to access the ZITADEL System API.",
           },
           items: require("./docs/apis/system/sidebar.js"),
         },

proto/zitadel/idp.proto

@@ -237,10 +237,18 @@ enum IDPFieldName {
 }
 
 message Provider {
-    string id = 1;
+    string id = 1 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"69629023906488334\"";
+        }
+    ];
     zitadel.v1.ObjectDetails details = 2;
     IDPState state = 3;
-    string name = 4;
+    string name = 4 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"Google\"";
+        }
+    ];
     IDPOwnerType owner = 5;
     ProviderType type = 6;
     ProviderConfig config = 7;
@@ -277,48 +285,143 @@ message ProviderConfig {
 }
 
 message OAuthConfig {
-    string client_id = 1;
-    string authorization_endpoint = 2;
-    string token_endpoint = 3;
-    string user_endpoint = 4;
-    repeated string scopes = 5;
-    string id_attribute = 6;
+    string client_id = 1 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"client-id\"";
+            description: "client id generated by the identity provider";
+        }
+    ];
+    string authorization_endpoint = 2 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"https://accounts.google.com/o/oauth2/v2/auth\"";
+            description: "the endpoint where ZITADEL send the user to authenticate";
+        }
+    ];
+    string token_endpoint = 3 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"https://oauth2.googleapis.com/token\"";
+            description: "the endpoint where ZITADEL can get the token";
+        }
+    ];
+    string user_endpoint = 4 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"https://openidconnect.googleapis.com/v1/userinfo\"";
+            description: "the endpoint where ZITADEL can get the user information";
+        }
+    ];
+    repeated string scopes = 5 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "[\"openid\", \"profile\", \"email\"]";
+            description: "the scopes requested by ZITADEL during the request on the identity provider";
+        }
+    ];
+    string id_attribute = 6 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"user_id\"";
+            description: "defines how the attribute is called where ZITADEL can get the id of the user";
+        }
+    ];
 }
 
 message GenericOIDCConfig {
-    string issuer = 1;
-    string client_id = 2;
-    repeated string scopes = 3;
+    string issuer = 1 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"https://accounts.google.com/\"";
+            description: "the OIDC issuer of the identity provider";
+        }
+    ];
+    string client_id = 2 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"client-id\"";
+            description: "client id generated by the identity provider";
+        }
+    ];
+    repeated string scopes = 3 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "[\"openid\", \"profile\", \"email\"]";
+            description: "the scopes requested by ZITADEL during the request on the identity provider";
+        }
+    ];
     bool is_id_token_mapping = 4;
 }
 
 message GitHubConfig {
-    string client_id = 1;
-    repeated string scopes = 2;
+    string client_id = 1 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"client-id\"";
+            description: "the client ID of the GitHub App";
+        }
+    ];
+    repeated string scopes = 2 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "[\"openid\", \"profile\", \"email\"]";
+            description: "the scopes requested by ZITADEL during the request to GitHub";
+        }
+    ];
 }
 
 message GitHubEnterpriseServerConfig {
-    string client_id = 1;
+    string client_id = 1 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"client-id\"";
+            description: "the client ID of the GitHub App";
+        }
+    ];
     string authorization_endpoint = 2;
     string token_endpoint = 3;
     string user_endpoint = 4;
-    repeated string scopes = 5;
+    repeated string scopes = 5 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "[\"openid\", \"profile\", \"email\"]";
+            description: "the scopes requested by ZITADEL during the request to GitHub";
+        }
+    ];
 }
 
 message GoogleConfig {
-    string client_id = 1;
-    repeated string scopes = 2;
+    string client_id = 1 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"client-id\"";
+            description: "client id of the Google application";
+        }
+    ];
+    repeated string scopes = 2 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "[\"openid\", \"profile\", \"email\"]";
+            description: "the scopes requested by ZITADEL during the request to Google";
+        }
+    ];
 }
 
 message GitLabConfig {
-    string client_id = 1;
-    repeated string scopes = 2;
+    string client_id = 1 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"client-id\"";
+            description: "client id of the GitLab application";
+        }
+    ];
+    repeated string scopes = 2 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "[\"openid\", \"profile\", \"email\"]";
+            description: "the scopes requested by ZITADEL during the request to GitLab";
+        }
+    ];
 }
 
 message GitLabSelfHostedConfig {
     string issuer = 1;
-    string client_id = 2;
-    repeated string scopes = 3;
+    string client_id = 2 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"client-id\"";
+            description: "client id of the GitLab application";
+        }
+    ];
+    repeated string scopes = 3 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "[\"openid\", \"profile\", \"email\"]";
+            description: "the scopes requested by ZITADEL during the request to GitLab";
+        }
+    ];
 }
 
 message LDAPConfig {
@@ -334,17 +437,51 @@ message LDAPConfig {
 }
 
 message AzureADConfig {
-    string client_id = 1;
-    AzureADTenant tenant = 2;
-    bool email_verified = 3;
-    repeated string scopes = 4;
+    string client_id = 1 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"client-id\"";
+            description: "client id of the Azure AD application";
+        }
+    ];
+    AzureADTenant tenant = 2 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "Defines what user accounts should be able to login (Personal, Organizational, All)";
+        }
+    ];
+    bool email_verified = 3 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "Azure AD doesn't send if the email has been verified. Enable this if the user email should always be added verified in ZITADEL (no verification emails will be sent)";
+        }
+    ];
+    repeated string scopes = 4 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "[\"openid\", \"profile\", \"email\", \"User.Read\"]";
+            description: "the scopes requested by ZITADEL during the request to Azure AD";
+        }
+    ];
 }
 
 message Options {
-    bool is_linking_allowed = 1;
-    bool is_creation_allowed = 2;
-    bool is_auto_creation = 3;
-    bool is_auto_update = 4;
+    bool is_linking_allowed = 1 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "Enable if users should be able to link an existing ZITADEL user with an external account.";
+        }
+    ];
+    bool is_creation_allowed = 2 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "Enable if users should be able to create a new account in ZITADEL when using an external account.";
+        }
+    ];
+    bool is_auto_creation = 3 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "Enable if a new account in ZITADEL should be created automatically when login with an external account.";
+        }
+    ];
+    bool is_auto_update = 4 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "Enable if a the ZITADEL account fields should be updated automatically on each login.";
+        }
+    ];
 }
 
 message LDAPAttributes {