docs: introduce versioned docs and migrate to fuma (#11166)

## Todos for release - [x] Configure Env in docs project on vercel - [x] Configure Root Path in the docs project on vercel - [ ] Remove old CSP https://github.com/zitadel/website/pull/1592 ## What we did This pull request migrates the project documentation from the old `docs/` directory to the new `apps/docs/` directory, introduces a new documentation system built with Next.js and Fumadocs, and updates all relevant references, configuration files, and documentation to reflect this change. It also adds new configuration and ignore files for the new documentation app, updates CI and linting to exclude the new docs from certain checks, and revises the contributing guidelines accordingly. **Documentation System Migration and New Docs App** * Migrated all documentation from `docs/` to `apps/docs/`, and updated all references in `README.md`, `CONTRIBUTING.md`, and other files to point to the new location. [[1]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L585-L640) [[2]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L660-R607) [[3]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L740-R687) [[4]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L2-R3) [[5]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L30-R30) * Added a new Next.js/Fumadocs-based documentation app under `apps/docs/`, including core app files, layouts, routing, search API, and a comprehensive `README.md` with development and contribution instructions. [[1]](diffhunk://#diff-5a1b07344a2c1b4d3f37b23ff1388b62cd9f57dea3c1cd23d8a0412b7602b132R1-R74) [[2]](diffhunk://#diff-462b9ad1eabbb7d1c29bb9c36e4931eb180fd7190900e6d2babf8f4d66ad1c28R1-R39) [[3]](diffhunk://#diff-e16ae25660ded787b10ac35dea96d5ecaacf895dae0afc8a9bd4382dc79a8c87R1-R7) [apps/docs/app/[[...slug]]/layout.tsxR1-R81](diffhunk://#diff-59e08acde4e805b7aeccef1dcf98f1d71dfc550777e6b9402085cee0e9fa4e0aR1-R81), [apps/docs/app/[[...slug]]/page.tsxR1-R79](diffhunk://#diff-e5df3f80d0fa01e12d63d81f29c57a9d14e846c78fd3beabb2ef768e38fd9580R1-R79), [[4]](diffhunk://#diff-389b34918e040cacaa87cd7201ffa462cc2b0b716736f537e3d3c660ac69353bR1-R7) [[5]](diffhunk://#diff-d3b03416d1c457b19f1c27b26f2db741412df841b875c26ccadc36e4522247f4R1-R29) [[6]](diffhunk://#diff-c8fb8339570a5305809be7c618e14705fd86390dc278e6ce8ba224a7bc8b0c3cR1-R25) **Configuration and Tooling Updates** * Updated `.github/workflows/codeql.yml`, `.golangci.yaml`, and `.github/dependabot.yml` to properly handle the new docs app: excluded `apps/docs` from certain checks, added npm dependency updates for the docs app, and excluded generated content. [[1]](diffhunk://#diff-12783128521e452af0cfac94b99b8d250413c516ec71fe6d97dbea666ff7ba27L8-R14) [[2]](diffhunk://#diff-9917ddc9f1c3304218f7269265b746d997c5c0615478177b5fceecd33ef47cb5R5-R6) [[3]](diffhunk://#diff-9917ddc9f1c3304218f7269265b746d997c5c0615478177b5fceecd33ef47cb5R126-R129) [[4]](diffhunk://#diff-dd4fbda47e51f1e35defb9275a9cd9c212ecde0b870cba89ddaaae65c5f3cd28R89-R106) * Updated `.devcontainer/devcontainer.json` to use the latest Go 1.25.3 version for consistency. **Licensing and Miscellaneous** * Added `apps/docs/` to the list of licensed directories in `LICENSING.md`. These changes ensure the documentation is now maintained in a modern, scalable system and all project tooling is updated to support the new structure. --------- Co-authored-by: Federico Coppede <[email protected]>
2026-10-18 05:52:51 +00:00 · 2026-01-29 08:38:36 -08:00
parent 7b6395c348
commit d8ea041c56
2826 changed files with 78739 additions and 23571 deletions
@@ -0,0 +1,122 @@
+---
+title: Configure OKTA as a SAML Identity Provider in ZITADEL
+sidebar_label: OKTA SAML
+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 components={props.components}  provider="OKTA"/>
+
+## ZITADEL Configuration
+
+### Go to the IdP Providers Overview
+
+<IDPsOverview components={props.components}  templates="SAML"/>
+
+### Create a new SAML Provider
+
+To be able to create the application in OKTA we need the provider id from ZITADEL.
+1. Create a new SAML Provider 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
+
+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](/reference/api/admin/zitadel.admin.v1.AdminService.AddSAMLProvider)
+- [Add SAML Identity Provider on Organization](/reference/api/management/zitadel.management.v1.ManagementService.AddSAMLProvider)
+
+![](../../../../public/img/guides/zitadel_okta_saml_provider_empty.png)
+
+After you created the SAML Provider in ZITADEL, you can copy the URLs you need to configure in your OKTA application.
+
+![](../../../../public/img/guides/zitadel_okta_saml_provider_urls.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. 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
+
+![](../../../../public/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     |
+
+![](../../../../public/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
+
+![](../../../../public/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](#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:
+- [Update Default SAML Identity Provider](/reference/api/admin/zitadel.admin.v1.AdminService.UpdateSAMLProvider)
+- [Update SAML Identity Provider on Organization](/reference/api/management/zitadel.management.v1.ManagementService.UpdateSAMLProvider)
+
+![](../../../../public/img/guides/zitadel_okta_saml_provider_filled.png)
+
+You can also fill the optional fields if needed:
+
+<GeneralConfigDescription components={props.components}  provider_account="OKTA account" />
+
+### Activate IdP
+
+<Activate components={props.components} />
+
+![](../../../../public/img/guides/zitadel_activate_okta_saml.png)
+
+### Ensure your Login Policy allows External IDPs
+
+<CustomLoginPolicy components={props.components} />
+
+## Test the setup
+
+<TestSetup components={props.components}  loginscreen="your OKTA login"/>
+
+![](../../../../public/img/guides/zitadel_login_okta.png)
+
+![](../../../../public/img/guides/okta_login.png)
+
+### Add Action to map user attributes
+
+<PrefillAction components={props.components}  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
+```