docs: Okta saml idp docs (#7523)

* docs: add guide to setup okta saml idp

* docs: remove todo

* docs: okta user data info

* docs: fix broken links

* docs: add references to API docs

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

Co-authored-by: Silvan <silvan.reusser@gmail.com>

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

Co-authored-by: Silvan <silvan.reusser@gmail.com>

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

Co-authored-by: Silvan <silvan.reusser@gmail.com>

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

Co-authored-by: Silvan <silvan.reusser@gmail.com>

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

Co-authored-by: Silvan <silvan.reusser@gmail.com>

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

Co-authored-by: Silvan <silvan.reusser@gmail.com>

* docs: default settings

* docs: default settings

* docs: add saml mapping action

* docs: add saml mapping action

* docs: add saml mapping action

---------

Co-authored-by: Silvan <silvan.reusser@gmail.com>

docs/docs/apis/actions/code-examples.mdx

@@ -180,7 +180,7 @@ If you want to ensure that the data of a user are always update you can automati
 
 ### Fields provided by Okta
 
-If you use [Okta as an identity provider](/guides/integrate/identity-providers/okta) you can improve the onboarding experience of new users by prefilling some basic information during authentication.
+If you use [Okta as an identity provider](/guides/integrate/identity-providers/okta-oidc) you can improve the onboarding experience of new users by prefilling some basic information during authentication.
 
 <details open="">
 <summary>Code example</summary>

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

@@ -2,4 +2,8 @@ Once you created the provider, it is listed in the providers overview.
 Activate it by selecting the tick with the tooltip *set as available*.
 
 If you deactivate a provider, your users with links to it will not be able to authenticate anymore.
-You can reactivate it and the logins will work again.
+You can reactivate it and the logins will work again.
+
+The provider can also be activated via API. As the identity providers are sub-resources of the login settings, this is done by linking the provider to the settings:
+- [Activate Default Identity Provider](/docs/apis/resources/admin/admin-service-add-idp-to-login-policy)
+- [Activate Organization Identity Provider](/docs/apis/resources/mgmt/management-service-add-idp-to-login-policy)

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

@@ -1,10 +1,15 @@
-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/instance?id=general
+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
 2. Modify your login policy in the menu "Login Behavior and Security"
 3. Enable the attribute "External IDP allowed"
 
+You can also change the settings through the API directly either in the default settings or on a specific organization:
+- [Update Default Login Settings](/docs/apis/resources/admin/admin-service-update-login-policy)
+- [Update Organization Login Settings](/docs/apis/resources/mgmt/management-service-update-custom-login-policy)
+
 ![Allow External IDP](/img/guides/zitadel_allow_external_idp.png)
+

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

@@ -1,7 +1,7 @@
 ---
-title: Configure OKTA as an Identity Provider in ZITADEL
+title: Configure OKTA as an OIDC Identity Provider in ZITADEL
 sidebar_label: OKTA generic OIDC
-id: okta
+id: okta-oidc
 ---
 
 import GeneralConfigDescription from './_general_config_description.mdx';
@@ -10,8 +10,8 @@ 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';
 import PrefillAction from './_prefill_action.mdx';
+import TestSetup from './_test_setup.mdx';
 
 <Intro provider="OKTA"/>
 

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

@@ -0,0 +1,121 @@
+---
+title: Configure OKTA as a SAML Identity Provider in ZITADEL
+sidebar_label: OKTA SAML SP
+id: okta-saml
+---
+
+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 PrefillAction from './_prefill_action.mdx';
+import TestSetup from './_test_setup.mdx';
+
+<Intro provider="OKTA"/>
+
+## ZITADEL Configuration
+
+### Add custom login policy
+
+<CustomLoginPolicy/>
+
+### Go to the IdP Providers Overview
+
+<IDPsOverview templates="SAML SP"/>
+
+### Create a new SAML Service Provider (SP)
+
+To be able to create the application in OKTA we need the provider id from ZITADEL.
+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)
+- [Add SAML Identity Provider on Organization](/docs/apis/resources/mgmt/management-service-add-saml-provider)
+
+![OKTA Provider Empty](/img/guides/zitadel_okta_saml_provider_empty.png)
+
+## OKTA Configuration
+
+### Register a new client
+
+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`
+5. Save the configuration
+6. Copy the metadata URL from the details
+
+![Add new SAML Application in OKTA](/img/guides/okta_add_saml_app.png)
+
+### Add Attribute Statements
+
+To send the user data from OKTA to ZITADEL you have to add some attribute mappings in your SAML Settings
+You can define the name by yourself, just ensure you use the same later on in the ZITADEL Action we will add.
+
+Add the following three mappings:
+
+| Name         | Name format | Value          |
+| ------------ | ----------- |--------------- |
+| givenname    | Basic       | user.firstName |
+| surname      | Basic       | user.lastName  |
+| emailaddress | Basic       | user.email     |
+
+![Add Attribute Mapping ](/img/guides/okta_saml_attribute_mapping.png)
+
+### Assign Users to Application
+
+To allow users to authenticate with that app go to the "Assign" Tab.
+1. Click the Assign Button
+2. Choose Assign To People
+3. Select the users you like to be able to authenticate
+
+![Add new SAML Application in OKTA](/img/guides/okta_assign_user_to_app.png)
+
+## Finish ZITADEL Configuration
+
+You are now finished with the configuration in OKTA and you can switch back to your identity provider configuration in ZITADEL.
+
+### Add Metadata Xml
+
+Add the metadata URL you have saved before from OKTA 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:
+- [Update Default SAML Identity Provider](/docs/apis/resources/admin/admin-service-update-saml-provider)
+- [Update SAML Identity Provider on Organization](/docs/apis/resources/mgmt/management-service-update-saml-provider)
+
+![OKTA Provider Empty](/img/guides/zitadel_okta_saml_provider_filled.png)
+
+You can also fill the optional fields if needed:
+
+<GeneralConfigDescription provider_account="OKTA account" />
+
+### Activate IdP
+
+<Activate/>
+
+![Activate the OKTA Provider](/img/guides/zitadel_activate_okta_saml.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
+```
+
+## Test the setup
+
+<TestSetup loginscreen="your OKTA login"/>
+
+![OKTA Button](/img/guides/zitadel_login_okta.png)
+
+![OKTA Login](/img/guides/okta_login.png)

