diff --git a/docs/docs/apis/actions/code-examples.mdx b/docs/docs/apis/actions/code-examples.mdx index 6dcf913417..2308e95b08 100644 --- a/docs/docs/apis/actions/code-examples.mdx +++ b/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.
Code example diff --git a/docs/docs/guides/integrate/identity-providers/_activate.mdx b/docs/docs/guides/integrate/identity-providers/_activate.mdx index 138885ca52..efa5a57ee3 100644 --- a/docs/docs/guides/integrate/identity-providers/_activate.mdx +++ b/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. \ No newline at end of file +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) diff --git a/docs/docs/guides/integrate/identity-providers/_custom_login_policy.mdx b/docs/docs/guides/integrate/identity-providers/_custom_login_policy.mdx index 476d84c24b..2f6c173445 100644 --- a/docs/docs/guides/integrate/identity-providers/_custom_login_policy.mdx +++ b/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) + diff --git a/docs/docs/guides/integrate/identity-providers/okta.mdx b/docs/docs/guides/integrate/identity-providers/okta-oidc.mdx similarity index 96% rename from docs/docs/guides/integrate/identity-providers/okta.mdx rename to docs/docs/guides/integrate/identity-providers/okta-oidc.mdx index ae558e0471..2461386995 100644 --- a/docs/docs/guides/integrate/identity-providers/okta.mdx +++ b/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'; diff --git a/docs/docs/guides/integrate/identity-providers/okta_saml.mdx b/docs/docs/guides/integrate/identity-providers/okta_saml.mdx new file mode 100644 index 0000000000..f498a2fd0b --- /dev/null +++ b/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'; + + + +## ZITADEL Configuration + +### Add custom login policy + + + +### Go to the IdP Providers Overview + + + +### 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: +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: + + + +### Activate IdP + + + +![Activate the OKTA Provider](/img/guides/zitadel_activate_okta_saml.png) + +### Add Action to map user attributes + + + +```js reference +https://github.com/zitadel/actions/blob/main/examples/okta_saml_prefil_register_form.js +``` + +## Test the setup + + + +![OKTA Button](/img/guides/zitadel_login_okta.png) + +![OKTA Login](/img/guides/okta_login.png) diff --git a/docs/docs/guides/integrate/login/login-users.mdx b/docs/docs/guides/integrate/login/login-users.mdx index 234e8b4bef..f0f28bf577 100644 --- a/docs/docs/guides/integrate/login/login-users.mdx +++ b/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 diff --git a/docs/sidebars.js b/docs/sidebars.js index 5666fe63bf..0b4c29e9cd 100644 --- a/docs/sidebars.js +++ b/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", diff --git a/docs/static/img/guides/okta_add_saml_app.png b/docs/static/img/guides/okta_add_saml_app.png new file mode 100644 index 0000000000..36d197712b Binary files /dev/null and b/docs/static/img/guides/okta_add_saml_app.png differ diff --git a/docs/static/img/guides/okta_assign_user_to_app.png b/docs/static/img/guides/okta_assign_user_to_app.png new file mode 100644 index 0000000000..66caabfec3 Binary files /dev/null and b/docs/static/img/guides/okta_assign_user_to_app.png differ diff --git a/docs/static/img/guides/okta_saml_attribute_mapping.png b/docs/static/img/guides/okta_saml_attribute_mapping.png new file mode 100644 index 0000000000..36ce5706e8 Binary files /dev/null and b/docs/static/img/guides/okta_saml_attribute_mapping.png differ diff --git a/docs/static/img/guides/zitadel_activate_okta_saml.png b/docs/static/img/guides/zitadel_activate_okta_saml.png new file mode 100644 index 0000000000..fdc72cd6eb Binary files /dev/null and b/docs/static/img/guides/zitadel_activate_okta_saml.png differ diff --git a/docs/static/img/guides/zitadel_identity_provider_overview.png b/docs/static/img/guides/zitadel_identity_provider_overview.png index 7cb9cfdd72..ecd7fef0e7 100644 Binary files a/docs/static/img/guides/zitadel_identity_provider_overview.png and b/docs/static/img/guides/zitadel_identity_provider_overview.png differ diff --git a/docs/static/img/guides/zitadel_okta_saml_provider_empty.png b/docs/static/img/guides/zitadel_okta_saml_provider_empty.png new file mode 100644 index 0000000000..bdb197438d Binary files /dev/null and b/docs/static/img/guides/zitadel_okta_saml_provider_empty.png differ diff --git a/docs/static/img/guides/zitadel_okta_saml_provider_filled.png b/docs/static/img/guides/zitadel_okta_saml_provider_filled.png new file mode 100644 index 0000000000..43b078cbab Binary files /dev/null and b/docs/static/img/guides/zitadel_okta_saml_provider_filled.png differ