chore: rename authorization to role assignment (#11588)

# Which Problems Are Solved

As part of the naming consistency initiative, the terms Authorization,
User grants, internal authorization and other similar terms that are
used in the context of assigning project roles to users are replaced by
Role Assignments in the UI, API docs, and documentation.

# How the Problems Are Solved

By replacing the following terms with Role Assignments in API docs,
Console UI, and guides.

- Authorization
- internal authorization
- external authorization
- User Grant
- Roles and Authorizations

By adding a note in the API docs to make it clear that Authorization
within the context of Authorization Service API refers to role
assignments, not to OAuth authorization as it is still used in the APIs.

By updating some screenshots in documentation / guides to show "Role
Assignments" instead of "Authorizations" in the UI.

# Additional Changes

N/A

# Additional Context

- Closes https://github.com/zitadel/zitadel/issues/11289

---------

Co-authored-by: Copilot <[email protected]>
This commit is contained in:
Gayathri Vijayan
2026-02-17 13:14:57 +01:00
committed by GitHub
co-authored by Copilot
parent fa5e76661a
commit 93a4ed8857
76 changed files with 1066 additions and 1015 deletions
@@ -2,9 +2,9 @@
title: Code examples
---
Actions are a powerful tool to extend ZITADEL and you might wonder what use cases actions can be used for.
Actions are a powerful tool to extend ZITADEL, and you might wonder what use cases actions can be used for.
This page provides a non-exhaustive list of possibilities which is provided by [examples](https://github.com/zitadel/actions/tree/main/examples). If a use case is missing feel free to contribute an issue or pull request to the repository, thanks in advance 🤗.
This page provides a non-exhaustive list of possibilities which is provided by [examples](https://github.com/zitadel/actions/tree/main/examples). If a use case is missing, feel free to contribute an issue or pull request to the repository, thanks in advance 🤗.
## Customize OIDC response
@@ -16,7 +16,7 @@ Append claims returned on OIDC requests.
- [Pre Userinfo creation](./complement-token#pre-userinfo-creation-id-token-userinfo-introspection-endpoint)
- [Pre access token creation](./complement-token#pre-access-token-creation)
### Set hardcoded claim
### Set a hardcoded claim
Extend the claims by a hardcoded value.
@@ -31,7 +31,7 @@ https://github.com/zitadel/actions/blob/main/examples/add_claim.js
### Set dynamic claim from user metadata
Extend the claims by dynamically read metadata from a user and sets the picture-claim if idpPicture-metadata value is present.
Extend the claims by dynamically reading metadata from a user and sets the picture-claim if idpPicture-metadata value is present.
<details open="">
<summary>{props.summary ? props.summary : 'Code example'}</summary>
@@ -44,7 +44,7 @@ https://github.com/zitadel/actions/blob/main/examples/add_picture_claim_from_idp
### Set dynamic claim from organization metadata
Extend the claims by dynamically read metadata from an organization and sets the present metadata.
Extend the claims by dynamically reading metadata from an organization and sets the present metadata.
<details open="">
<summary>Code example</summary>
@@ -105,7 +105,7 @@ https://github.com/zitadel/actions/blob/main/examples/set_custom_attribute.js
### Set dynamic attribute from organization metadata
Extend the attributes by dynamically read metadata from an organization and sets the present metadata.
Extend the attributes by dynamically reading metadata from an organization and sets the present metadata.
<details open="">
<summary>Code example</summary>
@@ -118,7 +118,7 @@ https://github.com/zitadel/actions/blob/main/examples/org_metadata_attribute.js
## Manipulate user
You can automate manual tasks like setting default grants during user creation.
You can automate manual tasks such as assigning default roles during user creation.
### Set email always verified
@@ -140,9 +140,9 @@ https://github.com/zitadel/actions/blob/main/examples/verify_email.js
</details>
### Add grants to users
### Assign roles to users
Allows you to add default user grants to a user after it was created or federated.
Allows you to assign default roles to a user after the user was created or federated.
#### Triggers
@@ -184,7 +184,7 @@ https://github.com/zitadel/actions/blob/main/examples/add_metadata.js
## Use provided fields of identity providers
If you want to ensure that the data of a user are always up-to-date, you can automatically update user fields during authentication and save time of your customers and your team.
If you want to ensure that the data of a user are always up to date, you can automatically update user fields during authentication and save time of your customers and your team.
### Trigger
@@ -193,7 +193,7 @@ If you want to ensure that the data of a user are always up-to-date, you can aut
### Fields provided by Okta as OIDC IdP
If you use [Okta as an identity provider](/guides/integrate/identity-providers/okta-oidc) you can improve the onboarding experience of new users by prefilling some basic information during authentication.
If you use [Okta as an identity provider](/guides/integrate/identity-providers/okta-oidc), you can improve the onboarding experience of new users by prefilling some basic information during authentication.
<details open="">
<summary>Code example</summary>
@@ -206,7 +206,7 @@ https://github.com/zitadel/actions/blob/main/examples/okta_identity_provider.js
### Fields provided by Gitlab
If you use [Gitlab as an identity provider](/guides/integrate/identity-providers/gitlab) you can improve the onboarding experience of new users by prefilling some basic information during authentication.
If you use [Gitlab as an identity provider](/guides/integrate/identity-providers/gitlab), you can improve the onboarding experience of new users by prefilling some basic information during authentication.
<details open="">
<summary>Code example</summary>
@@ -217,9 +217,9 @@ https://github.com/zitadel/actions/blob/main/examples/gitlab_identity_provider.j
</details>
### Fields provided by Github
### Fields provided by GitHub
If you use [Github as an identity provider](/guides/integrate/identity-providers/github) you can improve the onboarding experience of new users by prefilling some basic information during authentication.
If you use [GitHub as an identity provider](/guides/integrate/identity-providers/github), you can improve the onboarding experience of new users by prefilling some basic information during authentication.
<details open="">
<summary>Code example</summary>
@@ -232,7 +232,7 @@ https://github.com/zitadel/actions/blob/main/examples/github_identity_provider.j
### Claims provided by a generic OIDC identity provider
If you use a [generic OIDC identity provider](/guides/integrate/identity-providers/migrate#migrate-generic-oidc-provider) you can improve the onboarding experience of new users by prefilling some basic information during authentication.
If you use a [generic OIDC identity provider](/guides/integrate/identity-providers/migrate#migrate-generic-oidc-provider), you can improve the onboarding experience of new users by prefilling some basic information during authentication.
<details open="">
<summary>Code example</summary>
@@ -245,7 +245,7 @@ https://github.com/zitadel/actions/blob/main/examples/set_idp_picture_metadata.j
### Attributes provided by Okta as SAML IDP
If you use [Okta as an identity provider](/guides/integrate/identity-providers/okta_saml#add-attribute-statements) you can improve the onboarding experience of new users by prefilling some basic information during authentication.
If you use [Okta as an identity provider](/guides/integrate/identity-providers/okta_saml#add-attribute-statements), you can improve the onboarding experience of new users by prefilling some basic information during authentication.
<details open="">
<summary>Code example</summary>
@@ -258,7 +258,7 @@ https://github.com/zitadel/actions/blob/main/examples/okta_saml_prefil_register_
### Attributes provided by Microsoft Entra as SAML IDP
If you use [Microsoft Entra as SAML identity provider](/guides/integrate/identity-providers/azure-ad-saml) you can improve the onboarding experience of new users by prefilling some basic information during authentication.
If you use [Microsoft Entra as SAML identity provider](/guides/integrate/identity-providers/azure-ad-saml), you can improve the onboarding experience of new users by prefilling some basic information during authentication.
<details open="">
<summary>Code example</summary>
@@ -271,7 +271,7 @@ https://github.com/zitadel/actions/blob/main/examples/entra_id_saml_prefil_regis
### Attributes provided by a generic SAML identity provider
If you use a [SAML identity provider like mocksaml](/guides/integrate/identity-providers/mocksaml) you can improve the onboarding experience of new users by prefilling some basic information during authentication.
If you use a [SAML identity provider like mocksaml](/guides/integrate/identity-providers/mocksaml), you can improve the onboarding experience of new users by prefilling some basic information during authentication.
<details open="">
<summary>Code example</summary>
@@ -282,9 +282,9 @@ https://github.com/zitadel/actions/blob/main/examples/post_auth_saml.js
</details>
## Context aware execution
## Context-aware execution
Based on the context the execution path of an action can change. ZITADEL allows complex execution paths of course. 😎
Based on the context, the execution path of an action can change. ZITADEL allows complex execution paths, of course. 😎
### Based on auth request information
+7 -5
View File
@@ -43,12 +43,14 @@ title: Objects
## user grant
A user grant is a role assignment for a user.
- `projectID` *string*
Required. ID of the project to be granted
Required. ID of the project for the role assignment.
- `projectGrantID` *string*
Optional. If the grant is for a project grant, include projectGrantID
Optional. If the role assignment is for a project grant, include projectGrantID
- `roles` Array of *string*
Containing the roles
Roles to assign to the user.
## user
@@ -182,11 +184,11 @@ This object represents [the claims](../openidoauth/claims) which will be written
- `email_verified` *bool*
- `updated_at` *Number*
Additionally, there could be fields depending on the configuration of your [project](../../guides/manage/console/projects-overview#role-settings) and your [application](../../guides/manage/console/applications-overview#token-settings)
There could be additional fields depending on the configuration of your [project](../../guides/manage/console/projects-overview#role-settings) and your [application](../../guides/manage/console/applications-overview#token-settings)
## user grant list
This object represents a list of user grant stored in ZITADEL.
This object represents a list of user grants (role assignments) stored in ZITADEL.
- `count` *Number*
- `sequence` *Number*
+9 -8
View File
@@ -10,18 +10,19 @@ ZITADEL exposes all features via different gRPC and REST APIs and provides SDKs
The [OpenID Connect & OAuth endpoints](/apis/openidoauth/endpoints) and [SAML 2.0 endpoints](/apis/saml/endpoints) are implemented and exposed according to the specific standards. Managing resources such as users, organizations, instances, or settings must be done with the different [ZITADEL APIs](#zitadel-apis-resource-based).
[Actions](/guides/manage/console/actions-overview) allow to extend ZITADEL with custom code to change default behaviors or calling external systems.
[Actions](/guides/manage/console/actions-overview) allow extending ZITADEL with custom code to change default behaviors or calling external systems.
## Authentication & authorization
## Authentication & Authorization
In this section, “authorization” refers to protocol- and API-level authorization (for example OAuth scopes and claims, OIDC, SAML assertions, and API access) and is distinct from the “authorization” term used in ZITADEL role-assignment APIs.
### Authentication for users (interactive)
ZITADEL implements industry standards such as OpenID Connect, OAuth 2.0, or SAML for authentication.
Please refer to our guides how to [authenticate users](/guides/integrate/login/login-users) through an interactive authentication process.
Please refer to our guides on how to [authenticate users](/guides/integrate/login/login-users) through an interactive authentication process.
For user authentication on devices with limited accessibility (eg, SmartTV, Smart Watch etc.) use the [device authorization grant](/guides/integrate/login/oidc/device-authorization).
For user authentication on devices with limited accessibility (eg, SmartTV, Smartwatch, etc.) use the [device authorization grant](/guides/integrate/login/oidc/device-authorization).
Additionally, you can use the [session API](/reference/api/session) to authenticate users, for example by building a [custom login UI](/guides/integrate/login-ui).
Additionally, you can use the [session API](/reference/api/session) to authenticate users, for example, by building a [custom login UI](/guides/integrate/login-ui).
### Authenticate service accounts
@@ -45,8 +46,8 @@ The [OIDC Playground](https://zitadel.com/playgrounds/oidc) is for testing OpenI
### Custom
ZITADEL allows to authenticate users by creating a session with the [Session API](/reference/api/session), get OIDC authentication request details with the [OIDC service API](/reference/api/oidc) or get SAML request details with the [SAML service API](/reference/api/saml).
User authorizations can be [retrieved as roles from our APIs](/guides/integrate/retrieve-user-roles).
ZITADEL allows authenticating users by creating a session with the [Session API](/reference/api/session/zitadel.session.v2.SessionService.CreateSession), get OIDC authentication request details with the [OIDC service API](/reference/api/oidc/zitadel.oidc.v2.OIDCService.GetAuthRequest) or get SAML request details with the [SAML service API](/reference/api/saml/zitadel.saml.v2.SAMLService.GetSAMLRequest).
User role assignments can be [retrieved as roles from our APIs](/guides/integrate/retrieve-user-roles).
Refer to our guide to learn how to [build your own login UI](/guides/integrate/login-ui)
@@ -316,7 +317,7 @@ For easy copying to your reverse proxy configuration, here is the list of URL pa
We published an official Postman collection to help you explore and test the ZITADEL APIs.
The collection is organized by services, and includes a script to automatically authenticate requests. Before using it, make sure to configure the required environment variables in Postman:
The collection is organized by services and includes a script to automatically authenticate requests. Before using it, make sure to configure the required environment variables in Postman:
| Variable Name | Description |
|-------------------------|-------------|
+13 -13
View File
@@ -18,17 +18,17 @@ ZITADEL supports the usage of scopes as way of requesting information from the i
## Reserved Scopes
In addition to the standard compliant scopes we utilize the following scopes.
In addition to the standard compliant scopes, we use the following scopes.
| Scopes | Example | Description |
|:--------------------------------------------------|:-------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `urn:zitadel:iam:org:project:role:{rolekey}` | `urn:zitadel:iam:org:project:role:user` | By using this scope a client can request the claim `urn:zitadel:iam:org:project:roles` to be asserted when possible. As an alternative approach you can enable all roles to be asserted from the [project](/guides/manage/console/roles#authorizations) a client belongs to. |
| `urn:zitadel:iam:org:projects:roles` | `urn:zitadel:iam:org:projects:roles` | By using this scope a client can request the claim `urn:zitadel:iam:org:project:{projectid}:roles` to be asserted for each requested project. All projects of the token audience, requested by the `urn:zitadel:iam:org:project:id:{projectid}:aud` scopes will be used. |
| `urn:zitadel:iam:org:id:{id}` | `urn:zitadel:iam:org:id:178204173316174381` | When requesting this scope **ZITADEL** will enforce that the user is a member of the selected organization. If the organization does not exist a failure is displayed. It will assert the `urn:zitadel:iam:user:resourceowner` claims. |
| `urn:zitadel:iam:org:domain:primary:{domainname}` | `urn:zitadel:iam:org:domain:primary:acme.ch` | When requesting this scope **ZITADEL** will enforce that the user is a member of the selected organization and the username is suffixed by the provided domain. If the organization does not exist a failure is displayed |
| `urn:zitadel:iam:org:roles:id:{orgID}` | `urn:zitadel:iam:org:roles:id:178204173316174381` | This scope can be used one or more times to limit the granted organization IDs in the returned roles. Unknown organization IDs are ignored. When this scope is not used, all granted organizations are returned inside the roles. |
| `urn:zitadel:iam:org:project:id:{projectid}:aud` | `urn:zitadel:iam:org:project:id:69234237810729019:aud` | By adding this scope, the requested project id will be added to the audience of the access token |
| `urn:zitadel:iam:org:project:id:zitadel:aud` | `urn:zitadel:iam:org:project:id:zitadel:aud` | By adding this scope, the ZITADEL project id will be added to the audience of the access token |
| `urn:zitadel:iam:user:metadata` | `urn:zitadel:iam:user:metadata` | By adding this scope, the metadata of the user will be included in the token. The values are base64 encoded. |
| `urn:zitadel:iam:user:resourceowner` | `urn:zitadel:iam:user:resourceowner` | By adding this scope: id, name and primary_domain of the user's organization will be included in the token. |
| `urn:zitadel:iam:org:idp:id:{idp_id}` | `urn:zitadel:iam:org:idp:id:76625965177954913` | By adding this scope the user will directly be redirected to the identity provider to authenticate. Make sure you also send the primary domain scope if a custom login policy is configured. Otherwise the system will not be able to identify the identity provider. |
| Scopes | Example | Description |
|:--------------------------------------------------|:-------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `urn:zitadel:iam:org:project:role:{rolekey}` | `urn:zitadel:iam:org:project:role:user` | By using this scope a client can request the claim `urn:zitadel:iam:org:project:roles` to be asserted when possible. As an alternative approach you can enable all roles to be asserted from the [project](/guides/manage/console/roles#role-assignments) a client belongs to. |
| `urn:zitadel:iam:org:projects:roles` | `urn:zitadel:iam:org:projects:roles` | By using this scope a client can request the claim `urn:zitadel:iam:org:project:{projectid}:roles` to be asserted for each requested project. All projects of the token audience, requested by the `urn:zitadel:iam:org:project:id:{projectid}:aud` scopes will be used. |
| `urn:zitadel:iam:org:id:{id}` | `urn:zitadel:iam:org:id:178204173316174381` | When requesting this scope **ZITADEL** will enforce that the user is a member of the selected organization. If the organization does not exist a failure is displayed. It will assert the `urn:zitadel:iam:user:resourceowner` claims. |
| `urn:zitadel:iam:org:domain:primary:{domainname}` | `urn:zitadel:iam:org:domain:primary:acme.ch` | When requesting this scope **ZITADEL** will enforce that the user is a member of the selected organization and the username is suffixed by the provided domain. If the organization does not exist a failure is displayed |
| `urn:zitadel:iam:org:roles:id:{orgID}` | `urn:zitadel:iam:org:roles:id:178204173316174381` | This scope can be used one or more times to limit the granted organization IDs in the returned roles. Unknown organization IDs are ignored. When this scope is not used, all granted organizations are returned inside the roles. |
| `urn:zitadel:iam:org:project:id:{projectid}:aud` | `urn:zitadel:iam:org:project:id:69234237810729019:aud` | By adding this scope, the requested project id will be added to the audience of the access token |
| `urn:zitadel:iam:org:project:id:zitadel:aud` | `urn:zitadel:iam:org:project:id:zitadel:aud` | By adding this scope, the ZITADEL project id will be added to the audience of the access token |
| `urn:zitadel:iam:user:metadata` | `urn:zitadel:iam:user:metadata` | By adding this scope, the metadata of the user will be included in the token. The values are base64 encoded. |
| `urn:zitadel:iam:user:resourceowner` | `urn:zitadel:iam:user:resourceowner` | By adding this scope: id, name and primary_domain of the user's organization will be included in the token. |
| `urn:zitadel:iam:org:idp:id:{idp_id}` | `urn:zitadel:iam:org:idp:id:76625965177954913` | By adding this scope the user will directly be redirected to the identity provider to authenticate. Make sure you also send the primary domain scope if a custom login policy is configured. Otherwise the system will not be able to identify the identity provider. |
@@ -1,10 +1,10 @@
---
title: External user grant
title: External User Role Assignments
---
ZITADEL's external user grant is a feature that allows you to grant access to projects within your organization to users from other organizations.
ZITADEL's external user role assignment is a feature that allows you to grant access to projects within your organization to users from other organizations.
This is useful in scenarios where you want to collaborate with external users without needing them to be part of your organization.
By using external user grants, you can streamline collaboration with external users while maintaining control over access to your projects within ZITADEL.
By using external user role assignments, you can streamline collaboration with external users while maintaining control over access to your projects within ZITADEL.
![](../../../public/img/concepts/features/external-user-grant.png)
@@ -14,27 +14,27 @@ By using external user grants, you can streamline collaboration with external us
You might typically store all users in a single ZITADEL [organization](../structure/organizations) for managing customer accounts.
We recommend creating a second organization for your own team that also contains all the projects and applications that will be [granted](../structure/granted_projects) to the first organization with the B2C customer accounts.
Instead of duplicating user accounts for your team members in the B2C organization, you can create external user grants on the B2C organization.
Instead of duplicating user accounts for your team members in the B2C organization, you can create external user role assignments on the B2C organization.
### Multitenancy / Business-to-Business (B2B)
ZITADEL allows you to create separate [organizations](../structure/organizations) for each of your business partner or tenant.
There might be cases were users from one organization need access to projects from another organization.
You can create an external user grant, that allows the inviting organization to manage the roles for the external user.
ZITADEL allows you to create separate [organizations](../structure/organizations) for each of your business partners or tenants.
There might be cases where users from one organization need access to projects from another organization.
You can create a role assignment for an external user that allows the inviting organization to manage the roles for the external user.
## Project Grants vs. User Grants
## Project Grants vs. Role Assignments
Project Grants are used to delegate access management of an entire project (or specific roles of the project) to another organization.
User grants provide a more granular approach, allowing specific users from external organizations to access your projects.
Role assignments provide a more granular approach, allowing specific users from external organizations to access your projects.
## Alternative to multiple user accounts
A user account is always unique across a ZITADEL instance.
In some use cases, external user grants are a simple way to allow users access to multiple tenants.
In some use cases, external user role assignments are a simple way to allow users access to multiple tenants.
## References
* [API reference for user grants](/reference/api/management)
* [How to manage user grants through ZITADEL's management console](/guides/manage/console/roles#authorizations)
* [API reference to create authorization (role assignment)](/reference/api/authorization/zitadel.authorization.v2.AuthorizationService.CreateAuthorization)
* [How to manage role assignments through ZITADEL's console](/guides/manage/console/roles#role-assignments)
* [More about multi-tenancy with ZITADEL](https://zitadel.com/blog/multi-tenancy-with-organizations)
@@ -2,9 +2,9 @@ The idea of projects is to have a vessel for all components who are closely rela
![Project Grant](../../../public/img/concepts/objects/project_grants.png)
All applications within a project share the same roles, grants, and authorizations:
All applications within a project share the same roles, grants, and role assignments:
- **Applications** is your software that initiates the authorization flow. This could be a web app and a mobile app that share the same roles.
- **Roles** are a means of managing user access rights for a project.
- **Authorizations** define which users have which roles. Authorizations are also called “user grants”.
- **Granted Organizations** can manage selected roles for your project on their own.
- **Applications** initiate the authorization flow. They could be a web application and a mobile application that share the same roles.
- **Roles** define the access rights of a project and can be assigned to users.
- **Role Assignments** define the association between users and their roles within a project.
- **Granted Organizations** are organizations that have been granted access to a project in a different organization, allowing them to manage user role assignments for that project.
@@ -7,7 +7,7 @@ sidebar_label: Granted Projects
![Project Grant](../../../public/img/concepts/objects/project_grants.png)
With ZITADEL you can grant selected roles within your project to an organization. The receiving organization can then create authorizations for their users on their own (self-service).
With ZITADEL you can grant selected roles within your project to an organization. The receiving organization can then create role assignments for their users on their own (self-service).
An example could be a service provider that offers a SaaS solution that has different permissions for employees working in Sales and Accounting. As soon as a new client purchases the service, the provider could grant the roles ‘sales’ and ‘accounting’ to that organization, allowing them to self-manage how they want to allocate the roles to their users.
+21 -21
View File
@@ -1,11 +1,11 @@
---
title: ZITADEL with Next.js - A B2B Scenario
sidebar_label: Next.js - B2B
title: ZITADEL with Next.js – A B2B Scenario
sidebar_label: Next.js – B2B
---
This is our ZITADEL [Next.js](https://nextjs.org/) B2B template. It shows how to authenticate as a user with multiple organizations. The application shows your users roles on the selected organizations, other projects your organization is allowed to use and other users having a grant to use the application.
This is our ZITADEL [Next.js](https://nextjs.org/) B2B template. It shows how to authenticate as a user with multiple organizations. The application shows your users' roles in the selected organizations, other projects your organization is allowed to use, and other users who have roles to use the application.
If you need more info on B2B use cases consider reading our guide for the [B2B solution scenario](/guides/solution-scenarios/b2b).
If you need more info on B2B use cases, consider reading our guide for the [B2B solution scenario](/guides/solution-scenarios/b2b).
> You can follow along with the template code in our [zitadel-nextjs-b2b](https://github.com/zitadel/zitadel-nextjs-b2b) repo.
@@ -16,9 +16,9 @@ If you need more info on B2B use cases consider reading our guide for the [B2B s
Users with `view` role can view granted projects on their organization which were granted by your organization (owning this portal application).
Users with `admin` role can view granted projects and list users of the selected organization who are granted to use the portal application too.
## Setup Vendor application and users in ZITADEL
## Set up Vendor application and users in ZITADEL
First we need to create an organization that holds the Vendor's users, projects and applications.
First, we need to create an organization that holds the Vendor's users, projects, and applications.
### Vendor Organization
@@ -49,20 +49,20 @@ Copy the "Resource ID" of the application `portal-web` as you will need this in
### Roles
To set up the needed roles for your project, navigate to your `Portal` project, and add the following roles
To set up the necessary roles for your project, navigate to your `Portal` project, and add the following roles
| Key | Display Name | Group | Description |
|:-------|:--------------|:------|------------------------------------------------------------------------|
| admin | Administrator | | The administrator, allowed to read granted projects and to user grants |
| reader | Reader | | A user who is allowed to read his organizations granted projects only |
| Key | Display Name | Group | Description |
|:-------|:--------------|:------|----------------------------------------------------------------------------------|
| admin | Administrator | | The administrator, allowed to read granted projects and to assign roles to users |
| reader | Reader | | A user who is allowed to read his organization's granted projects only |
Now in the `General` section of the Portal project, make sure to enable `Assert Roles on Authentication`.
This makes sure that roles, which is used by the application to enable UI components, are set in your OIDC ID Token.
This makes sure that roles, which are used by the application to enable UI components, are set in your OIDC ID Token.
### Service Account
To make the application work you need a service account which loads granted-projects and user-grants for you.
In the B2B-Demo organization, navigate to `Users` in navigation of Management Console, click on `Service Accounts` and create a new user.
To make the application work, you need a service account which loads granted-projects and user-grants for you.
In the B2B-Demo organization, navigate to `Users` in navigation of Management Console, click on `Service Accounts`, and create a new user.
Let's set its username to `nextjs` and its name to `NextJS`. Then press `create`.
On the detail page of that user, navigate to "Personal Access Tokens" and add a new entry, set an optional expiration date.
@@ -94,7 +94,7 @@ Replace the values as follows
`NEXTAUTH_URL`: Base url of this demo app (B2B portal); runs per default on [http://localhost:3000](http://localhost:3000)
`NEXT_PUBLIC_ZITADEL_ISSUER`: The url to your zitadel instance. When using zitadel.cloud for this demo you can find the domain of your ZITADEL instance in the customer portal. You can also find this information by going to your application `portal-web` and click 'URLs' in the navigation. The variable is prefixed with `NEXT_PUBLIC_` such that it can be accessed from the application.
`NEXT_PUBLIC_ZITADEL_ISSUER`: The url to your zitadel instance. When using zitadel.cloud for this demo, you can find the domain of your ZITADEL instance in the customer portal. You can also find this information by going to your application `portal-web` and click 'URLs' in the navigation. The variable is prefixed with `NEXT_PUBLIC_` such that it can be accessed from the application.
`ZITADEL_API`: URL of the Management API. Typically, the same as `ZITADEL_ISSUER`.
@@ -104,11 +104,11 @@ Replace the values as follows
`ZITADEL_CLIENT_ID`: Having the project `Portal` selected, click on the Application `portal-web`. `${CLIENT_ID}` is displayed as a field in the OIDC configuration, labeled "Client ID" and has the format `12345678@portal`.
`SERVICE_ACCOUNT_ACCESS_TOKEN`: Set up a service account, add a Personal Access Token and copy the secret here (see below).
`SERVICE_ACCOUNT_ACCESS_TOKEN`: Set up a service account, add a Personal Access Token, and copy the secret here (see below).
## Install and Run
To run this sample locally you need to install dependencies first.
To run this sample locally, you need to install dependencies first.
Type and execute:
@@ -130,7 +130,7 @@ and open [http://localhost:3000](http://localhost:3000) with your browser to see
### Customer organization
Create a new organization in Console. Easiest way is to use the organization dropdown on the top left.
Create a new organization in Console. The easiest way is to use the organization dropdown on the top left.
Let's call this new organization `Demo-Customer`.
### Users
@@ -154,11 +154,11 @@ Login with your user on the customer organization to validate the setup.
Switch to the `Demo-Vendor` organization, select Projects in the navigation, and click on `Portal` and then `Project Grants`.
[Grant all roles of the Project](/guides/manage/console/projects-overview#granted-projects-b2b) to the organization `demo-customer.$CUSTOM_DOMAIN.zitadel.cloud`.
### Authorization
### Role Assignment
As you have guessed, these two users need to be authorized.
As you have guessed, these two users need to be assigned roles.
On the `Demo-Customer` organization, navigate to Projects and select "Granted Projects" in the sub-navigation.
Select the project portal `Portal` and navigate to "Authorizations".
Select the project portal `Portal` and navigate to "Role Assignments".
Give `Alice Admin` the roles `reader` and `admin`.
`Eric Employee` will get only the role `reader`.
+1 -1
View File
@@ -48,7 +48,7 @@ Also note the projects resource ID, as you will need it to configure your React
![](../../../public/img/react/project-authz.png)
If you want to read your users roles from user info endpoint, make sure to enable the checkbox in your project.
If you want to read your users roles from the user info endpoint, make sure to enable the checkbox in your project.
## React setup
+3 -3
View File
@@ -38,9 +38,9 @@ A `user` role is not required. This role is assumed by default for any authentic
![Project roles in management console](../../../public/img/symfony/project-roles.png)
Finally, we can assign the roles to users in the project's authorizations tab.
Finally, we can assign the roles to users in the project's "Role Assignments" section.
![Project authorizations in management console](../../../public/img/symfony/project-authorizations.png)
![Project role assignments in management console](../../../public/img/symfony/project-authorizations.png)
### Set up application and obtain secrets
@@ -279,7 +279,7 @@ You can customize the User Info that is obtained and stored by adjusting the `SC
### Controllers and templates
We need to create couple of Controllers and templates to define the app.
We need to create a couple of Controllers and templates to define the app.
#### Index
+2 -2
View File
@@ -38,8 +38,8 @@ Continue and create the application.
### Refresh Token and Client ID
After successful creation of the app, make sure you tick the checkbox to enable refresh tokens.
Also copy the client ID, as you will need it to configure your Vue application.
After the successful creation of the app, make sure you tick the checkbox to enable refresh tokens.
Also, copy the client ID, as you will need it to configure your Vue application.
![](../../../public/img/vue/tick-refresh-token.png)
@@ -188,7 +188,7 @@ CLIENT_SECRET = "NVAp70IqiGmJldbS...."
1. Create a service account and a Personal Access Token (PAT) for that user by following [this guide](/guides/integrate/service-accounts/personal-access-token#create-a-service-account-with-a-pat).
2. To enable authorization, follow [this guide](/guides/manage/console/roles) to create a role `read:messages` on your project.
3. Next, create an authorization for the service account you created by adding the role `read:messages` to the user. Follow this [guide](/guides/manage/console/roles#authorizations) for more information on creating an authorization.
3. Next, add the role `read:messages` to the service account you created. Follow this [guide](/guides/manage/console/roles#role-assignments) for more information on creating a role assignment.
### Run the API
@@ -5,8 +5,8 @@ sidebar_label: Retrieve User Roles
This guide explains all the possible ways of retrieving user roles across different organizations and projects using ZITADEL's APIs.
## What are roles/authorizations/grants in ZITADEL?
User roles, user grants, or authorizations refer to the roles that are assigned to a user. These terms are used interchangeably to mean the roles assigned to the user, e.g., the ZITADEL Management Console refers to the pairing of roles and users as authorizations, whereas the APIs refer to them as grants. This guide will use the term roles for application-specific roles (e.g., `admin`, `accountant`, `employee`, `hr`, etc.) and ZITADEL-specific administrator roles (e.g., `IAM_OWNER`, `ORG_OWNER`, `PROJECT_OWNER`, etc.).
## What are roles and role assignments in ZITADEL?
User role assignments or authorizations refer to the roles that are assigned to a user. These terms are used interchangeably to mean the roles assigned to the user, e.g., the ZITADEL Console refers to the pairing of roles and users as role assignments, whereas the APIs refer to them as authorizations or user grants. This guide will use the term roles for application-specific roles (e.g., `admin`, `accountant`, `employee`, `hr`, etc.) and ZITADEL-specific manager roles (e.g., `IAM_OWNER`, `ORG_OWNER`, `PROJECT_OWNER`, etc.).
Roles are critical to managing permissions in a single-tenant or multi-tenant application. It can, however, be tricky to retrieve them, especially when spanning multiple organizations and projects.
@@ -18,8 +18,8 @@ Follow the links below to assign roles to your users.
- [Add application roles via the ZITADEL Management Console](/guides/manage/console/roles)
- [Add administrator roles via the ZITADEL Management Console](/guides/manage/console/administrators)
- [Add application roles via the ZITADEL Management API](/reference/api/project)
- [Add administrator roles to users via the ZITADEL Management API](/reference/api/management)
- [Add application roles via the Project Service API](/reference/api/project/zitadel.project.v2.ProjectService.AddProjectRole)
- [Add administrator roles to users via the Internal Permission Service API](/reference/api/internal_permission/zitadel.internal_permission.v2.InternalPermissionService.CreateAdministrator)
## Retrieve roles
@@ -34,7 +34,7 @@ How to generate a token:
- [Generate tokens for users](/guides/integrate/login/oidc/login-users)
- [Generate tokens for service accounts](/guides/integrate/service-accounts/authenticate-service-accounts)
In order to access role information via the token, you must include the right audience and the necessary role claims in the scope and/or select the required role settings in the ZITADEL management console before requesting the token.
To access role information via the token, you must include the right audience and the necessary role claims in the scope and/or select the required role settings in the ZITADEL management console before requesting the token.
### Determine the audience
@@ -212,11 +212,10 @@ https://github.com/zitadel/actions/blob/main/examples/custom_roles.js
### Retrieve roles using the auth API
Now we will use the auth API to retrieve roles from a logged in user using the user’s token
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://`${CUSTOM_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 service account’s token to retrieve the authorizations using the [APIs listed under user authorizations/grants in the auth API](/reference/api/authorization).
Let’s start with a user who has multiple roles in different organizations in a multi-tenanted setup. You can use the logged-in user’s token or the service account’s token to retrieve the roles assigned to this user using the [APIs listed under user authorizations/grants in the auth API](/reference/api/authorization/zitadel.authorization.v2.AuthorizationService.ListAuthorizations).
**Scope used:** `openid urn:zitadel:iam:org:project:id:zitadel:aud`
#### **1. [List my project roles](/reference/api/auth/zitadel.auth.v1.AuthService.ListMyProjectPermissions)**
@@ -290,9 +289,9 @@ curl -L -X POST 'https://${CUSTOM_DOMAIN}/auth/v1/permissions/zitadel/me/_search
}
```
#### **[3. List my authorizations/grants​](/reference/api/auth/zitadel.auth.v1.AuthService.ListMyUserGrants)**
#### **[3. List my role assignments](/reference/api/auth/zitadel.auth.v1.AuthService.ListMyUserGrants)**
Returns a list of user grants the authenticated user has. User grants consist of an organization, a project and roles.
Returns a list of roles the authenticated user has been assigned. Role assignments (referred to as user grants in the APIs) consist of an organization, a project, and roles.
**URL: https://`${CUSTOM-DOMAIN}`/auth/v1/usergrants/me/_search**
@@ -15,7 +15,7 @@ import AppType from "./_application-types.mdx";
Applications are the entry point to your [Project Overview](/guides/manage/console/projects-overview)
. Users either login into one of your applications (Frontend) and interact with them directly, or use one of your APIs (Backend).
All applications within a project share the same **Roles** and **Authorizations**. This means you define a role once (e.g., `admin`) on the Project level, and it applies across all your web, mobile, and API applications.
All applications within a project share the same **Roles** and **Role Assignments**. This means you define a role once (e.g., `admin`) on the Project level, and it applies across all your web, mobile, and API applications.
To access your applications, navigate to your Project in the Management Console and select your application.
@@ -117,13 +117,13 @@ When disabled, ZITADEL enforces strict security and only allows `https`.
**Glob Patterns:**
Development mode allows the use of glob patterns in Redirect URIs for flexibility:
| Special Terms | Meaning |
| :--- | :--- |
| `*` | Matches any sequence of **non-path-separators**. |
| `/**/` | Matches zero or more directories. |
| `?` | Matches any single non-path-separator character. |
| `[class]` | Matches any single character against a class of characters (e.g., `[a-z]`). |
| `{alt1,...}` | Matches a sequence if one of the comma-separated alternatives matches. |
| Special Terms | Meaning |
|:--------------|:----------------------------------------------------------------------------|
| `*` | Matches any sequence of **non-path-separators**. |
| `/**/` | Matches zero or more directories. |
| `?` | Matches any single non-path-separator character. |
| `[class]` | Matches any single character against a class of characters (e.g., `[a-z]`). |
| `{alt1,...}` | Matches a sequence if one of the comma-separated alternatives matches. |
<Callout type="note">
Double stars (`**`) should appear surrounded by path separators (e.g., `/**/`). A pattern like `path/to/**.txt` is invalid; use `path/to/**/*.txt`.
@@ -40,7 +40,7 @@ The Management Console enables administrators to perform the following critical
2. **Resource Management:** Create, update, and delete essential resources such as [Organizations](./organizations-overview), [Projects](./projects-overview), and [Applications](./applications-overview).
3. **User Management:** Manage the lifecycle of [User accounts](./users-overview). This includes creating new users, updating profiles, resetting passwords, and deactivating accounts.
4. **Access Control:** Define and manage permissions. Administrators can assign [Roles](/guides/manage/console/roles) to users and configure fine-grained access controls for specific resources.
5. **Manager Assignment:** Delegate administrative tasks by assigning **Administrator** roles (e.g., Org Owner, Project Owner) to specific users, ensuring proper oversight and segregation of duties.
5. **Administrator Assignment:** Delegate administrative tasks by assigning **Administrator** roles (e.g., Org Owner, Project Owner) to specific users, ensuring proper oversight and segregation of duties.
6. **Customization and Branding:** Customize the look and feel of ZITADEL. You can upload custom logos, select color schemes, and apply [branding](/guides/manage/customize/branding) to match your corporate identity.
7. **Audit Logging:** Access [Audit Logs](/concepts/features/audit-trail) to track user activity and configuration changes. This is essential for monitoring security events and maintaining regulatory compliance.
@@ -16,7 +16,7 @@ A Project is the vessel that holds your Applications and Roles. It defines the s
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.
* **Authorization:** All applications in this project share these roles, allowing you to create unified authorizations for your users across all platforms.
* **Role assignment:** All applications in this project share these roles, allowing you to create unified role assignments for your users across all platforms.
![POS Project](../../../../public/img/guides/console/posproject.png)
@@ -28,7 +28,7 @@ At the moment, we support OIDC and almost every OAuth2 client. We'll be expandin
Go to [Applications](./applications-overview) for more details.
### Roles
A role consists of different attributes, but only the **Key** is relevant to the authorization and must be unique within the project.
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).
@@ -65,7 +65,7 @@ To create a project:
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 authorizations of *their own users* for your project. They can assign the roles you defined to their employees without your intervention.
* **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.
@@ -79,7 +79,7 @@ Using the POS example above: You could grant the `POS` project to a partner orga
### How to Grant a Project
1. Navigate to the Project you want to share (e.g., `POS`).
2. In the **Grants** section, click **New**.
2. In the **Project Grants** section, click **New**.
<img src="/docs/img/guides/console/grantsmenu.png" alt="Grants" width="170px" />
@@ -101,11 +101,11 @@ If you have different designs for your organizations (Private Labeling), you can
width="400px"
/>
| Setting | Description |
| :--- | :--- |
| **Unspecified** | If nothing is specified, the system default settings will trigger. |
| 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. |
| **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 [primary domain scope](/apis/openidoauth/scopes#reserved-scopes) (e.g., `urn:zitadel:iam:org:domain:primary:{domainname}`).
@@ -119,7 +119,7 @@ You can configure strict security checks regarding roles during authentication.
/>
* **Assert Roles on Authentication:** Role information is sent from the Userinfo endpoint (and in tokens, depending on app settings).
* **Check authorization on Authentication:** Users are **only** allowed to login if they have at least one role assigned for this project. If they have no roles, access is denied immediately.
* **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
@@ -1,11 +1,11 @@
---
title: ZITADEL Roles and Authorizations
sidebar_label: Roles and Authorizations
title: ZITADEL Roles and Role Assignments
sidebar_label: Roles and Role Assignments
---
If you would build out the [POS use case example](./projects-overview#example-scenario) you would probably need an application for administration.
If you built out the [POS use case example](./projects-overview#example-scenario), you would probably need an application for administration.
In this application you would probably have somebody accessing as an accountant and somebody as an administrator, who is somebody with enhanced rights.
To build this out, you would have to add this distinction as roles.
To achieve this, you would have to add this distinction as roles.
To add roles, jump to the section **Roles** and create those new roles with the following values
- Key: admin
@@ -20,35 +20,35 @@ and
<img src="/docs/img/guides/console/addrole.png" alt="Add roles" />
The **Key** is used for coding (can then for example be requested in the ID Token).
The **Key** is used for coding (can then, for example, be requested in the ID Token).
The **Display Name** is just for you remembering its use case
The **Display Name** is just for you to remember its use case
The **Group** is for making multiple roles selectable more easy.
The **Group** is to make it easier to assign multiple roles at once.
<img src="/docs/img/guides/console/roles.png" width="750px" alt="Roles" />
> The role client is for another application of the project `POS`, as all possible roles from your POS applications are defined in your project.
## Authorizations
## Role Assignments
Now to make use of this roles, add an authorization.
An authorization combines a user of your organization with one or multiple roles.
Now, to make use of these roles, add a role assignment.
A role assignment combines a user of your organization with one or multiple roles.
> You can also add users of other organizations. Click on the hint below the username field to create an [external user grant](/concepts/features/external-user-grant).
> You can also add users of other organizations. Click on the hint below the username field to create an [external user role assignment](/concepts/features/external-user-grant).
<img src="/docs/img/guides/console/authusers.png" width="500px" alt="Auth users" />
If your wanted to test your application with your own user, navigate to the **Authorizations** section under your project and click on **new**.
If you want to test your application with your own user, navigate to the **Role Assignments** section under your project and click on **new**.
Type your username, hit continue, select the roles you want your user to have and save. If you want to add all roles of the Administration group, you can click on the group to select all.
Type your username, hit "Continue," select the roles you want your user to have, and save. If you want to add all roles of the Administration group, you can click on the group to select all.
<img
src="/docs/img/guides/console/authorization.png"
width="750px"
alt="Authorization"
alt="RoleAssignments"
/>
Now you can retrieve those roles in your application. ZITADEL has [multiple settings](./projects-overview#project-settings) for you to access them more easily. Navigate to the **General** section of your project and check your needed ones.
Now you can retrieve those roles in your application. ZITADEL has [multiple settings](./projects-overview#project-settings) for you to access them more easily. Navigate to the **General** section of your project for more settings.
> Note: We did set up our authorizations from projects, but this can be achieved from multiple locations in console. You can view and add authorizations from your organization, your projects, or from your users page.
> Note: We set up the role assignments from projects, but this can be achieved from multiple locations in the console. You can view and assign roles from the organization, the projects, or from the users page.
@@ -93,11 +93,11 @@ Metadata can be requested via the Auth and Management APIs, the Userinfo endpoin
alt="ID Token settings"
/>
### Authorizations
User authorizations (roles) are displayed on user profile pages.
### Role Assignments
The roles assigned to a user are displayed on user profile pages.
To access these roles in your application:
* **Userinfo Endpoint:** Check the **Assert roles on authentication** box in your [Project Settings](./roles#authorizations).
* **Userinfo Endpoint:** Check the **Assert roles on authentication** box in your [Project Settings](./roles#role-assignments).
* **ID Token:** Toggle **User roles inside ID Token** in your [Application Settings](./applications-overview).
## References
@@ -11,72 +11,74 @@ B2B describes the situation where an organization interacts with other organizat
This **multi-tenancy architecture** usually adds some form of complexity to an Identity and Access Management System.
In ZITADEL an [organization](/guides/manage/console/organizations-overview) can represent a business partner or partner who typically has its own branding and has different access settings like an additional federated login for its users.
B2B can be a simple scenario where an organization only shares one of its projects with another organization or have a more complex case where an organization is offering a portal application to all its partners with included (self)administration.
B2B can be a simple scenario where an organization only shares one of its projects with another organization or has a more complex case where an organization is offering a portal application to all its partners with included (self)administration.
## Sample scenario
Octagon is a fictitious company which is used throughout this guide to explain the details and key concepts of such a B2B scenario.
Octagon is a fictitious company used throughout this guide to explain the details and key concepts of such a B2B scenario.
Octagon tries to solve multiple tasks in the banking field. Its portfolio includes several applications for their employees, customers, and partners. Some of which are web-based, some of which are used by service accounts only.
### Portal Application
Octagon has a **Portal application** where its employees can access their account and list all applications they are allowed to use.
Employees work for a department within Octagon or for Octagon itself.
Some of the users have enhanced features because they supervise certain teams. Those can onboard new employees and manage their roles and features.
Some users have enhanced features because they supervise certain teams. Those can onboard new employees and manage their roles and features.
Target groups of the application can be split into:
- **Employees:** users who are using the application as a starting point for their work.
- **Supervisors:** users who are mainly using the application to manage users and their access of their department.
- **Administrators:** this users are able to grant additional organizations or departments and elect supervisors.
- **Administrators:** users who can grant additional organizations or departments and elect supervisors.
### Planning considerations
In order to define the need of the **Portal Application** some planning considerations about organizations have to be made:
To define the need of the **Portal Application**, some planning considerations about organizations have to be made:
- **Login and Access:** Does a user have a preset organization to login? Does the application show the default login page or does each organization use its own branding?
- **Organizations:** Does a user have access in multiple organizations? Is a user required to use a different federated login for those organizations?
- **Login and Access:** Does a user have a preset organization to login? Does the application show the default login page, or does each organization use its own branding?
- **Organizations:** Does a user have access to multiple organizations? Is a user required to use a different federated login for those organizations?
- **Roles** Does the application need users to have specific roles assigned within their organizations? Which roles are needed to enable certain features of the application?
### Login
You can decide whether a organization is preselected for the login or if the user is redirected to the default login screen. Using OpenID Connect, you can send the user to a specific organization by defining the organization in a [reserved scope](/apis/openidoauth/scopes#reserved-scopes) (primary domain).
You can decide whether an organization is preselected for the login or if the user is redirected to the default login screen. Using OpenID Connect, you can send the user to a specific organization by defining the organization in a [reserved scope](/apis/openidoauth/scopes#reserved-scopes) (primary domain).
Settings to the branding or the login options of the organization can be made from the organization section in [Console](/guides/manage/console/console-overview).
The behavior of the login branding can be set in your projects detail page. You can choose the branding of the selected organization, the user's organization, or the project's organization.
The behavior of the login branding can be set in your project detail page. You can choose the branding of the selected organization, the user's organization, or the project's organization.
### Organizations
Generally a user belongs to and is managed by one organization, however the user can receive authorizations from multiple other organizations (delegated authorizations). Anyways, a user should be able to use the same identity to switch between organizations.
Generally a user belongs to and is managed by one organization, however, a user can be authorized to access projects in other organizations via role assignments. A user should be able to use the same identity to switch between organizations.
If this feature is not desired, a separate user for each organization should be created.
Adding a user from a different organization to the audience of a project can be as easy as adding a new user authorization (user grant). A user grant combines a user from any organization with a project and 0-N roles.
Adding a user from a different organization to the audience of a project can be as easy as assigning a new role to a user. A role assignment combines a user from any organization with a project and 0-N roles.
In our sample scenario, we assume to have the following users:
Our sample scenario includes the following users:
- **Dimitri:** a team leader who is employed by Pentagon, an Octagon department. Dimitri uses his Microsoft Account in combination with his one time password to access the portal. Pentagon therefore has set up Microsoft as Identity Provider. Pentagon also requires its users to secure their accounts with additional factors.
- **Michael:** a trainee of Pentagon only using the portal to access his workspace apps. Michael uses his Google Account in combination with his laptops fingerprint.
- **Bill:** is employed at Octagon as Administrator of the Portal Application. Bill also uses a Microsoft Account in combination with a Security Key to secure his account.
- **Dimitri:** a team leader who is employed by the Pentagon, an Octagon department. Dimitri uses his Microsoft Account in combination with a One Time Password to access the portal. Pentagon therefore has set up Microsoft as their Identity Provider. Pentagon also requires its users to secure their accounts with additional factors.
- **Michael:** a trainee of the Pentagon who uses the portal to access his workspace apps. Michael uses his Google Account in combination with biometrics (e.g., his fingerprint on his Laptop).
- **Bill:** is employed at Octagon as an Administrator of the Portal Application. Bill also uses a Microsoft Account in combination with a Security Key to secure his account.
After having determined the constellation of the organizations and its users, all the necessary data (Portal project with roles and app, users, login requirements, identity providers, branding) should be set up in [Console](https://${CUSTOM_DOMAIN}.zitadel.cloud/ui/console/org).
A B2B [sample application](https://github.com/zitadel/zitadel-nextjs-b2b). for NextJS can be found [here](../../examples/login/nextjs-b2b).
A B2B [sample application](https://github.com/zitadel/zitadel-nextjs-b2b) for NextJS can be found [here](../../examples/login/nextjs-b2b).
To allow another organization to use a project, a project grant has to be created. Upon creation, roles for a grant can be limited to a subset of the total project roles.
In our scenario, Octagon creates a project grant for Pentagon. Pentagon is limited to use `writer` and `reader` role. The `admin` role is reserved for the Octagon organization itself.
In our scenario, the Octagon creates a project grant for the Pentagon. Pentagon is limited to use `writer` and `reader` role. The `admin` role is reserved for the Octagon organization itself.
<B2B></B2B>
### Roles
In this scenario, Dimitri and Michael share the same organization Pentagon, where as Bill belongs to Octagon. Octagon is owner of the Portal project with its Web App, having Bill configured as user grant with `admin` role. Dimitri owns the `writer` role, whereas Michael only is `reader`.
This scenario involves two organizations: Octagon and Pentagon.
Bill, a user from the Octagon organization, is assigned the admin role for the Portal project.
Dimitri and Michael are both part of the Pentagon organization and have been assigned the `writer` and `reader` roles, respectively.
> Note: Roles are meant for internal business logic and therefore need to be validated separately, none of the users described are allowed to create user grants, at least if they do not own a ZITADEL administrator role.
> Note: Roles are intended for your application's internal business logic and require separate validation.
The users in this example cannot manage role assignments for other users unless they have an appropriate ZITADEL administrator role.
If you made a dashboard where some users are able to create user grants, the Management API to do such operations should be triggered with the personal access token of the users, not with a token of a service account, to create a meaningful audit log.
If you had such a use case, ZITADEL administrator roles must be assigned to those users.
If you build a dashboard for users to assign roles, you must use the Management API with the user's personal access token and not with a machine user's token. This ensures that all actions are properly recorded in the audit log. To enable this, the users performing these actions must be granted a ZITADEL manager role.
### Noteworthy
Due to the fact that ZITADEL includes unlimited users, projects, and applications and comes with all security features in the FREE tier, ZITADEL can be considered a great alternative to other SaaS IAM systems such as Auth0 or Okta.
As ZITADEL includes unlimited users, projects, and applications and comes with all security features in the FREE tier, ZITADEL can be considered a great alternative to other SaaS IAM systems such as Auth0 or Okta.
In such a case with this high potential of scalability where user counts can grow explosively, ZITADEL does not become the bottleneck and therefore is the valid choice. You can learn more on ZITADELs benefits and the pricing [here](https://zitadel.com/pricing).
### Learn more
@@ -17,35 +17,35 @@ This means that the users and also their authorizations will be managed within Z
## Organization
An organization is the ZITADEL resource which contains users, projects, applications, policies and so on.
In an organization projects and users are managed by the organization.
You need at least one organization for your own company in our case "The Timing Company".
An organization is the ZITADEL resource that contains users, projects, applications, policies and so on.
The organization manages the projects and users.
You need at least one organization for your own company, in our case "The Timing Company."
Your next step is to create an organization for each of your customers.
## Project
The idea of projects is to have a vessel for all components who are closely related to each other.
In this use case we would have two different projects, for each environment one. So lets call it "Time Dev" and "Time Prod".
These projects should be created in "The Timing Company" organization, because it is the owner of the project.
In this use case, we would have two different projects, one each for the Development and Production environments.
Let us call them "Time Dev" and "Time Prod". These projects should be created in "The Timing Company" organization.
In the project you will configure all your roles and applications (clients and APIs).
### Project Settings
You can configure `check roles on authentication` on the project, if you want to restrict access to users that have the correct authorization for the project.
Enable the `check roles on authentication` setting on the project, if you want to restrict access to users that do not have the correct access for the project.
### Project Grant
To give a customer permissions to a project, a project grant to the customers organization is needed (search the granted organization by its domain).
To grant a customer permission to a project, a project grant to the customer's organization is needed (search the granted organization by its domain).
It is also possible to delegate only specific roles of the project to a certain customer.
As soon as a project grant exists, the customer will see the project in the granted projects section of their organization and will be able to authorize their own users to the given project.
As soon as a project grant exists, the customer will see the project in the granted projects section of their organization and will be able to assign roles to their own users to the given project.
## Authorizations
## Role Assignments
To give a user permission to a project an authorization is needed.
All organizations which own the project or received a grant are able to authorize users.
It is also possible to authorize users outside the own company if the exact login name of the user is known.
To give a user permission to a project, a role assignment is needed.
All organizations that own projects or received a grant can assign roles to users to have access to projects.
It is also possible to assign roles to users outside the own company if the exact login name of the user is known.
## Project Login
@@ -53,7 +53,7 @@ There are some different use cases how the login should behave and look like:
1. Restrict Organization
With the primary domain scope the organization will be restricted to the requested domain, this means only users of the requested organization will be able to login.
With the primary domain scope the organization will be restricted to the requested domain; this means only users of the requested organization will be able to log in.
The private labeling (branding) and the login policy of the requested organization will be set automatically.
<Callout>
@@ -65,7 +65,7 @@ More about the [Scopes](/apis/openidoauth/scopes)
You can configure on project-level which branding should be shown to users.
In the default the design of the instance will be shown, but as soon as the user is identified, the policy of the users organization (if specified) will be triggered.
If the setting is set to `Ensure Project Resource Owner Setting`, the private labeling of the project organization will always be triggered.
The last possibility is to show the private labeling of the project organization and as soon as the user is identified the user organization settings will be triggered.
The last possibility is to show the private labeling of the project organization, and as soon as the user is identified, the user organization settings will be triggered.
For this the Allow User Resource Owner Setting should be set.
<Callout>
More about [Private Labeling](/guides/manage/customize/branding)
@@ -53,7 +53,7 @@ Follow these steps to deploy your first instance:
### 4. Create your Project and Application
In ZITADEL, [**Applications**](/guides/manage/console/applications-overview) are grouped into [**Projects**](/guides/manage/console/projects-overview).
This allows multiple applications (like a React frontend and a Go backend) to share the same roles and authorizations.
This allows multiple applications (like a React frontend and a Go backend) to share the same roles and role assignments.
#### Launch the Management Console