docs/docs/guides/integrate/login/login-users.mdx

@@ -134,7 +134,7 @@ With the hosted login page from ZITADEL developers will get the best support for
 ZITADEL acts as an [identity broker](/docs/concepts/features/identity-brokering) between your applications and different external identity providers, reducing the implementation effort for developers.
 External Identity providers can be configured for the whole instance or for each organization that represents a group of users such as a B2B customer or organizational unit.
 
-ZITADEL offers various [identity provider templates](/docs/guides/integrate/identity-providers) to integrate providers such as [Okta](/docs/guides/integrate/identity-providers/okta), [Entra ID](/docs/guides/integrate/identity-providers/azure-ad) or on-premise [LDAP](/docs/guides/integrate/identity-providers/ldap).
+ZITADEL offers various [identity provider templates](/docs/guides/integrate/identity-providers) to integrate providers such as [Okta](/docs/guides/integrate/identity-providers/okta-oidc), [Entra ID](/docs/guides/integrate/identity-providers/azure-ad) or on-premise [LDAP](/docs/guides/integrate/identity-providers/ldap).
 
 ### Multi-tenancy authentication
 

docs/sidebars.js

@@ -349,7 +349,8 @@ module.exports = {
             "guides/integrate/identity-providers/ldap",
             "guides/integrate/identity-providers/openldap",
             "guides/integrate/identity-providers/migrate",
-            "guides/integrate/identity-providers/okta",
+            "guides/integrate/identity-providers/okta-oidc",
+            "guides/integrate/identity-providers/okta-saml",
             "guides/integrate/identity-providers/keycloak",
             "guides/integrate/identity-providers/mocksaml",
             "guides/integrate/identity-providers/additional-information",