mirror of
https://github.com/andwati/zitadel.git
synced 2026-10-20 06:24:25 +00:00
Florian ForsterandGitHub
2763e93a61
## What
Shorten the `title` frontmatter on 20 docs pages so that the rendered
`<title>` tag stays within the 70-character SEO limit.
The root layout appends ` | ZITADEL Docs` (15 chars) to every page
title, meaning the raw frontmatter `title` must be ≤ 55 characters. A
site scan flagged all 20 pages for the "Title too long" warning (titles
ranged from 71 to 92 characters in the final rendered tag).
## Why
Search engines may truncate or ignore `<title>` tags longer than 70
characters, hurting click-through rates and keyword relevance in search
results.
## How
Each title was rewritten to:
- Fit within 55 characters (leaving room for ` | ZITADEL Docs`)
- Front-load the primary search keyword (product name, protocol, or
feature)
- Include "ZITADEL" where users realistically search for `{feature}
ZITADEL`
- Avoid generic filler words ("Configure", "Set up", "Support for")
All 20 files already have a `sidebar_label` field that preserves the
original descriptive title for sidebar navigation — no navigation
changes result from this PR.
## Pages updated
| Page | Before (chars) | After (chars) |
|---|---|---|
| concepts/features/passkeys | 82 | 64 |
| guides/integrate/identity-providers/openldap | 72 | 58 |
| guides/solution-scenarios/b2b | 78 | 59 |
| guides/integrate/services/cloudflare-oidc | 86 | 54 |
| guides/integrate/login/hosted-login | 71 | 55 |
| guides/integrate/service-accounts/private-key-jwt | 76 | 56 |
| guides/integrate/service-accounts/client-credentials | 78 | 60 |
| guides/integrate/services/google-cloud | 92 | 57 |
| guides/solution-scenarios/saas | 88 | 65 |
| guides/migrate/sources/auth0 | 73 | 65 |
| guides/integrate/login-ui/oidc-standard | 81 | 55 |
| guides/integrate/login-ui/username-password | 73 | 59 |
| guides/integrate/login-ui/device-auth | 78 | 60 |
| guides/integrate/identity-providers/linkedin_oauth | 72 | 58 |
| guides/integrate/identity-providers/pingfederate-saml | 74 | 61 |
| guides/integrate/service-accounts/personal-access-token | 82 | 62 |
| legal/service-description/cloud-service-description | 76 | 61 |
| guides/integrate/login/login-users | 83 | 55 |
| guides/integrate/identity-providers/migrate | 74 | 65 |
| guides/manage/console/projects-overview | 71 | 62 |
All final `<title>` values are between 54 and 66 characters (well under
the 70-char limit).
140 lines
7.2 KiB
Plaintext
140 lines
7.2 KiB
Plaintext
---
|
|
title: "ZITADEL Projects: Manage Apps, Services & Roles"
|
|
description: "Use projects to group applications and manage roles and authorizations across multiple clients."
|
|
sidebar_label: Projects
|
|
sidebar_position: 4
|
|
---
|
|
|
|
import ProjectDescription from "../../../concepts/structure/_project_description.mdx";
|
|
|
|
## What is a project?
|
|
|
|
<ProjectDescription components={props.components} name="ProjectDescription" />
|
|
|
|
A Project is the vessel that holds your Applications and Roles. It defines the security context for a specific software solution.
|
|
|
|
### Example Scenario
|
|
Imagine you are building a **Point of Sales (POS)** platform. In ZITADEL, you would create one Project (e.g., named `POS`).
|
|
* **Applications:** Your web portal for administration, your iOS app, and your Android app would all be defined as **Applications** within this single Project.
|
|
* **Roles:** You would create **Roles** (e.g., `admin`, `cashier`, `viewer`) inside this Project.
|
|
* **Role assignment:** All applications in this project share these roles, allowing you to create unified role assignments for your users across all platforms.
|
|
|
|
|
|
|
|
## Core Components
|
|
|
|
### Applications
|
|
Applications define the different clients (web apps, native mobile apps, server-side APIs) that share the same roles and security context.
|
|
At the moment, we support OIDC and almost every OAuth2 client. We'll be expanding this with SAML shortly.
|
|
Go to [Applications](./applications-overview) for more details.
|
|
|
|
### Roles
|
|
A role consists of different attributes, but only the **Key** is relevant to the role assignment and must be unique within the project.
|
|
* **Key:** The identifier used in code (e.g., `role.admin`).
|
|
* **Display Name:** A human-readable name for the UI.
|
|
* **Group:** Enables better handling in the ZITADEL Management Console (e.g., giving a user all roles of a specific group).
|
|
|
|
Read more about managing roles [here](./roles).
|
|
|
|
## The Default Project
|
|
When creating a new ZITADEL instance, you will find an automatically created project in the first organization.
|
|
This **Default Project** (named "ZITADEL") protects the ZITADEL Management Console and APIs.
|
|
|
|
<Callout type="caution">
|
|
We do not recommend changing any settings in the Default Project or using it for your own applications, as this could influence the behavior of ZITADEL itself.
|
|
</Callout>
|
|
|
|
|
|
|
|
## Create a Project
|
|
|
|
To create a project:
|
|
1. Navigate to your Organization in the Console.
|
|
2. Go to **Projects** (or visit `https://${CUSTOM_DOMAIN}.zitadel.cloud/ui/console/projects`).
|
|
3. Click the **Create New Project** button.
|
|
|
|
<img
|
|
alt="Empty Project"
|
|
src="/docs/img/console_projects_empty.png"
|
|
width="270px"
|
|
/>
|
|
|
|
4. Enter your project name and continue.
|
|
|
|
## Granted Projects (B2B)
|
|
|
|
A powerful feature of ZITADEL is the ability to **Grant** a project to other organizations. This is essential for B2B scenarios where you sell your software to business partners.
|
|
|
|
* **The Concept:** You enable another organization to use your Project.
|
|
* **Delegation:** The granted organization can manage the role assignments of *their own users* for your project. They can assign the roles you defined to their employees without your intervention.
|
|
* **Isolation:** You can select specifically which roles are available to the granted organization. This allows you to restrict features (e.g., "Premium" roles) per customer.
|
|
|
|
Using the POS example above: You could grant the `POS` project to a partner organization. That partner can then log in with their own domain, use their own branding, and manage their own cashier users, all while using your underlying application structure.
|
|
|
|
<img
|
|
alt="Granted project"
|
|
src="/docs/img/guides/console/grantedprojectgrid.png"
|
|
width="320px"
|
|
/>
|
|
|
|
### How to Grant a Project
|
|
|
|
1. Navigate to the Project you want to share (e.g., `POS`).
|
|
2. In the **Project Grants** section, click **New**.
|
|
|
|
<img src="/docs/img/guides/console/grantsmenu.png" alt="Grants" width="170px" />
|
|
|
|
3. Enter the **Domain** of the partner organization you want to grant access to.
|
|
* *Tip: If you don't know the domain, navigate to the Organization detail page to find it.*
|
|
4. Search and select the organization.
|
|
5. Select the **Roles** you want to grant to this organization and click **Save**.
|
|
|
|
## Project Settings
|
|
|
|
You can customize the behavior of your project, particularly regarding how login screens look and how tokens are issued.
|
|
|
|
### Branding
|
|
If you have different designs for your organizations (Private Labeling), you can define the login behavior on the project detail page.
|
|
|
|
<img
|
|
src="/docs/img/guides/console/projectbranding.png"
|
|
alt="Project branding"
|
|
width="400px"
|
|
/>
|
|
|
|
| Setting | Description |
|
|
|:-----------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
| **Unspecified** | If nothing is specified, the system default settings will trigger. |
|
|
| **Enforce project's policy** | This forces the branding of the organization that *owns* the project throughout the entire login process. Useful if you want your users to always see *your* brand, even if they belong to a partner org. |
|
|
| **Allow login user policy** | The login starts with the project's branding. However, as soon as the user is identified (e.g., by entering their email), the branding switches to match the user's organization. |
|
|
|
|
In a B2B use case, you would typically use **Allow login user policy**. If you want to skip the detection step, you can preselect an organization using the [Organization Domain scope](/apis/openidoauth/scopes#reserved-scopes) (e.g., `urn:zitadel:iam:org:domain:primary:{domainname}`).
|
|
|
|
### Role Settings
|
|
You can configure strict security checks regarding roles during authentication.
|
|
|
|
<img
|
|
src="/docs/img/guides/console/rolesettings.png"
|
|
width="700px"
|
|
alt="Role settings"
|
|
/>
|
|
|
|
* **Assert Roles on Authentication:** Role information is sent from the Userinfo endpoint (and in tokens, depending on app settings).
|
|
* **Check Role Assignment on Authentication:** Users are **only** allowed to log in if they have at least one role assigned for this project. If they have no roles, access is denied immediately.
|
|
* **Check for Project on Authentication:** Checks if the user's organization actually has a grant for this project. If not, the user cannot be authenticated.
|
|
|
|
### Roles in Tokens
|
|
If you want roles to appear directly inside your Access or ID Tokens (to avoid calling the Userinfo endpoint), you must enable this per application.
|
|
|
|
1. Navigate to your **Application**.
|
|
2. Open **Token Settings**.
|
|
3. Check **Assert Roles on Authentication**.
|
|
|
|
<img
|
|
src="/docs/img/guides/console/tokenroles.png"
|
|
width="700px"
|
|
alt="Roles in token"
|
|
/>
|
|
|
|
You can learn more about Application and Token settings [here](./applications-overview).
|