chore(docs): Migrate from Docusaurus v2 to v3 (#8036)

Migrate Docs to latest version of Docusaursu (3.3.2 as of time of writing) --------- Co-authored-by: Florian Forster <[email protected]>
2026-11-05 13:52:15 +00:00 · 2024-06-20 12:55:03 +00:00
parent f9742a58f4
commit 4101e1cd49
56 changed files with 6421 additions and 5343 deletions
@@ -177,5 +177,5 @@ Deciding whether to configure an external Identity Provider (IdP) at the organiz
 ## References

 - [Identity brokering in ZITADEL](/docs/concepts/features/identity-brokering)
- [The ZITADEL API reference for managing external IdPs](/docs/category/apis/resources/admin/identity-providers)
- [Handle external logins in a custom login UI](/docs/guides/integrate/login-ui/external-login)
+- [The ZITADEL API reference for managing external IdPs](/docs/apis/resources/admin/identity-providers)
+- [Handle external logins in a custom login UI](/docs/guides/integrate/login-ui/external-login)
@@ -26,7 +26,7 @@ You will have to paste it in the Keycloak Client later.

 ### Register a new client

-1. Login to your Keycloak account and go to the clients list: <$KEYCLOAK-DOMAIN/auth/admin/$REALM/console/#/$REALM/clients>
+1. Login to your Keycloak account and go to the clients list: `$KEYCLOAK-DOMAIN/auth/admin/$REALM/console/#/$REALM/clients`
 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
@@ -23,7 +23,7 @@ import TestSetup from './_test_setup.mdx';
 2. Add your App Name, your Company Page and a Logo
 3. Add "Sign In with LinkedIn using OpenID Connect" by clicking "Request access"
 4. Go to the Auth Settings of the App and add the following URL to the "Authorized redirect URLs"
- - {your-domain}/ui/login/login/externalidp/callback
+ - `{your_domain}/ui/login/login/externalidp/callback`
 - Example redirect url for the domain `https://acme.zitadel.cloud` would look like this:  `https://acme.zitadel.cloud/ui/login/login/externalidp/callback`
 5. Verify the app as your company
 6. In the Auth - OAuth 2.0 scopes section you should see `openid`, `profile` and `email` listed
@@ -44,7 +44,7 @@ All the necessary configuration is contained in the metadata which has to be exc
 ### Download metadata

 Normally, you would need to download the ServiceProvider metadata from ZITADEL to upload to the IdentityProvider.
-They are available under [https://{CUSTOMDOMAIN}/idps/{ID of the provider in ZITADEL}/saml/metadata], but this step can be skipped due to the fact that MockSAML is only for testing purposes.
+They are available under `https://${CUSTOMDOMAIN}/idps/\{ID of the provider in ZITADEL}/saml/metadata`, but this step can be skipped due to the fact that MockSAML is only for testing purposes.

 ### Activate IdP

@@ -27,7 +27,7 @@ You will have to paste it in the OKTA application later.

 ### Register a new client

-1. Login to your OKTA Account and go to the applications list: <OKTA-DOMAIN/admin/apps/active>
+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. [Paste the ZITADEL Callback URL you copied before](#open-the-generic-oidc-provider-template) to the Sign-in redirect URIs
@@ -65,7 +65,6 @@ ZITADEL ensures that at least the `openid`-scope is always sent.

 <TestSetup loginscreen="your OKTA login"/>

-<!-- TODO: Image highlights Google -->
 ![OKTA Button](/img/guides/zitadel_login_okta.png)

 ![OKTA Login](/img/guides/okta_login.png)
@@ -41,7 +41,7 @@ After you created the SAML SP in ZITADEL, you can copy the URLs you need to conf

 ### Register a new client

-1. Log in to your OKTA Account and go to the applications list: <OKTA-DOMAIN/admin/apps/active>
+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:
@@ -26,7 +26,7 @@ ZITADEL does have multiple possibilities to achieve that process.
 ## Onboard customers through the ZITADEL Management Console

 Each ZITADEL instance does automatically bring a management console with it. The [console](/docs/guides/manage/console/overview) can be used to manage all your resources through a UI.
-You can access it by calling the following URL: $CUSTOM-DOMAIN/ui/
+You can access it by calling the following URL: `${CUSTOM-DOMAIN}/ui/`
 Make sure that your admins have a [Manager role](/docs/guides/manage/console/managers) with permissions on an instance level such as "INSTANCE_OWNER"

 ### Create a customer
@@ -139,7 +139,7 @@ If you want to start automating the process of onboarding your customers the fol
 ### Built-in register organization form

 A basic form that allows a customer to enter an organization name and a user account is hosted on the following URL:
-{custom-domain}/ui/login/register/org
+`{custom-domain}/ui/login/register/org`

 When a user registers through this form, an organization and a user are created.
 The user will automatically get the role "ORG_OWNER" withing ZITADEL and is able to manage the whole organization.
@@ -18,8 +18,8 @@ Follow the links below to assign roles to your users.

 - [Add application roles via the ZITADEL Console](/docs/guides/manage/console/roles)
 - [Add manager roles via the ZITADEL Console](/docs/guides/manage/console/managers)
- [Add application roles via the ZITADEL Management API](/docs/category/apis/resources/mgmt/project-roles)
- [Add manager roles to users via the ZITADEL Management API](/category/apis/resources/mgmt/members)
+- [Add application roles via the ZITADEL Management API](/docs/apis/resources/mgmt/project-roles)
+- [Add manager roles to users via the ZITADEL Management API](/docs/apis/resources/mgmt/members)

 ## Retrieve roles

@@ -210,7 +210,7 @@ https://github.com/zitadel/actions/blob/main/examples/custom_roles.js
 Now we will use the auth API to retrieve roles from a logged in user using the user’s token
 The base URL is: **https://$ZITADEL_DOMAIN/auth/v1**

-Let’s start with a user who has multiple roles in different organizations in a multi-tenanted set up. You can use the logged in user’s token or the machine user’s token to retrieve the authorizations using the [APIs listed under user authorizations/grants in the auth API](/docs/category/apis/resources/auth/user-authorizations-grants). 
+Let’s start with a user who has multiple roles in different organizations in a multi-tenanted set up. You can use the logged in user’s token or the machine user’s token to retrieve the authorizations using the [APIs listed under user authorizations/grants in the auth API](/docs/apis/resources/auth/user-authorizations-grants). 

 **Scope used:** `openid urn:zitadel:iam:org:project:id:zitadel:aud`

@@ -394,7 +394,7 @@ Now we will use the management API to retrieve user roles under an admin user.

 The base URL is: **https://$CUSTOM-DOMAIN/management/v1**

-In [APIs listed under user grants in the management API](/docs/category/apis/resources/mgmt/user-grants), you will see that you can use the management API to retrieve and modify user grants. The two API paths that we are interested in to fetch user roles are given below.
+In [APIs listed under user grants in the management API](/docs/apis/resources/mgmt/user-grants), you will see that you can use the management API to retrieve and modify user grants. The two API paths that we are interested in to fetch user roles are given below.

 **Scope used:** `openid urn:zitadel:iam:org:project:id:zitadel:aud`

@@ -127,7 +127,7 @@ However, [client credentials authentication](./client-credentials.md) might be c
 ## Further resources

 * Read about the [different methods to authenticate service users](./authenticate-service-users)
-* [Service User API reference](/docs/category/apis/resources/mgmt/user-machine)
+* [Service User API reference](/docs/apis/resources/mgmt/user-machine)
 * [OIDC JWT with private key](/docs/apis/openidoauth/authn-methods#jwt-with-private-key) authentication method reference
 * [Access ZITADEL APIs](../zitadel-apis/access-zitadel-apis)
 * Validate access tokens with [token introspection with private key jwt](../token-introspection/private-key-jwt.mdx)
@@ -100,7 +100,7 @@ By following these steps and adhering to security best practices, you can effect
 ## Notes

 * Read about the [different methods to authenticate service users](./authenticate-service-users)
-* [Service User API reference](/docs/category/apis/resources/mgmt/user-machine)
+* [Service User API reference](/docs/apis/resources/mgmt/user-machine)
 * [OIDC client secret basic](/docs/apis/openidoauth/authn-methods#client-secret-basic) authentication method reference
 * [Access ZITADEL APIs](../zitadel-apis/access-zitadel-apis)
 * Validate access tokens with [token introspection with basic auth](../token-introspection/basic-auth)
@@ -36,9 +36,9 @@ For Identity Provider select "Other provider" and enter a Directory Name.
 Follow the wizard.
 Fill in the following information:

- `Identity provider Entity ID`: {your_instance_domain}/saml/v2/metadata
- `Identity provider SSO URL`: {your_instance_domain}/saml/v2/SSO
- `Public x509 certificate`: You need to download and paste the value of the certificate from {your_instance_domain}/saml/v2/certificate
+- `Identity provider Entity ID`: \{your_instance_domain}/saml/v2/metadata
+- `Identity provider SSO URL`: \{your_instance_domain}/saml/v2/SSO
+- `Public x509 certificate`: You need to download and paste the value of the certificate from \{your_instance_domain}/saml/v2/certificate

 ![Add SAML details](/img/saml/atlassian/atlassian-03.png)

@@ -42,7 +42,7 @@ This includes:
 All the information is filled out as an example, and to connect with any other environment you only have to change the
 used domain, for example "example.com" with "zitadel.cloud".
 Lastly, upload the certificate used to sign the reponses, provided for you under the
-URL {your_instance_domain}/saml/v2/certificate.
+URL \{your_instance_domain}/saml/v2/certificate.

 Then just press the button "Create" and the connection on Auth0 is configured.

@@ -45,7 +45,7 @@ can connect to ZITADEL as a SAML2 IDP.
 4. Download the ZITADEL-used certificate to sign the responses, so that AWS can validation the signature.

   You can download the certificate from following
-   URL: {your_instance_domain}/saml/v2/certificate
+   URL: \{your_instance_domain}/saml/v2/certificate

 5. Then upload the ".crt"-file to AWS and click "next".

@@ -30,7 +30,7 @@ Cloudflare will return an error "User email was not returned. API permissions ar

 1. On the Cloudflare dashboard go to Zero Trust, click settings, and then select "Authentication"
 2. Add a new login method with the type "OpenID Connect"
-3. Fill in the required information. Check the discovery endpoint of your instance (https://{your_domain}/.well-known/openid-configuration) for the urls. As mentioned in the Cloudflare docs the Certificate Url is jwks_uri.
+3. Fill in the required information. Check the discovery endpoint of your instance `https://{your_domain}/.well-known/openid-configuration` for the urls. As mentioned in the Cloudflare docs the Certificate Url is jwks_uri.
 4. Disable PKCE (Cloudflare requires a client secret for PKCE, which is currently not supported)
 5. Add the following claims: "openid", "profile", "email"
 6. Test the connection
@@ -52,7 +52,7 @@ Check your application, if everything is correct, press "Create".
 Complete the configuration as follows:

 - `Identity provider single sign-on URL`: $CUSTOM-DOMAIN/saml/v2/SSO
- `Certificate fingerprint`: You need to download the certificate from {your_instance_domain}/saml/v2/certificate and create a SHA1 fingerprint
+- `Certificate fingerprint`: You need to download the certificate from \{your_instance_domain}/saml/v2/certificate and create a SHA1 fingerprint

 Save the changes.

@@ -68,8 +68,8 @@ Create a new .xml file with the following minimal SAML metadata contents:

 Set or replace the variables with the values from the next screen as follows:

- `${ENTITYID}`: google.com/a/<your_domain>
- `${ACSURL}`: https://www.google.com/a/<your_domain>/acs
+- `${ENTITYID}`: `google.com/a/<your_domain>`
+- `${ACSURL}`: `https://www.google.com/a/<your_domain>/acs`

 `<your_domain>` is the domain you have verified in Google Workspace.

@@ -103,7 +103,7 @@ Save the settings.

 Now you should be all set to verify your setup:

- Open Gmail in an incognito session with the following link: https://mail.google.com/a/<your_domain>
+- Open Gmail in an incognito session with the following link: `https://mail.google.com/a/<your_domain>`
 - Enter your username and credentials
 - You should be redirected to Gmail and logged in

@@ -165,8 +165,8 @@ Create a new .xml file with the following minimal SAML metadata contents:

 Set or replace the variables with the values from the next screen as follows:

- `${ENTITYID}`: https://accounts.google.com/samlrp/metadata?rpid=<your_value>
- `${ACSURL}`: https://accounts.google.com/samlrp/acs?rpid=<your_value>
+- `${ENTITYID}`: `https://accounts.google.com/samlrp/metadata?rpid=<your_value>`
+- `${ACSURL}`: `https://accounts.google.com/samlrp/acs?rpid=<your_value>`

 Replace `<your_value>` with the values from the [SSO profile](#entity-id-and-acs-url).

@@ -200,7 +200,7 @@ Save the settings.

 Now you should be all set to verify your setup:

- Open Gmail in an incognito session with the following link: https://mail.google.com/a/<your_domain>
+- Open Gmail in an incognito session with the following link: `https://mail.google.com/a/<your_domain>`
 - Enter your username and credentials
 - You should be redirected to Gmail and logged in

@@ -40,7 +40,7 @@ With the following parameters

 | Parameter | Description | Example value|
 |---|---|---|
-| OIDCProviderMetadataURL | Is the url to the discovery endpoint, which is typically located at {your-domain}/.well-known/openid-configuration| https://<your_domain>.zitadel.cloud/.well-known/openid-configuration |
+| OIDCProviderMetadataURL | Is the url to the discovery endpoint, which is typically located at `{your-domain}/.well-known/openid-configuration`| `https://<your_domain>.zitadel.cloud/.well-known/openid-configuration` |
 | OIDCClientID | Is the ID of the zitadel application. You can find it on the settings page of the application.  | 123456789123@apache_test |
 | OIDCRedirectURI | Users will be redirected to this page after successful login. If you are using localhost or any other non-https endpoint, make sure to enable development mode in ZITADEL. | https://mysecureapp.io/secure/callback |
 | OIDCCryptoPassphrase | Create a secure passphrase. Consult the module's documentation for more details. | ... |
@@ -139,7 +139,7 @@ The Login Policy defines how the login process should look like and which authen
 The Default Redirect URI will be used, if a user calls the login page directly.
 More specifically, typically a client will initiate login with an auth request.
 The auth request contains a client-id and a redirect uri, that must match the configuration in ZITADEL.
-If there is no [auth request](https://zitadel.com/docs/apis/openidoauth/authrequest), users will be redirected to the Default Redirect URI, which is by default https://<custom_domain>/ui/console/
+If there is no [auth request](https://zitadel.com/docs/apis/openidoauth/authrequest), users will be redirected to the Default Redirect URI, which is by default `https://<custom_domain>/ui/console/`

 Reasons why ZITADEL doesn't have a redirect URI:

@@ -148,7 +148,7 @@ Reasons why ZITADEL doesn't have a redirect URI:

 We recommend setting your own default redirect URI, if you do not want end users to access ZITADEL console.

-Change default redirect url of instance: https://<custom_domain>/ui/console/settings?id=login
+Change default redirect url of instance: `https://<custom_domain>/ui/console/settings?id=login`

 <img
  src="/docs//img/guides/solution-scenarios/console-default-redirect.png"
@@ -18,7 +18,7 @@ You would have to create roles for administration and your clients in this very

 ## Create a project

-To create a project, navigate to your organization, then projects or directly via <https://{your_domain}.zitadel.cloud/ui/console/projects>, and then click the button to create a new project.
+To create a project, navigate to your organization, then projects or directly via `https://{your_domain}.zitadel.cloud/ui/console/projects`, and then click the button to create a new project.

 <img
  alt="Empty Project"
@@ -4,7 +4,7 @@ title: Feature Restrictions

 New self-hosted and [ZITADEL Cloud instances](https://zitadel.com/signin) are unrestricted by default.
 Self-hosters can change this default using the DefaultInstance.Restrictions configuration section.
-Users with the role IAM_OWNER can change the restrictions of their instance using the [Feature Restrictions Admin API](/category/apis/resources/admin/feature-restrictions).
+Users with the role IAM_OWNER can change the restrictions of their instance using the [Feature Restrictions Admin API](/apis/resources/admin/feature-restrictions).
 Currently, the following restrictions are available:

 - *Disallow public organization registrations* - If restricted, only users with the role IAM_OWNERS can create new organizations. The endpoint */ui/login/register/org* returns HTTP status 404 on GET requests, and 409 on POST requests.
@@ -232,4 +232,4 @@ The user that calls the management service must have [manager permissions](/docs
 A user can be either a human user or a service user.

 You can get [metadata of a user filtered by your query](/docs/apis/resources/mgmt/management-service-list-user-metadata) or [get a metadata object from a user by a specific key](/docs/apis/resources/mgmt/management-service-get-user-metadata).
-The management service allows you to set and delete metadata, see the [API documentation for users](/docs/category/apis/resources/mgmt/users).
+The management service allows you to set and delete metadata, see the [API documentation for users](/docs/apis/resources/mgmt/users).
@@ -220,7 +220,7 @@ Use metadata to store additional attributes of the users, such as organizational

 :::info
 Metadata must be added to users after the users were created. Currently metadata can't be added during user creation.  
-[API reference: User Metadata](/docs/category/apis/resources/mgmt/user-metadata)
+[API reference: User Metadata](/docs/apis/resources/mgmt/user-metadata)
 :::

 Request metadata from the userinfo endpoint by passing the required [reserved scope](/docs/apis/openidoauth/scopes#reserved-scopes) in your auth request.
@@ -232,5 +232,5 @@ You can assign roles from owned or granted projects to a user.

 :::info
 Authorizations must be added to users after the users were created. Currently metadata can't be added during user creation.  
-[API reference: User Authorization / Grants](/docs/category/apis/resources/auth/user-authorizations-grants)
+[API reference: User Authorization / Grants](/docs/apis/resources/auth/user-authorizations-grants)
 :::