feat(console): guide users when configuring IDPs (#7572)

* feat(console): show external idp remote config

* reuse copy-row

* finish google and saml sp

* finish apps

* add next steps modal

* rollout

* activate

* fix saml urls

* fix saml provider

* complete providers

* translate

* update google docs

* update entra id oidc docs

* update entra id saml docs

* update github docs

* update gitlab docs

* update apple docs

* update okta oidc docs

* update okta saml docs

* update keycloak docs

* update mocksaml

* cleanup

* lint

* lint

* fix overriden classes

* encapsulate styles

* fix icon classes

---------

Co-authored-by: peintnermax <max@caos.ch>

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

@@ -1,9 +1,6 @@
-The login policy can be configured on two levels. Once in the default settings 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 default settings page.
-Default Settings: $YOUR-DOMAIN/ui/console/instance?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
+    - To allow external IdP logins by default, go to your instance default settings at `$YOUR-DOMAIN/ui/console/instance?id=general`
+    - To allow external IdP logins on an organization, go to `$YOUR-DOMAIN/ui/console/org-settings?id=login` and ensure you have the right org context.
 2. Modify your login policy in the menu "Login Behavior and Security"
 3. Enable the attribute "External Login allowed"
 

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

@@ -1,8 +0,0 @@
-The Generic OIDC Provider allows you to configure any OIDC compliant identity providers.
-
-The following information you need to fill out by yourself:
-
-<li><b>Name</b> {props.name}</li>
-<li><b>Issuer</b> {props.issuer}</li>
-<li><b>Client-ID</b> {props.clientid}</li>
-<li><b>Scopes</b>: (openid, profile, email is preconfigured)</li>

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

@@ -12,6 +12,15 @@ import TestSetup from './_test_setup.mdx';
 
 <Intro provider="Apple"/>
 
+## Open the Apple Identity Provider Template
+
+<IDPsOverview templates="Apple"/>
+
+Click on the ZITADEL Callback URL to copy it to your clipboard.
+You will have to paste it in the Apple service later.
+
+![Apple Provider](/img/guides/zitadel_apple_create_provider.png)
+
 ## Apple Configuration
 
 ### Register a new App
@@ -32,13 +41,10 @@ import TestSetup from './_test_setup.mdx';
 6. Choose the previously created App in the Primary App ID List
 7. Add your custom domain in the domains and subdomains field
  - Example domain for `https://acme-gzoe4x.zitadel.cloud` would look like this:  `acme-gzoe4x.zitadel.cloud`
-8. Add the redirect uri in the Return URLs
- - {your-domain}/ui/login/login/externalidp/callback/form
- - 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/form`
+8. [Paste the ZITADEL Callback URL you copied before](#open-the-apple-identity-provider-template) to the Return URLs
 
 ![Apple Service](/img/guides/apple_service_create.png)
 
-
 ### Register a new key
 
 1. Go to the keys list of your Apple Developer Account: [https://developer.apple.com/account/resources/authkeys/list](https://developer.apple.com/account/resources/authkeys/list)
@@ -50,34 +56,29 @@ import TestSetup from './_test_setup.mdx';
 
 ## ZITADEL Configuration
 
-### Add custom login policy
+Go back [to the Apple provider template you opened before in ZITADEL](#open-the-apple-identity-provider-template).
 
-<CustomLoginPolicy/>
-
-### Go to the IdP Providers Overview
-
-<IDPsOverview templates="Apple"/>
-
-### Create a new Apple Provider
-
-1. Add the Client ID, this is the identifier of the service you created in your Apple Account
+1. Add the Client ID, this is [the identifier of the service you created in your Apple Account](#register-a-new-service)
 2. Fill the Team ID, you can find it when you login to your Apple Developer account, in your membership
-3. Enter the Key ID and upload the Private Key you previously created
+3. Enter the [Key ID and upload the Private Key you created before](#register-a-new-key)
 
-You can configure the following settings if you like, a useful default will be filled if you don't change anything:
+You can optionally configure the following settings.
+A useful default will be filled if you don't change anything.
 
 **Scopes**: The scopes define which scopes will be sent to the provider, `name` and `email` are prefilled. This information will be taken to create/update the user within ZITADEL.
 
 <GeneralConfigDescription provider_account="Apple account" />
 
-![Apple Provider](/img/guides/zitadel_apple_create_provider.png)
-
 ### Activate IdP
 
 <Activate/>
 
 ![Activate the Apple Provider](/img/guides/zitadel_activate_apple.png)
 
+### Ensure your Login Policy allows External IDPs
+
+<CustomLoginPolicy/>
+
 ## Test the setup
 
 <TestSetup loginscreen="your Apple login"/>

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

@@ -12,6 +12,15 @@ import Activate from './_activate.mdx';
 
 <Intro provider="Entra ID (former Azure Active Directory)"/>
 
+## Open the Microsoft Identity Provider Template
+
+<IDPsOverview templates="Microsoft"/>
+
+Click on the ZITADEL Callback URL to copy it to your clipboard.
+You will have to paste it in the Entra ID Client later.
+
+![Azure Provider](/img/guides/zitadel_azure_provider2.png)
+
 ## Entra ID Configuration
 
 You need to have access to an Entra ID Tenant. If you do not yet have one follow [this guide from Microsoft](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant) to create one for free.
@@ -20,10 +29,9 @@ You need to have access to an Entra ID Tenant. If you do not yet have one follow
 
 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
+3. Choose "Web" in the redirect uri field and [paste the ZITADEL Callback URL you copied before](#open-the-microsoft-identity-provider-template).
+4. Save the Application (client) ID and the Directory (tenant) ID from the detail page
+5. Register the application
 
 ![Azure App Registration](/img/guides/azure_app_registration.png)
 
@@ -61,20 +69,11 @@ To be able to get all the information that ZITADEL needs, you have to configure
 
 ## ZITADEL Configuration
 
-### Add custom login policy
+Go back [to the Microsoft provider template you opened before in ZITADEL](#open-the-microsoft-identity-provider-template).
+Add the [client ID and secret created before on your Entra ID application](#add-client-secret).
 
-<CustomLoginPolicy/>
-
-### Go to the IdP Providers Overview
-
-<IDPsOverview templates="Microsoft"/>
-
-### Create a new Entra ID 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:
+You can optionally configure the following settings.
+A useful default will be filled if you don't change anything.
 
 **Scopes**: The scopes define which scopes will be sent to the provider, `openid`, `profile`, and `email` are prefilled.
 This information will be taken to create/update the user within ZITADEL. Make sure to also add `User.Read`. ZITADEL ensures that at least `openid` and `User.Read` scopes are always sent.
@@ -94,14 +93,16 @@ In this case, configure "Accounts in any organizational directory and personal M
 
 <GeneralConfigDescription provider_account="Microsoft account" />
 
-![Azure Provider](/img/guides/zitadel_azure_provider2.png)
-
 ### Activate IdP
 
 <Activate/>
 
 ![Activate Entra ID](/img/guides/zitadel_activate_azure.png)
 
+### Ensure your Login Policy allows External IDPs
+
+<CustomLoginPolicy/>
+
 ## Test the setup
 
 <TestSetup loginscreen="your Microsoft login"/>

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

@@ -49,15 +49,11 @@ Configure the sign-on method of the app.
 
 ## ZITADEL Configuration
 
-### Add custom login policy
-
-<CustomLoginPolicy/>
-
 ### Go to the IdP Providers Overview
 
 <IDPsOverview templates="SAML SP"/>
 
-### Create a new SAML SP
+### Create a new SAML Service Provider (SP)
 
 Now we configure the identity provider on ZITADEL.
 
@@ -72,24 +68,40 @@ Now we configure the identity provider on ZITADEL.
 
 ![Azure SAML App Creation](/img/guides/zitadel_azure_saml_provider.png)
 
+## Configure Basic SAML Configuration
+
+After you created the SAML SP in ZITADEL, you can copy the URLs you need to configure in your Entra ID application.
+
+![Azure SAML App URLs](/img/guides/zitadel_azure_saml_provider_urls.png)
+
+1. Go to Microsoft Entra > Manage > Single sign-on
+2. Edit the "Basic SAML Configuration"
+3. **Identifier (Entity ID)**: Paste the *ZITADEL Metadata URL*.
+4. **Reply URL (Assertion Consumer Service URL)**: Paste the *ZITADEL ACS Login Form URL*
+5. **Sign on URL**: Paste the *ZITADEL ACS Login Form URL*
+5. **Logout URL**: Optionally paste the *ZITADEL Single Logout URL*
+6. Click Save
+
+:::info
+You can ignore the ZITADEL ACS Intent API URL for now.
+This is relevant if you want to [programmatically sign users in at ZITADEL via a SAML Service Provider](/guides/integrate/login-ui/external-login).
+:::
+
+![Azure Entra configuration overview](/img/guides/azure_saml_overview2.png)
+
+## Enable the Microsoft Entra Button in ZITADELs Login Page
+
+Go back to ZITADEL and activate the IdP.
+
 ### Activate IdP
 
 <Activate/>
 
 ![Activate Azure SAML Provider](/img/guides/zitadel_activate_azure_saml.png)
 
-## Configure Basic SAML Configuration
+### Ensure your Login Policy allows External IDPs
 
-Now we set the links in Microsoft Entra
-
-1. Go to Microsoft Entra > Manage > Single sign-on
-2. Edit the "Basic SAML Configuration"
-3. Enter the following URL in "Identifier (Entity ID)": `<YOUR-ZITADEL-DOMAIN>/idps/<IDP-ID>/saml/metadata`
-4. Enter the following URL in "Reply URL (Assertion Consumer Service URL)": `<YOUR-ZITADEL-DOMAIN>/ui/login/login/externalidp/saml/acs`
-5. Enter the following URL in "Sign on URL": `<YOUR-ZITADEL-DOMAIN>/ui/login/login/externalidp/saml/acs`
-6. Hit Save
-
-![Azure Entra configuration overview](/img/guides/azure_saml_overview2.png)
+<CustomLoginPolicy/>
 
 ## Test the setup
 

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

@@ -14,28 +14,29 @@ import PrefillAction from './_prefill_action.mdx';
 
 <Intro provider="GitHub"/>
 
+## Open the GitHub Identity Provider Template
+
+<IDPsOverview templates="GitHub or GitHub Enterprise Server"/>
+
+Click on the ZITADEL Callback URL to copy it to your clipboard.
+You will have to paste it to the GitHub OAuth application later.
+
+![GitHub Provider](/img/guides/zitadel_github_create_provider.png)
+
 ## 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 themselves.
-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
-:::
+1. Create a new OAuth application
+   - For **GitHub** browse to the [Register a new OAuth application](https://github.com/settings/applications/new). You can find this link withing [Settings](https://github.com/settings/profile) - [Developer Settings](https://github.com/settings/apps) - - [OAuth Apps](https://github.com/settings/developers).
+   - For **GitHub Enterprise** go to your GitHub Enterprise home page and then to Settings - Developer Settings - OAuth Apps - Register a new application/New OAuth App
+2. Fill in the application name and homepage URL.
+3. [Paste the ZITADEL Callback URL you copied before](#open-the-github-identity-provider-template) to the Authorization callback URL field.
+4. Click "Register application".
 
 ![Register an OAuth application](/img/guides/github_oauth_app_registration.png)
 
-### Client ID and Secret
+### 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.
@@ -46,33 +47,28 @@ Make sure to save the secret, as you will not be able to show it again.
 
 ## ZITADEL Configuration
 
-### Add custom login policy
+Go back [to the GitHub provider template you opened before in ZITADEL](#open-the-github-identity-provider-template).
+Add the [client ID and secret you created before when you registered your GitHub OAuth application](#client-id-and-secret).
 
-<CustomLoginPolicy/>
-
-### Go to the IdP Providers Overview
-
-<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:
+You can optionally configure the following settings.
+A useful default will be filled if you don't change anything.
 
 **Scopes**: The scopes define which scopes will be sent to the provider, `openid`, `profile`, and `email` are prefilled.
-This information is used to create and/or update the user within ZITADEL. ZITADEL ensures that at least the `openid`-scope is always sent.
+This information is used to create and/or update the user within ZITADEL.
+ZITADEL ensures that at least the `openid`-scope is always sent.
 
 <GeneralConfigDescription 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)
 
+### Ensure your Login Policy allows External IDPs
+
+<CustomLoginPolicy/>
+
 ## Test the setup
 
 <TestSetup loginscreen="your GitHub login"/>

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

@@ -14,30 +14,28 @@ import PrefillAction from './_prefill_action.mdx';
 
 <Intro provider="GitLab"/>
 
+## Open the GitLab Identity Provider Template
+
+<IDPsOverview templates="GitLab or GitLab Self Hosted"/>
+
+Click on the ZITADEL Callback URL to copy it to your clipboard.
+You will have to paste it to the GitLab Application later.
+
+![GitLab Provider](/img/guides/zitadel_gitlab_create_provider.png)
+
 ## GitLab Configuration
 
 ### Register a new application
 
-1. Login to [gitlab.com](https://gitlab.com)
+1. Login to [gitlab.com](https://gitlab.com) or to your GitLab self-hosted instance
 2. Select [Edit Profile](https://gitlab.com/-/profile)
 3. Click on [Applications](https://gitlab.com/-/profile/applications) in the side navigation
-
-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.
-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
-:::
+4. Fill in the application name
+5. [Paste the ZITADEL Callback URL you copied before](#open-the-gitlab-identity-provider-template) to the Redirect URI field.
 
 ![Register an OAuth application](/img/guides/gitlab_app_registration.png)
 
-### Client ID and Secret
+### 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.
@@ -47,33 +45,28 @@ Save the ID and the Secret, you will not be able to copy the secret again, if yo
 
 ## ZITADEL Configuration
 
-### Add custom login policy
+Go back [to the GitLab provider template you opened before in ZITADEL](#open-the-gitlab-identity-provider-template).
+Add the [client ID and secret you created before when you registered your GitLab application](#client-id-and-secret).
 
-<CustomLoginPolicy/>
+You can optionally configure the following settings.
+A useful default will be filled if you don't change anything.
 
-### Go to the IdP Providers Overview
-
-<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:
-
-**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. ZITADEL ensures that at least the `openid`-scope is always sent.
+**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.
+ZITADEL ensures that at least the `openid`-scope is always sent.
 
 <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)
 
+### Ensure your Login Policy allows External IDPs
+
+<CustomLoginPolicy/>
+
 ## Test the setup
 
 <TestSetup loginscreen="your GitLab login"/>

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

@@ -12,6 +12,15 @@ import TestSetup from './_test_setup.mdx';
 
 <Intro provider="Google"/>
 
+## Open the Google Identity Provider Template
+
+<IDPsOverview templates="Google"/>
+
+Click on the ZITADEL Callback URL to copy it to your clipboard.
+You will have to paste it in the Google Cloud Platform later.
+
+![Google Provider](/img/guides/zitadel_google_create_provider.png)
+
 ## Google Configuration
 
 ### Register a new client
@@ -19,45 +28,40 @@ import TestSetup from './_test_setup.mdx';
 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
+4. [Paste the ZITADEL Callback URL you copied before](#open-the-google-identity-provider-template) to the Authorised redirect URIs
 
 ![Google OAuth App Registration](/img/guides/google_oauth_app_registration.png)
 
+### Client ID and secret
+
+You will need the Client ID and Client secret to configure the Google Identity Provider in ZITADEL.
+
 ![Google Client ID and Secret](/img/guides/google_client_id_secret.png)
 
 ## ZITADEL Configuration
 
-### Add custom login policy
+Go back [to the Google provider template you opened before in ZITADEL](#open-the-google-identity-provider-template).
+Add the [client ID and secret created before on your Google App](#client-id-and-client-secret).
 
-<CustomLoginPolicy/>
-
-### Go to the IdP Providers Overview
-
-<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:
-
-**Scopes**: The scopes define which scopes will be sent to the provider, `openid`, `profile`, and `email` are prefilled. This information will be taken to create/update the user within ZITADEL. ZITADEL ensures that at least the `openid`-scope is always sent.
+You can optionally configure the following settings.
+A useful default will be filled if you don't change anything.
 
+**Scopes**: The scopes define which scopes will be sent to the provider, `openid`, `profile`, and `email` are prefilled.
+This information will be taken to create/update the user within ZITADEL.
+ZITADEL ensures that at least the `openid`-scope is always sent.
 
 <GeneralConfigDescription 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)
 
+### Ensure your Login Policy allows External IDPs
+
+<CustomLoginPolicy/>
+
 ## Test the setup
 
 <TestSetup loginscreen="your Google login"/>

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

@@ -8,12 +8,20 @@ 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 GenericOIDC from './_generic_oidc.mdx';
 import Activate from './_activate.mdx';
 import TestSetup from './_test_setup.mdx';
 
 <Intro provider="Keycloak"/>
 
+## Open the Generic OIDC Provider Template
+
+<IDPsOverview templates="Generic OIDC"/>
+
+Click on the ZITADEL Callback URL to copy it to your clipboard.
+You will have to paste it in the Keycloak Client later.
+
+![Generic OIDC Provider](/img/guides/zitadel_generic_oidc_create_provider.png)
+
 ## Keycloak Configuration
 
 ### Register a new client
@@ -22,9 +30,7 @@ import TestSetup from './_test_setup.mdx';
 2. Click on "Create Client"
 3. Choose OpenID Connect as Client Type and give your client an ID
 4. Enable Client authentication and the standard flow and direct access grants as authentication flow
-5. Add the valid redirect URIs
- - {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. [Paste the ZITADEL Callback URL you copied before](#open-the-generic-oidc-provider-template) to the redirect URIs
 6. Go to the credentials tab and copy the secret
 
 ![Add new OIDC Client in Keycloak](/img/guides/keycloak_add_client.png)
@@ -32,22 +38,17 @@ import TestSetup from './_test_setup.mdx';
 
 ## ZITADEL configuration
 
-### Add custom login policy
+1. Go back [to the Generic OIDC Provider template you opened before in ZITADEL](#open-the-generic-oidc-provider-template).
+2. Add the [client ID and secret created before on your Keycloak Client](#register-a-new-client).
+3. Give the provider a name, e.g. Keycloak. This name will be displayed on the login screen button.
+4. Add the issuer URL of your Keycloak realm with the path /auth/realms/$REALM, e.g. `https://lemur-0.cloud-iam.com/auth/realms/acme`
 
-<CustomLoginPolicy/>
-
-### Go to the IdP providers overview
-
-<IDPsOverview templates="Generic OIDC"/>
-
-### Create a new generic OIDC provider
-
-<GenericOIDC
-    name=": e.g. Keycloak"
-    issuer=": The domain where your Keycloak can be reached with the path /auth/realms/$REALM, Example: https://lemur-0.cloud-iam.com/auth/realms/acme"
-    clientid=": Client id from the client previously created in your Keycloak account"
-/>
+You can optionally configure the following settings.
+A useful default will be filled if you don't change anything.
 
+**Scopes**: The scopes define which scopes will be sent to the provider, `openid`, `profile`, and `email` are prefilled.
+This information will be taken to create/update the user within ZITADEL.
+ZITADEL ensures that at least the `openid`-scope is always sent.
 
 <GeneralConfigDescription provider_account="Keycloak account" />
 
@@ -59,11 +60,14 @@ import TestSetup from './_test_setup.mdx';
 
 ![Activate the Keycloak Provider](/img/guides/zitadel_activate_keycloak.png)
 
+### Ensure your Login Policy allows External IDPs
+
+<CustomLoginPolicy/>
+
 ## Test the setup
 
 <TestSetup loginscreen="your Keycloak login"/>
 
-
 ![Keycloak Button](/img/guides/zitadel_login_keycloak.png)
 
 ![Keycloak Login](/img/guides/keycloak_login.png)

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

@@ -19,10 +19,6 @@ import TestSetup from './_test_setup.mdx';
 
 ## ZITADEL Configuration
 
-### Add custom login policy
-
-<CustomLoginPolicy/>
-
 ### Go to the IdP Providers Overview
 
 <IDPsOverview templates="Active Directory / LDAP"/>
@@ -66,6 +62,10 @@ Otherwise, your users passwords are sent in clear text through the wire.
 
 ![Activate the LDAP Provider](/img/guides/zitadel_activate_ldap.png)
 
+### Ensure your Login Policy allows External IDPs
+
+<CustomLoginPolicy/>
+
 ## Test the setup
 
 <TestSetup loginscreen="ZITADELs LDAP login"/>

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

@@ -27,10 +27,6 @@ fill in the URL when creating the SAML SP in ZITADEL.
 
 ## ZITADEL configuration
 
-### Add custom login policy
-
-<CustomLoginPolicy/>
-
 ### Go to the IdP providers overview
 
 <IDPsOverview templates="SAML SP"/>
@@ -56,11 +52,14 @@ They are available under [https://{CUSTOMDOMAIN}/idps/{ID of the provider in ZIT
 
 ![Activate the SAML SP Provider](/img/guides/zitadel_activate_saml.png)
 
+### Ensure your Login Policy allows External IDPs
+
+<CustomLoginPolicy/>
+
 ## Test the setup
 
 <TestSetup loginscreen="your SAML SP login"/>
 
-
 ![SAML SP Button](/img/guides/zitadel_login_saml.png)
 
 ![SAML SP Login](/img/guides/mocksaml_login.png)

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

@@ -8,13 +8,21 @@ 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 GenericOIDC from './_generic_oidc.mdx';
 import Activate from './_activate.mdx';
 import PrefillAction from './_prefill_action.mdx';
 import TestSetup from './_test_setup.mdx';
 
 <Intro provider="OKTA"/>
 
+## Open the Generic OIDC Provider Template
+
+<IDPsOverview templates="Generic OIDC"/>
+
+Click on the ZITADEL Callback URL to copy it to your clipboard.
+You will have to paste it in the OKTA application later.
+
+![Generic OIDC Provider](/img/guides/zitadel_generic_oidc_create_provider.png)
+
 ## OKTA Configuration
 
 ### Register a new client
@@ -22,47 +30,42 @@ import TestSetup from './_test_setup.mdx';
 1. Login to your OKTA Account and go to the applications list: <OKTA-DOMAIN/admin/apps/active>
 2. Click on "Create App Integration" and choose "OIDC - OpenID Connect"
 3. Choose Web application as Application type and give a name
-4. Add the Sign-in redirect uris
- - {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 clientid and client secret
+4. [Paste the ZITADEL Callback URL you copied before](#open-the-generic-oidc-provider-template) to the Sign-in redirect URIs
+5. Save the clientid and client secret
 
 ![Add new OIDC Application in OKTA](/img/guides/okta_add_app.png)
 
 ## ZITADEL Configuration
 
-### Add custom login policy
+1. Go back [to the Generic OIDC Provider template you opened before in ZITADEL](#open-the-generic-oidc-provider-template).
+2. Add the [client ID and secret created before on your Web application](#register-a-new-client).
+3. Give the provider a name, e.g. OKTA. This name will be displayed on the login screen button.
+4. Add the issuer URL of your OKTA account, e.g. `https://trial-1925566.okta.com`
 
-<CustomLoginPolicy/>
-
-### Go to the IdP Providers Overview
-
-<IDPsOverview templates="Generic OIDC"/>
-
-### Create a new Generic OIDC Provider
-
-<GenericOIDC
-    name=": e.g. OKTA"
-    issuer=": The domain of your OKTA account, Example: https://trial-1925566.okta.com"
-    clientid=": Client id from the application previously created in your OKTA account"
-/>
+You can optionally configure the following settings.
+A useful default will be filled if you don't change anything.
 
+**Scopes**: The scopes define which scopes will be sent to the provider, `openid`, `profile`, and `email` are prefilled.
+This information will be taken to create/update the user within ZITADEL.
+ZITADEL ensures that at least the `openid`-scope is always sent.
 
 <GeneralConfigDescription provider_account="OKTA account" />
 
-![OKTA Provider](/img/guides/zitadel_okta_create_provider.png)
-
 ### Activate IdP
 
 <Activate/>
 
 ![Activate the OKTA Provider](/img/guides/zitadel_activate_okta.png)
 
+### Ensure your Login Policy allows External IDPs
+
+<CustomLoginPolicy/>
+
 ## Test the setup
 
 <TestSetup loginscreen="your OKTA login"/>
 
-<!-- TODO: Image highlights GitHub -->
+<!-- TODO: Image highlights Google -->
 ![OKTA Button](/img/guides/zitadel_login_okta.png)
 
 ![OKTA Login](/img/guides/okta_login.png)

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

@@ -16,10 +16,6 @@ import TestSetup from './_test_setup.mdx';
 
 ## ZITADEL Configuration
 
-### Add custom login policy
-
-<CustomLoginPolicy/>
-
 ### Go to the IdP Providers Overview
 
 <IDPsOverview templates="SAML SP"/>
@@ -30,8 +26,6 @@ To be able to create the application in OKTA we need the provider id from ZITADE
 1. Create a new SAML SP with a name and a random text in the Metadata Xml field.
 We will fill that as soon as we have done the configuration in OKTA.
 2. Save Configuration
-3. Open up the detail of the configuration and copy the provider ID from the browser URL:
-`$CUSTOM-DOMAIN/ui/console/org/provider/saml/$PROVIDER-ID`
 
 As an alternative you can add the SAML identity provider through the API, either on the default settings or on a specific organization:
 - [Add Default SAML Identity Provider](/docs/apis/resources/admin/admin-service-add-saml-provider)
@@ -39,6 +33,10 @@ As an alternative you can add the SAML identity provider through the API, either
 
 ![OKTA Provider Empty](/img/guides/zitadel_okta_saml_provider_empty.png)
 
+After you created the SAML SP in ZITADEL, you can copy the URLs you need to configure in your OKTA application.
+
+![OKTA SAML App URLs](/img/guides/zitadel_okta_saml_provider_urls.png)
+
 ## OKTA Configuration
 
 ### Register a new client
@@ -46,10 +44,9 @@ As an alternative you can add the SAML identity provider through the API, either
 1. Log in to your OKTA Account and go to the applications list: <OKTA-DOMAIN/admin/apps/active>
 2. Click on "Create App Integration" and choose "SAML 2.0"
 3. Give the application a name
-4. Fill the configuration as following (Replace `your-domain` and `saml-idp-id` with your data):
- - Single sign-on URL `{your-domain}/ui/login/login/externalidp/saml/acs`
- - Audience URI (SP Entity ID): `{your-domain}/idps/{saml-idp-id}/saml/metadata`
- - Example redirect url for the domain `https://acme.zitadel.cloud` would look like this:  `https://acme.zitadel.cloud/idps/257372385775925924/saml/metadata`
+4. Click on the ZITADEL URLs that your SAML IDP shows since you created it in ZITADEL and paste them accordingly:
+- **Single sign-on URL**: Paste the *ZITADEL ACS Login Form URL*.
+- **Audience URI (SP Entity ID)**: Paste the *ZITADEL Metadata URL*
 5. Save the configuration
 6. Copy the metadata URL from the details
 
@@ -85,7 +82,7 @@ You are now finished with the configuration in OKTA and you can switch back to y
 
 ### Add Metadata Xml
 
-Add the metadata URL you have saved before from OKTA to the Metadata URL.
+Add [the metadata URL you have saved before from OKTA](#register-a-new-client) to the Metadata URL.
 As soon as you have saved the provider, and you have a look at the detail you should now see the Metadata Xml field filled.
 
 If you prefer changing the configuration through the API you can update the SAML provider on the default settings or a specific organization:
@@ -104,13 +101,9 @@ You can also fill the optional fields if needed:
 
 ![Activate the OKTA Provider](/img/guides/zitadel_activate_okta_saml.png)
 
-### Add Action to map user attributes
+### Ensure your Login Policy allows External IDPs
 
-<PrefillAction fields="username, firstname, lastname, email and email verified" provider="OKTA"/>
-
-```js reference
-https://github.com/zitadel/actions/blob/main/examples/okta_saml_prefil_register_form.js
-```
+<CustomLoginPolicy/>
 
 ## Test the setup
 
@@ -119,3 +112,12 @@ https://github.com/zitadel/actions/blob/main/examples/okta_saml_prefil_register_
 ![OKTA Button](/img/guides/zitadel_login_okta.png)
 
 ![OKTA Login](/img/guides/okta_login.png)
+
+### Add Action to map user attributes
+
+<PrefillAction fields="username, firstname, lastname, email and email verified" provider="OKTA"/>
+
+```js reference
+https://github.com/zitadel/actions/blob/main/examples/okta_saml_prefil_register_form.js
+```
+

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

@@ -150,10 +150,6 @@ ldapadd -x -h localhost -D "cn=admin,dc=example,dc=com" -f example.ldif -w 'Pass
 
 ## ZITADEL Configuration
 
-### Add custom login policy
-
-<CustomLoginPolicy/>
-
 ### Go to the IdP Providers Overview
 
 <IDPsOverview templates="Active Directory / LDAP"/>
@@ -195,6 +191,10 @@ Fill in the template fields with the exact values listed below. The fields are d
 
 ![Activate the LDAP Provider](/img/guides/zitadel_activate_ldap.png)
 
+### Ensure your Login Policy allows External IDPs
+
+<CustomLoginPolicy/>
+
 ## Test the setup
 
 <TestSetup loginscreen="ZITADELs LDAP login"/>