diff --git a/apps/docs/components/prevent-lockout.tsx b/apps/docs/components/prevent-lockout.tsx
new file mode 100644
index 000000000..67cfc0fc6
--- /dev/null
+++ b/apps/docs/components/prevent-lockout.tsx
@@ -0,0 +1,26 @@
+import { Callout } from 'fumadocs-ui/components/callout';
+import Link from 'next/link';
+
+export function PreventLockout() {
+ return (
+
+ Login policy settings misconfigurations that occur during the testing phase can easily lead to a{' '}
+ lockout. To ensure you don't lose access to your instance:
+
+
+ Generate a backup PAT: Create a{' '}
+
+ Service Account Personal Access Token
+ {' '}
+ with the IAM_OWNER role to revert any login UI misconfigurations using the API.
+
+
+ Add a second Instance Administrator: Always designate at least one{' '}
+
+ second instance administrator
+ .
+
+
+
+ );
+}
diff --git a/apps/docs/content/guides/solution-scenarios/restrict-console.mdx b/apps/docs/content/guides/solution-scenarios/restrict-console.mdx
index 0c44ef070..00806fa27 100644
--- a/apps/docs/content/guides/solution-scenarios/restrict-console.mdx
+++ b/apps/docs/content/guides/solution-scenarios/restrict-console.mdx
@@ -4,59 +4,76 @@ description: "Guidelines and strategies for restricting user access to the ZITAD
sidebar_label: Limit access to management console
---
-ZITADEL includes a management console that allows Administrators to configure all resources. All uses, including end-users, by default, view and manage their profile information.
-In some use cases you want to prevent users from accessing the management console, this could be:
-- User management is integrated into your own app
-- Users login via SSO and should not be able to change their data in the Management Console
-- Only administrators should be able to access Management Console to manage their users
+ZITADEL includes a Management Console that allows administrators to configure all resources. By default, all users, including end users, can view and manage their profile information.
+In some cases, you may want to prevent users from accessing the Management Console. Common reasons include:
+- User management is integrated into your own application.
+- Users log in via SSO and should not be able to change their data in the Management Console.
+- Only administrators should be able to access the Management Console to manage users.
-At the moment it is not possible to simply disable the Management Console, but with the settings described in this guide, you can prevent users from accessing the Console.
+While it is not currently possible to completely disable the Management Console, you can prevent users from accessing it by following the strategies described in this guide.
## Self-hosted
-If you are running ZITADEL self-hosted, we recommend restricting the access to ZITADEL Management Console via WAF/reverse-proxy for Non-Administrator users
+If you are running a self-hosted instance of ZITADEL, we recommend restricting access to the Management Console via a Web Application Firewall (WAF) or reverse proxy for non-administrator users.
## ZITADEL Cloud (and self-hosted)
-### Default redirect url
+### Default redirect URI
-One goal is to never send the end user to the ZITADEL management console.
-This does make sense if you build your own user profile page within your application.
-In that case you probably want to redirect the user to your own application, instead of to the console.
+One goal is to never send the end user to the ZITADEL Management Console.
+This is particularly useful if you have built your own user profile page within your application.
+In such cases, you likely want to redirect users to your own application instead of the console.
Read more about how to set the default redirect URI: [Settings - Default Redirect URI](/guides/manage/console/default-settings#default-redirect-uri)
+
+
### Restricting Management Console in default-project
-With this workaround, you will limit users from accessing the [default-project](/guides/manage/console/projects-overview#the-default-project) if they are not explicitly granted to use this project.
-When setting the "Check for Project on Authentication" setting on a project, only users of organizations with a grant to that project can access it.
+With this workaround, you will limit users from accessing the [default-project](/guides/manage/console/projects-overview#the-default-project) if they are not explicitly granted access to it.
+When enabling the "**Authentication is restricted to users from organizations that have been granted access to this project**" setting on a project, only users from organizations with a Project Grant for that project can access it.
By default, this setting is disabled, so all users can access the project.
+
+ Before a user can be authenticated, it is verified that their affiliated organization has been granted access to this project. Authentication is not permitted for users from unauthorized organizations.
+
+
-Start by granting the organization of your administrators that should be able to access the Management Console, the [default project](/guides/manage/console/projects-overview#the-default-project):
+Start by granting the organization of your administrators access to the ZITADEL project (default project):
+
-1. Click on the default-project > Grants > New +
- 
+
+ 1. Go to the **ZITADEL** project, select **Project Grants**, and click **New**.
+ 
+
-2. On the next screen select the organization to which you want to give the grant
- 
+
+ Select the organization you want to grant access to.
+ 
+
-3. You can skip the screen with the role selection and click save
-4. Make sure the grant is in now in the overview and marked as active.
+
+ You can skip the role selection and click **Save**.
+
-To avoid accidental lock-out, the [default project](/guides/manage/console/projects-overview#the-default-project) hides the checkbox "Check Project on Authentication" in the Management Console:
+
+ Ensure the grant appears in the overview and is marked as **Active**.
+
+
+
+To avoid accidental lockout, the [default project](/guides/manage/console/projects-overview#the-default-project) hides the "**Authentication is restricted to users from organizations that have been granted access to this project**" checkbox in the Management Console:
-You need to use the [update project API call](/reference/api/management/zitadel.management.v1.ManagementService.UpdateProject) to set the settings on the project.
+You need to use the [Update Project API](/reference/api/management/zitadel.management.v1.ManagementService.UpdateProject) to configure this setting on the project.
First, you need a user with administrator permissions to change the project settings in that organization.
-This means either you add the manager to the organization or you use an administrator on the instance level with "IAM-OWNER" permissions.
-After that create a Personal Access Token (PAT) for the administrator.
+This means either you add the Administrator to the organization or you use an administrator on the instance level with `IAM-OWNER` permissions.
+After that, create a Personal Access Token (PAT) for the administrator.
-More detailed information about creating a PAT and administrator roles you can find [here](/guides/integrate/service-accounts/personal-access-token)
+More detailed information about creating a PAT and Administrator Roles can be found [here](/guides/integrate/service-accounts/personal-access-token).
-Then you have to send the following request:
+Then, send the following request:
```bash
curl -L -X PUT "https://${CUSTOM_DOMAIN}/management/v1/projects/${PROJECT_ID}" \
-H 'Content-Type: application/json' \
@@ -71,12 +88,17 @@ curl -L -X PUT "https://${CUSTOM_DOMAIN}/management/v1/projects/${PROJECT_ID}" \
}'
```
-Where
-- `${CUSTOM_DOMAIN}` is your Custom Domain, f.e. mydemo.zitadel.cloud
-- `${PAT}` is your service account's personal access token
-- `${PROJECT_ID}` is the default-project's ID that can be found in Management Console see screenshot above
+Where:
+- `${CUSTOM_DOMAIN}` is your custom domain (e.g., `mydemo.zitadel.cloud`).
+- `${PAT}` is the administrator's Personal Access Token.
+- `${PROJECT_ID}` is the default project's ID, which can be found in the Management Console (see screenshot above).
-You should now be able to log in with users of the organization that have the grant (in this example users of the organization "Customer-A").
+
+ You can also use the [V2 Update Project API](/reference/api/project/zitadel.project.v2.ProjectService.UpdateProject) to perform this action.
+
+
+You should now be able to log in with users of the organization that have the Project Grant (in this example, users of the organization "Customer-A").
All other users should see the following error message after authentication:
+
diff --git a/apps/docs/content/guides/start/quickstart.mdx b/apps/docs/content/guides/start/quickstart.mdx
index 46e60267f..7be70b9a6 100644
--- a/apps/docs/content/guides/start/quickstart.mdx
+++ b/apps/docs/content/guides/start/quickstart.mdx
@@ -1072,12 +1072,7 @@ ZITADEL handles the complexity of the OIDC handshake so your app stays secure wi
## Success! 🚀
You’ve successfully integrated ZITADEL into an application.
-
- Login policy settings misconfigurations that occur during the testing phase can easily lead to a [lockout](/legal/policies/account-lockout-policy). To ensure you don't lose access to your instance:
-
- 1. **Generate a backup PAT:** Create a [Service Account Personal Access Token](/guides/integrate/service-accounts/personal-access-token) with the [`IAM_OWNER`](/guides/manage/console/administrators) role to revert any login UI misconfigurations using the API.
- 2. **Add a second Instance Administrator:** Always designate at least one [**second instance administrator**](/guides/manage/console/administrators).
-
+
### What’s next?
- [**Example Applications**](/examples/introduction): Find more comprehensive guides and examples for the different frameworks
diff --git a/apps/docs/mdx-components.tsx b/apps/docs/mdx-components.tsx
index 4d7de8fb1..d12fcd85d 100644
--- a/apps/docs/mdx-components.tsx
+++ b/apps/docs/mdx-components.tsx
@@ -7,6 +7,7 @@ import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Step, Steps } from 'fumadocs-ui/components/steps';
import Admonition from '@/components/docusaurus/admonition';
import { GithubCodeBlock } from '@/components/github-code-block';
+import { PreventLockout } from '@/components/prevent-lockout';
export function useMDXComponents(components?: MDXComponents): MDXComponents {
return {
@@ -20,6 +21,7 @@ export function useMDXComponents(components?: MDXComponents): MDXComponents {
APIPage,
TerminologyUpdate,
GithubCodeBlock,
+ PreventLockout,
...components,
};
}
diff --git a/apps/docs/public/img/guides/solution-scenarios/console-check-project-auth.png b/apps/docs/public/img/guides/solution-scenarios/console-check-project-auth.png
index b686b0c25..7e251cb0f 100644
Binary files a/apps/docs/public/img/guides/solution-scenarios/console-check-project-auth.png and b/apps/docs/public/img/guides/solution-scenarios/console-check-project-auth.png differ