diff --git a/docs/docs/concepts/structure/projects.md b/docs/docs/concepts/structure/projects.md index 16b6bf7e5..9c48517be 100644 --- a/docs/docs/concepts/structure/projects.md +++ b/docs/docs/concepts/structure/projects.md @@ -33,3 +33,15 @@ The display name is only to provide a human-readable name if needed. And the group should enable a better handling in ZITADEL console, like give a user all the roles of a specific group. (Not implemented yet) All applications in a project share the roles. Read more about roles [here](../../guides/manage/console/roles) + +## Default Project + +When creating a new ZITADEL instance you will find an automatically created project on the first created organization. +This default project does represent the ZITADEL project and is used to secure the different apps shipped with ZITADEL. +This includes the ZITADEL Management Console and APIs. + +We do not recommend changing any settings or using this project for anything else, as this could influence the behavior of ZITADEL. + +The default name of the project is "ZITADEL", this might differ on self-hosted instances, when you change the default name. + +![Default Project](/img/guides/solution-scenarios/console-default-project.png) diff --git a/docs/docs/guides/manage/console/instance-settings.mdx b/docs/docs/guides/manage/console/instance-settings.mdx index 0d00b9e0e..2e2a54392 100644 --- a/docs/docs/guides/manage/console/instance-settings.mdx +++ b/docs/docs/guides/manage/console/instance-settings.mdx @@ -107,6 +107,23 @@ The Login Policy defines how the login process should look like and which authen width="600px" /> +### Default Redirect URI + +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:///ui/console/ + +Reasons why ZITADEL doesn't have a redirect URI: +- The login has not been called with an OIDC authorize request +- The user landed on the login through an email link, e.g. Password Reset, Initialize User + +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:///ui/console/settings?id=login + +![Login Policy Advanced Setting: Default Redirect URL](/img/guides/solution-scenarios/console-default-redirect.png) + ### Passwordless Passwordless authentication means that the user doesn't need to enter a password to login. In our case the user has to enter his loginname and as the next step proof the identity through a registered device or token. diff --git a/docs/docs/guides/manage/console/overview.mdx b/docs/docs/guides/manage/console/overview.mdx index 18ed560ff..d6386bb7f 100644 --- a/docs/docs/guides/manage/console/overview.mdx +++ b/docs/docs/guides/manage/console/overview.mdx @@ -22,3 +22,8 @@ Depending on your use case, multiple organizations can be created (B2B) or you c /> If your new to console, you'll probably want to set some settings initially. Continue reading instance settings on the next page. + +## Prevent console access + +In some use cases you want to prevent users from accessing the ZITADEL management console. +Please follow this [guide](/docs/guides/solution-scenarios/restrict-console) to achieve that. \ No newline at end of file diff --git a/docs/docs/guides/solution-scenarios/restrict-console.mdx b/docs/docs/guides/solution-scenarios/restrict-console.mdx new file mode 100644 index 000000000..625202368 --- /dev/null +++ b/docs/docs/guides/solution-scenarios/restrict-console.mdx @@ -0,0 +1,82 @@ +--- +title: Prevent users from accessing ZITADEL console +sidebar_label: Limit access to console +--- + +ZITADEL includes a console that allows Managers 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 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 Console +- Only managers should be able to access Console to manage their users + +At the moment it is not possible to simply disable the Console but with the configuration described in this guide you can prevent users from accessing the Console. + +## Self-hosted + +If you are running ZITADEL self-hosted we recommend to restrict the access to ZITADEL Console via WAF/reverse-proxy for Non-Manager users + +## ZITADEL Cloud (and self-hosted) + +### Default redirect url + +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. + +Read more about how to set the default redirect URI: [Settings - Default Redirect URI](/docs/guides/manage/console/instance-settings#default-redirect-uri) + +### Restricting Console in default-project + +With this workaround, you will limit users from accessing the [default-project](/docs/concepts/structure/projects#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. +By default, this setting is disabled, so all users can access the project. + +![Project Settings: Check for Project on authentication](/img/guides/solution-scenarios/console-check-project-auth.png) + +Start by granting the organization of your managers, that should be able to access the Console, the [default project](/docs/concepts/structure/projects#default-project): + +1. Click on the default-project > Grants > New + + ![Project Settings: Default Project - Grants](/img/guides/solution-scenarios/console-zitadel-project-grants.png) + +2. On the next screen select the organization to which you want to give the grant + ![Project Settings: Grants - Choose Organization](/img/guides/solution-scenarios/console-create-project-grant-org.png) + +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. + +To avoid accidental lock-out, the [default project](/docs/concepts/structure/projects#default-project) hides the checkbox "Check Project on Authentication" in the Console: +![Default Project](/img/guides/solution-scenarios/console-default-project.png) + +You need to use the [update project API call](/docs/apis/resources/mgmt/management-service-update-project) to set the configuration on the project. + +First you need a user with manager permissions to change the project settings in that organization. +This means either you add the manager to the organization or you use a manager on the instance level with "IAM-OWNER" permissions. +After that create a Personal Access Token (PAT) for the manager. + +More detailed information about creating a PAT and manager roles you can find [here](/docs/guides/integrate/pat) + +Then you have to send the following request: +```bash +curl -L -X PUT "https://$CUSTOM_DOMAIN/management/v1/projects/$PROJECT_ID" \ +-H 'Content-Type: application/json' \ +-H 'Accept: application/json' \ +-H "Authorization: Bearer $PAT" \ +--data-raw '{ + "name": "ZITADEL", + "projectRoleAssertion": false, + "projectRoleCheck": false, + "hasProjectCheck": true, + "privateLabelingSetting": "PRIVATE_LABELING_SETTING_UNSPECIFIED" +}' +``` + +Where +- CUSTOM_DOMAIN is your domain, f.e. mydemo.zitadel.cloud +- PAT is your service user's personal access token +- PROJECT_ID is the default-project's ID that can be found in Console, see screenshot above + +You should now be able to login with users of organization that have the grant (in this example users of the organization "Customer-A"). +All other users should see the following error message after authentication: + +![Console access restricted](/img/guides/solution-scenarios/console-access-restricted.png) + diff --git a/docs/sidebars.js b/docs/sidebars.js index 1cc318d6b..23d64e833 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -417,6 +417,7 @@ module.exports = { "guides/solution-scenarios/configurations", "guides/solution-scenarios/frontend-calling-backend-API", "guides/solution-scenarios/device-authorization", + "guides/solution-scenarios/restrict-console", { type: "category", label: "Onboarding Customers and Users", diff --git a/docs/static/img/guides/solution-scenarios/console-access-restricted.png b/docs/static/img/guides/solution-scenarios/console-access-restricted.png new file mode 100644 index 000000000..a1486f915 Binary files /dev/null and b/docs/static/img/guides/solution-scenarios/console-access-restricted.png differ diff --git a/docs/static/img/guides/solution-scenarios/console-check-project-auth.png b/docs/static/img/guides/solution-scenarios/console-check-project-auth.png new file mode 100644 index 000000000..b686b0c25 Binary files /dev/null and b/docs/static/img/guides/solution-scenarios/console-check-project-auth.png differ diff --git a/docs/static/img/guides/solution-scenarios/console-create-project-grant-org.png b/docs/static/img/guides/solution-scenarios/console-create-project-grant-org.png new file mode 100644 index 000000000..4ede5860c Binary files /dev/null and b/docs/static/img/guides/solution-scenarios/console-create-project-grant-org.png differ diff --git a/docs/static/img/guides/solution-scenarios/console-default-project.png b/docs/static/img/guides/solution-scenarios/console-default-project.png new file mode 100644 index 000000000..67ddf8b4a Binary files /dev/null and b/docs/static/img/guides/solution-scenarios/console-default-project.png differ diff --git a/docs/static/img/guides/solution-scenarios/console-default-redirect.png b/docs/static/img/guides/solution-scenarios/console-default-redirect.png new file mode 100644 index 000000000..5f2437068 Binary files /dev/null and b/docs/static/img/guides/solution-scenarios/console-default-redirect.png differ diff --git a/docs/static/img/guides/solution-scenarios/console-zitadel-project-grants.png b/docs/static/img/guides/solution-scenarios/console-zitadel-project-grants.png new file mode 100644 index 000000000..36651b3b4 Binary files /dev/null and b/docs/static/img/guides/solution-scenarios/console-zitadel-project-grants.png differ