mirror of
https://github.com/andwati/zitadel.git
synced 2026-10-30 19:12:16 +00:00
docs: introduce versioned docs and migrate to fuma (#11166)
## Todos for release - [x] Configure Env in docs project on vercel - [x] Configure Root Path in the docs project on vercel - [ ] Remove old CSP https://github.com/zitadel/website/pull/1592 ## What we did This pull request migrates the project documentation from the old `docs/` directory to the new `apps/docs/` directory, introduces a new documentation system built with Next.js and Fumadocs, and updates all relevant references, configuration files, and documentation to reflect this change. It also adds new configuration and ignore files for the new documentation app, updates CI and linting to exclude the new docs from certain checks, and revises the contributing guidelines accordingly. **Documentation System Migration and New Docs App** * Migrated all documentation from `docs/` to `apps/docs/`, and updated all references in `README.md`, `CONTRIBUTING.md`, and other files to point to the new location. [[1]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L585-L640) [[2]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L660-R607) [[3]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L740-R687) [[4]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L2-R3) [[5]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L30-R30) * Added a new Next.js/Fumadocs-based documentation app under `apps/docs/`, including core app files, layouts, routing, search API, and a comprehensive `README.md` with development and contribution instructions. [[1]](diffhunk://#diff-5a1b07344a2c1b4d3f37b23ff1388b62cd9f57dea3c1cd23d8a0412b7602b132R1-R74) [[2]](diffhunk://#diff-462b9ad1eabbb7d1c29bb9c36e4931eb180fd7190900e6d2babf8f4d66ad1c28R1-R39) [[3]](diffhunk://#diff-e16ae25660ded787b10ac35dea96d5ecaacf895dae0afc8a9bd4382dc79a8c87R1-R7) [apps/docs/app/[[...slug]]/layout.tsxR1-R81](diffhunk://#diff-59e08acde4e805b7aeccef1dcf98f1d71dfc550777e6b9402085cee0e9fa4e0aR1-R81), [apps/docs/app/[[...slug]]/page.tsxR1-R79](diffhunk://#diff-e5df3f80d0fa01e12d63d81f29c57a9d14e846c78fd3beabb2ef768e38fd9580R1-R79), [[4]](diffhunk://#diff-389b34918e040cacaa87cd7201ffa462cc2b0b716736f537e3d3c660ac69353bR1-R7) [[5]](diffhunk://#diff-d3b03416d1c457b19f1c27b26f2db741412df841b875c26ccadc36e4522247f4R1-R29) [[6]](diffhunk://#diff-c8fb8339570a5305809be7c618e14705fd86390dc278e6ce8ba224a7bc8b0c3cR1-R25) **Configuration and Tooling Updates** * Updated `.github/workflows/codeql.yml`, `.golangci.yaml`, and `.github/dependabot.yml` to properly handle the new docs app: excluded `apps/docs` from certain checks, added npm dependency updates for the docs app, and excluded generated content. [[1]](diffhunk://#diff-12783128521e452af0cfac94b99b8d250413c516ec71fe6d97dbea666ff7ba27L8-R14) [[2]](diffhunk://#diff-9917ddc9f1c3304218f7269265b746d997c5c0615478177b5fceecd33ef47cb5R5-R6) [[3]](diffhunk://#diff-9917ddc9f1c3304218f7269265b746d997c5c0615478177b5fceecd33ef47cb5R126-R129) [[4]](diffhunk://#diff-dd4fbda47e51f1e35defb9275a9cd9c212ecde0b870cba89ddaaae65c5f3cd28R89-R106) * Updated `.devcontainer/devcontainer.json` to use the latest Go 1.25.3 version for consistency. **Licensing and Miscellaneous** * Added `apps/docs/` to the list of licensed directories in `LICENSING.md`. These changes ensure the documentation is now maintained in a modern, scalable system and all project tooling is updated to support the new structure. --------- Co-authored-by: Federico Coppede <[email protected]>
This commit is contained in:
Florian Forster
co-authored by
Federico Coppede
Federico Coppede
parent
7b6395c348
commit
d8ea041c56
@@ -0,0 +1,37 @@
|
||||
---
|
||||
title: Account linking
|
||||
---
|
||||
|
||||
ZITADEL supports linking user accounts from different external identity providers, such as social logins or enterprise IdPs, to a single ZITADEL user profile. This enables users to be recognized as the same user in your applications, regardless of which external account they use to log in.
|
||||
|
||||
Each user in ZITADEL has one account for streamlined access management and a unified audit trail. Multiple external identities can be linked to this account.
|
||||
|
||||
### Advantages
|
||||
|
||||
- Users can log in with several identity providers without maintaining separate profiles
|
||||
- Already registered users can link additional external profiles
|
||||
- Provides backup authentication methods if an IdP is unavailable
|
||||
- Enables unified auditing across all linked identities
|
||||
|
||||
### How it works
|
||||
|
||||
Account linking is controlled by your organization and identity provider configuration.
|
||||
|
||||
When external identity providers (such as social logins or enterprise SSO) are configured, a user account is created in ZITADEL, and the [external identity](../structure/users#federated-users) is linked to the ZITADEL account.
|
||||
|
||||
> **Important:** If a user account in ZITADEL is already linked to an external identity and the user enters their username during login, ZITADEL will automatically redirect to the linked external identity provider for authentication.
|
||||
> There is **no choice** presented to the user between authenticating with local username/password and an external IDP once accounts are linked.
|
||||
> Only if the external login fails (for example, due to an expired or invalid IDP secret), will ZITADEL fall back to local authentication.
|
||||
|
||||
Users are only shown options to pick local login or possible external IDPs **during registration**—that is, only when there is no existing account. For existing accounts that are linked to an external IDP, the system determines the authentication method automatically.
|
||||
|
||||
If only one external identity provider is configured and username/password login is disabled, all authentication requests are immediately redirected to the external provider.
|
||||
|
||||
In cases where a local account exists and a user registers or logs in through an external identity provider, ZITADEL can be instructed to link the new external identity to the local account based on matching criteria (such as email address or username).
|
||||
|
||||
### Automatic account linking
|
||||
|
||||
You can configure your identity provider to allow automatic account linking for users with the same email or username.
|
||||
To enable this, set "Account linking allowed" in the [identity provider template settings](/guides/integrate/identity-providers/introduction#key-settings-on-the-templates).
|
||||
|
||||
Automatic account linking helps users associate multiple login options with their ZITADEL account, offering flexibility—however, at login, the authentication method will be determined by the link, **not by user choice**.
|
||||
@@ -0,0 +1,39 @@
|
||||
---
|
||||
title: ZITADEL Actions
|
||||
sidebar_label: Actions
|
||||
---
|
||||
|
||||
By using ZITADEL actions, you can manipulate ZITADELs behavior on specific Events.
|
||||
This is useful when you have special business requirements that ZITADEL doesn't support out-of-the-box.
|
||||
|
||||
<Callout>
|
||||
We're working on Actions continuously. In the [roadmap](https://zitadel.com/roadmap), you see how we are planning to expand and improve it. Please tell us about your needs and help us prioritize further fixes and features.
|
||||
</Callout>
|
||||
|
||||
## Why actions?
|
||||
ZITADEL can't anticipate and solve every possible business rule and integration requirements from all ZITADEL users. Here are some examples:
|
||||
- A business requires domain specific data validation before a user can be created or authenticated.
|
||||
- A business needs to automate tasks. Roles should be assigned to users based on their ADFS 2016+ groups.
|
||||
- A business needs to store metadata on a user that is used for integrating applications.
|
||||
- A business needs to restrict the users who are allowed to register to a certain organization by their email domains.
|
||||
|
||||
With actions, ZITADEL provides a way to solve such problems.
|
||||
|
||||
## How it works
|
||||
Using the actions feature, *ORG_OWNERs* create a flow for each supported flow type.
|
||||
Each flow type provides its own events.
|
||||
You can hook into these events by assigning them an action.
|
||||
An action is composed of
|
||||
* a name,
|
||||
* a custom JavaScript code snippet,
|
||||
* an execution timeout in seconds,
|
||||
* a switch that defines if its corresponding flow should fail if the action fails.
|
||||
|
||||
Within the JavaScript code, you can read and manipulate the state.
|
||||
|
||||
## Further reading
|
||||
|
||||
- [Assign users a role after they register using an external identity provider](/guides/manage/customize/behavior)
|
||||
- [Actions reference](/guides/manage/console/actions-overview)
|
||||
- [Actions Marketplace: Find example actions to use in ZITADEL](https://github.com/zitadel/actions)
|
||||
- [Example use cases](/apis/actions/code-examples)
|
||||
@@ -0,0 +1,64 @@
|
||||
---
|
||||
title: ZITADEL Actions v2
|
||||
sidebar_label: Actions v2
|
||||
---
|
||||
|
||||
By using ZITADEL Actions v2, you can modify ZITADEL's behavior on specific API calls, events, or functions. This is useful when you have special business requirements that ZITADEL does not support out-of-the-box.
|
||||
|
||||
<Callout>
|
||||
We're working on Actions continuously. In the [roadmap](https://zitadel.com/roadmap), you can see how we plan to expand and improve this feature. Please tell us about your needs to help us prioritize further improvements and features.
|
||||
</Callout>
|
||||
|
||||
<Callout>
|
||||
To use Actions v2, activate the "Actions" [feature flag](/reference/api/feature/zitadel.feature.v2.FeatureService.SetInstanceFeatures) in order to manage the related resources.
|
||||
|
||||
Actions v2 will always be executed if available, even if the feature flag is switched off. To remove any Actions v2, the related Execution must be removed.
|
||||
</Callout>
|
||||
|
||||
## Why Actions?
|
||||
ZITADEL can't anticipate or solve every possible business rule and integration requirement for all users. Here are some examples:
|
||||
- A business requires domain-specific data validation before a user can be created or authenticated.
|
||||
- A business needs to automate tasks, such as assigning roles to users based on their ADFS 2016+ groups.
|
||||
- A business needs to store metadata on a user, which is used for integrating applications.
|
||||
- A business needs to restrict which users are allowed to register to a certain organization by their email domains.
|
||||
|
||||
With Actions, ZITADEL provides a way to address such scenarios.
|
||||
|
||||
## How it works
|
||||
There are three necessary components:
|
||||
- **Endpoint:** An external endpoint with the desired logic. It can be anything, as long as it can receive an HTTP POST request.
|
||||
- **Target:** A resource in ZITADEL containing all the necessary information about how to trigger an endpoint.
|
||||
- **Execution:** A resource in ZITADEL specifying when to trigger which targets.
|
||||
|
||||
The process is that, at certain points, ZITADEL executes a defined Execution, which then calls the defined Target(s). This allows everyone to implement custom behavior for as many processes as needed.
|
||||
|
||||
Possible conditions for the Execution:
|
||||
- **Request:** Reacts to or manipulates requests to ZITADEL, for example, by adding information to newly created users.
|
||||
- **Response:** Reacts to or manipulates responses from ZITADEL, for example, provisioning newly created users to other systems.
|
||||
- **Function:** Reacts to various functions in ZITADEL, replacing [Actions](/concepts/features/actions).
|
||||
- **Event:** Reacts to different events created in ZITADEL, for example, to inform someone if a user gets locked.
|
||||
|
||||
<Callout>
|
||||
Currently, defined Actions v2 will be executed in addition to [Actions](/concepts/features/actions).
|
||||
</Callout>
|
||||
|
||||
## Migration
|
||||
|
||||
- [Migrate Actions v1 to Actions v2](/guides/integrate/actions/migrate-from-v1)
|
||||
|
||||
## Further reading
|
||||
|
||||
- [Actions v2 reference](/guides/integrate/actions/usage)
|
||||
- [Actions v2 example execution for request](/guides/integrate/actions/testing-request)
|
||||
- [Actions v2 example execution for request manipulation](/guides/integrate/actions/testing-request-manipulation)
|
||||
- [Actions v2 example execution for request signature check](/guides/integrate/actions/testing-request-signature)
|
||||
- [Actions v2 example execution for response](/guides/integrate/actions/testing-response)
|
||||
- [Actions v2 example execution for response manipulation](/guides/integrate/actions/testing-response-manipulation)
|
||||
- [Actions v2 example execution for function](/guides/integrate/actions/testing-function)
|
||||
- [Actions v2 example execution for function manipulation](/guides/integrate/actions/testing-function-manipulation)
|
||||
- [Actions v2 example execution for event](/guides/integrate/actions/testing-event)
|
||||
|
||||
## Example use cases:
|
||||
The following repository contains various examples demonstrating how to use Actions v2 in different scenarios. It also includes a deployment script for testing the examples with Cloudflare Workers:
|
||||
|
||||
- [Actions v2 examples](https://github.com/zitadel/actions/tree/main/actions-v2-cloudflare-workers)
|
||||
@@ -0,0 +1,56 @@
|
||||
---
|
||||
title: ZITADEL's In-built Audit Trail
|
||||
sidebar_label: Audit Trail
|
||||
---
|
||||
|
||||
ZITADEL provides you with an built-in audit trail to track all changes and events over an unlimited period of time.
|
||||
Most other solutions replace a historic record and track changes in a separate log when information is updated.
|
||||
ZITADEL only ever appends data in an [Eventstore](/concepts/eventstore/overview), keeping all historic record.
|
||||
The audit trail itself is identical to the state, since ZITADEL calculates the state from all the past changes.
|
||||
|
||||
|
||||
|
||||
This form of audit log has several benefits over storing classic audit logs.
|
||||
You can view past data in-context of the whole system at a single point in time.
|
||||
Reviewing a past state of the application can be important when tracing an incident that happened months back. Moreover the eventstore provides a truly complete and clean audit log.
|
||||
|
||||
<Callout title="Future Plans">
|
||||
There will be three major areas for future development on the audit data
|
||||
|
||||
- [Metrics](https://github.com/zitadel/zitadel/issues/4458) and [standard reports](https://github.com/zitadel/zitadel/discussions/2162#discussioncomment-1153259)
|
||||
- [Feedback loop](https://github.com/zitadel/zitadel/issues/5102) and threat detection
|
||||
- Forensics and replay of events
|
||||
|
||||
</Callout>
|
||||
|
||||
## Accessing the Audit Log
|
||||
|
||||
### Last changes of an object
|
||||
|
||||
You can check the last changes of most objects in the [Console](/guides/manage/console/console-overview).
|
||||
In the following screenshot you can see an example of last changes on an [user](/guides/manage/console/users-overview).
|
||||
The same view is available on several other objects such as organization or project.
|
||||
|
||||
|
||||
|
||||
### Event View
|
||||
|
||||
Administrators can see all events across an instance and filter them directly in [Console](/guides/manage/console/overview).
|
||||
Go to your default settings and then click on the Tab **Events** to open the Event Viewer or browse to $CUSTOM_DOMAIN/ui/console/events
|
||||
|
||||
|
||||
|
||||
### Event API
|
||||
|
||||
Since everything that is available in Management Console can also be called with our APIs, you can access all events and audit data trough our APIs:
|
||||
|
||||
- [Event API Guide](/guides/integrate/zitadel-apis/event-api)
|
||||
- [API Documentation](/reference/api/admin)
|
||||
|
||||
Access to the API is possible with a [Service User](/guides/integrate/service-users/authenticate-service-users) account, allowing you to integrate the events with your own business logic.
|
||||
|
||||
## Using logs in external systems
|
||||
|
||||
You can use the events from the audit log in external systems such as a SOC/SIEM solution.
|
||||
|
||||
Follow our guide on how to [integrate ZITADEL with external systems for streaming events and audit logs](/guides/integrate/external-audit-log).
|
||||
@@ -0,0 +1,33 @@
|
||||
---
|
||||
title: "ZITADEL Management Console: Resource management and customization"
|
||||
sidebar_label: Management Console
|
||||
---
|
||||
|
||||
The ZITADEL management console is a web-based interface designed to facilitate the management and administration of ZITADEL resources and configurations.
|
||||
It serves as a central hub where administrators can perform various tasks related to identity and access management within their organization's infrastructure.
|
||||
|
||||
The management console is available by navigating to the [custom domain](/concepts/features/custom-domain) of your instance and appending the path `/ui/console`.
|
||||
Administrators can [restrict end-users from accessing the management console](/guides/solution-scenarios/restrict-console).
|
||||
|
||||
Here's an overview of what the management console enables users to do:
|
||||
|
||||
1. **Default Settings:** [Managers](/concepts/structure/managers) can access and manage the default settings of the ZITADEL system. This includes configuring authentication methods, security policies, and other system-wide parameters to meet the organization's requirements.
|
||||
|
||||
2. **Resource Management:** The management console allows for the creation, updating, and deletion of essential resources such as organizations, users, projects, and applications. Administrators can efficiently manage these entities to ensure proper access control and governance.
|
||||
|
||||
3. **User Management:** Administrators can manage user accounts, including creating new user accounts, updating user profiles, resetting passwords, and deactivating or deleting user accounts as needed.
|
||||
|
||||
4. **Access Control:** The management console provides tools for defining and managing access control policies. This includes assigning roles and permissions to users, configuring fine-grained access controls, and managing access to specific resources.
|
||||
|
||||
5. **Audit Logging:** The management console offers access to [audit logs](/concepts/features/audit-trail) that track user activity and changes made to resources and system settings. Administrators can review these logs to monitor security-related events, track changes, and maintain compliance with regulatory requirements.
|
||||
|
||||
6. **Customization and Branding:** The management console allows organizations to customize the branding and appearance of their ZITADEL instance. This includes uploading custom logos, selecting color schemes, and applying other visual customizations to align the interface with the organization's branding guidelines.
|
||||
|
||||
7. **Manager Assignment:** Administrators can assign ZITADEL [managers](/concepts/structure/managers) who have elevated privileges for managing resources within the organization. This allows for the delegation of administrative tasks while maintaining proper oversight and control.
|
||||
|
||||
Overall, the ZITADEL management console serves as a comprehensive tool for administrators to configure, manage, and monitor identity and access management within their organization, providing the necessary controls to ensure security, compliance, and efficient administration of resources.
|
||||
|
||||
Notes:
|
||||
|
||||
- Detailed guide on [using the management console](/guides/manage/console/console-overview)
|
||||
- [Restrict access](/guides/solution-scenarios/restrict-console) to the management console
|
||||
@@ -0,0 +1,13 @@
|
||||
---
|
||||
title: Custom Domain
|
||||
sidebar_label: Custom Domain
|
||||
---
|
||||
|
||||
A ZITADEL Custom Domain refers to the ability for organizations to personalize the authentication experience by using their own domain name rather than the default ZITADEL domain.
|
||||
|
||||
This feature allows organizations to maintain their brand identity throughout the authentication process, providing a seamless and consistent user experience.
|
||||
By configuring a Custom Domain within ZITADEL, organizations can replace the default authentication URLs with their own domain, such as "login.example.com" or "auth.companyname.com".
|
||||
|
||||
This not only enhances the overall user experience but also reinforces the organization's brand presence. Additionally, Custom Domains can contribute to trust and credibility, as users are more likely to recognize and trust URLs associated with the organization rather than generic domains. Overall, ZITADEL's Custom Domain feature empowers organizations to tailor the authentication process to align with their brand identity and user expectations.
|
||||
|
||||
Learn how to [configure a Custom Domain in ZITADEL Cloud](/guides/manage/cloud/instances#add-custom-domain) or how to configure [Custom Domain when self-hosting](/self-hosting/manage/custom-domain).
|
||||
@@ -0,0 +1,40 @@
|
||||
---
|
||||
title: External user grant
|
||||
---
|
||||
|
||||
ZITADEL's external user grant 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.
|
||||
|
||||
|
||||
|
||||
## Where to store users
|
||||
|
||||
### Consumer Identity Management (CIAM) / Business-to-Consumer (B2C)
|
||||
|
||||
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.
|
||||
|
||||
### 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.
|
||||
|
||||
## Project Grants vs. User Grants
|
||||
|
||||
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.
|
||||
|
||||
## 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.
|
||||
|
||||
## References
|
||||
|
||||
* [API reference for user grants](/reference/api/management)
|
||||
* [How to manage user grants through ZITADEL's management console](/guides/manage/console/roles#authorizations)
|
||||
* [More about multi-tenancy with ZITADEL](https://zitadel.com/blog/multi-tenancy-with-organizations)
|
||||
@@ -0,0 +1,78 @@
|
||||
---
|
||||
title: Identity Brokering
|
||||
sidebar_label: Identity Brokering
|
||||
---
|
||||
|
||||
Link social logins and external identity providers with your identity management platform allowing users to login with their preferred identity provider.
|
||||
|
||||
Establish a trusted connection between your central identity provider (IdP) and third party identity providers.
|
||||
|
||||
By using a central identity brokering service you don't need to develop and establish a trust relationship between each application and each identity provider individually.
|
||||
|
||||
## What are federated identities?
|
||||
|
||||
Federated identity management is an arrangement built upon the trust between two or more domains. Users of these domains are allowed to access applications and services using the same identity.
|
||||
This identity is known as federated identity and the pattern behind this is identity federation.
|
||||
|
||||
Compatibility across various IdPs is ensured by using industry standard protocols, such as:
|
||||
|
||||
* OpenID Connect (OIDC): A modern and versatile protocol for secure authentication.
|
||||
* SAML2: A widely adopted protocol for secure single sign-on (SSO) in enterprise environments.
|
||||
* LDAP: A lightweight protocol for accessing user data directories commonly used in corporate networks.
|
||||
|
||||
## What is identity brokering?
|
||||
|
||||
A service provider that specializes in brokering access control between multiple service providers (also referred to as relying parties) is called an identity broker.
|
||||
Federated identity management is an arrangement that is made between two or more such identity brokers across organizations.
|
||||
|
||||
For example, if Google is configured as an identity provider in your organization, the user will get the option to use his Google Account on the Login Screen of ZITADEL.
|
||||
Because Google is registered as a trusted identity provider, the user will be able to login in with the Google account after the user is linked with an existing ZITADEL account (if the user is already registered) or a new one with the claims provided by Google.
|
||||
|
||||
|
||||
|
||||
The schema is a very simplified version, but shows the essential steps for identity brokering
|
||||
|
||||
1. An unauthenticated user wants to use the alpha.com's application.
|
||||
2. The application redirects the user to alpha.com's identity provider (IdP).
|
||||
3. Based on the user's tenants configuration the IdP presents the configured identity providers, or redirects the user directly to the primary external IdP. The user authenticates with their external identity provider (eg, Entra ID).
|
||||
4. After the authentication, the user is redirected back to alpha.com's identity provider. If the user doesn't exist in the IdP the user will be created just-in-time and linked to the external identity provider for future reference.
|
||||
5. As with a local authentication, the IdP issues a token to the user that can be used to access the application. The IdP redirects the user, which is now authenticated, eventually to the application.
|
||||
|
||||
## Is single-sign-on (SSO) the same as identity brokering?
|
||||
|
||||
Sometimes single-sign-on (SSO) and login with third party identity providers is used interchangeably.
|
||||
Typically SSO describes an authentication scheme that allows users to log in once at a central identity provider and access service providers (client applications) without to login again.
|
||||
|
||||
Identity brokering describes an authentication scheme where users can login with external identity providers that have a established trust with an identity provider which facilitates the authentication for the requested applications.
|
||||
|
||||
The connection between the two lies in how SSO can be implemented as part of an identity brokering solution.
|
||||
In such cases, the identity broker uses SSO to enable seamless access across multiple systems, handling the complexities of different authentication protocols and standards behind the scenes.
|
||||
This allows users to log in once and gain access to multiple systems that the broker facilitates.
|
||||
|
||||
## Multitenancy and identity brokering
|
||||
|
||||
In a multi-tenancy application, you want to be able to configure an external identity provider per tenant.
|
||||
For example some organizations might use their EntraID, some other want to login with their OKTA, or Google Workspace.
|
||||
|
||||
Using an identity provider with strong multitenancy capabilities such as ZITADEL, you can configure a different set of external identity providers per organization.
|
||||
|
||||
[Domain discovery](/guides/solution-scenarios/domain-discovery) ensures that users are redirected to their external identity provider based on their email-address or username.
|
||||
[Managers](../structure/managers) can configure organization domains that are used for domain-based redirection to an external IdP.
|
||||
|
||||
|
||||
|
||||
## Simplify identity brokering with ZITADEL templates
|
||||
|
||||
ZITADEL works with SAML, OpenID Connect, and LDAP external identity providers.
|
||||
|
||||
For popular IdPs such as EntraID, Okta, Google, Facebook, and GitHub, ZITADEL [offers pre-configured templates](/guides/integrate/identity-providers/introduction).
|
||||
These templates expedite the configuration process, allowing organizations to quickly integrate these providers with minimal effort.
|
||||
|
||||
ZITADEL recognizes that specific needs may extend beyond pre-built templates.
|
||||
To address this, ZITADEL provides generic templates that enable connection to virtually any IdP. This ensures maximum flexibility and future-proofs login infrastructure, accommodating future integrations with ease.
|
||||
|
||||
### References
|
||||
|
||||
* [Detailed integration guide for many identity providers](/guides/integrate/identity-providers/introduction)
|
||||
* [Setup identity providers with Management Console](/guides/manage/console/default-settings#identity-providers)
|
||||
* [Configure identity providers with the ZITADEL API](/reference/api/management)
|
||||
@@ -0,0 +1,14 @@
|
||||
---
|
||||
title: Features
|
||||
---
|
||||
|
||||
<Cards >
|
||||
<Card href="/concepts/features/identity-brokering" title="Identity Brokering" />
|
||||
<Card href="/concepts/features/account-linking" title="Account Linking" />
|
||||
<Card href="/concepts/features/selfservice" title="Self Service" />
|
||||
<Card href="/concepts/features/custom-domain" title="Custom Domain" />
|
||||
<Card href="/concepts/features/audit-trail" title="Audit Trail" />
|
||||
<Card href="/concepts/features/passkeys" title="Passkeys" />
|
||||
<Card href="/concepts/features/actions" title="Actions" />
|
||||
<Card href="/concepts/features/console" title="Console" />
|
||||
</Cards>
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: "Passkeys in ZITADEL: Passwordless phishing-resistant authentication"
|
||||
sidebar_label: Passkeys
|
||||
---
|
||||
|
||||
ZITADEL's passkeys feature enables passwordless authentication, offering a **smoother and more secure** login experience for your users. This document explains the essential details for developers.
|
||||
|
||||
### What are Passkeys?
|
||||
|
||||
Imagine signing in without passwords! Passkeys, replacing traditional passwords, leverage **public-key cryptography** similar to FIDO2 and WebAuthn. Users rely on their devices' **biometrics or PINs** for authentication, eliminating password burdens.
|
||||
|
||||
### Benefits for Developers
|
||||
|
||||
* **Enhanced Security:** Phishing-resistant passkeys minimize credential theft risks.
|
||||
* **Streamlined User Experience:** Faster, easier logins free users from managing passwords.
|
||||
* **Platform Agnostic:** Works across devices and platforms supporting passkeys.
|
||||
* **Modern Standard:** Complies with the FIDO2 and WebAuthn standards.
|
||||
|
||||
### Features
|
||||
|
||||
* **Seamless Registration:** Create unique passkeys for users on various devices. Optionally pair them with specific users and choose cross-platform or platform-specific options.
|
||||
* **User Control:** Users manage their passkeys directly through ZITADEL's self-service portal, allowing registration, viewing, and deletion.
|
||||
* **Intuitive Login:** Users initiate passkey login by selecting the passkey option and verifying themselves with the device's biometrics (fingerprint, face ID, etc.).
|
||||
* **Intuitive Login:** Users initiate passkey login by selecting the passkey option and verifying themselves with the device's biometrics (fingerprint, face ID, etc.).
|
||||
* **Robust Fallback:** Traditional password login remains available for users without passkeys.
|
||||
|
||||
### Developer Resources
|
||||
|
||||
* **Documentation:** Passkeys Guide: [https://zitadel.com/docs/guides/integrate/login-ui/passkey](/guides/integrate/login-ui/passkey)
|
||||
* [Create Passkey Registration Link API](/guides/manage/user/reg-create-user)
|
||||
|
||||
### Notes
|
||||
|
||||
* Passkey support is still evolving in browsers and platforms. Check compatibility for your target audience.
|
||||
* ZITADEL actively develops its passkey features. Stay updated with documentation and releases.
|
||||
* Passkeys are bound to your domain, thus we recommend configuring a [Custom Domain](/concepts/features/custom-domain) before setting up passkeys.
|
||||
|
||||
Don't hesitate to ask if you have further questions about integrating passkeys in your ZITADEL application!
|
||||
@@ -0,0 +1,156 @@
|
||||
---
|
||||
title: Self Service in ZITADEL
|
||||
sidebar_label: Self Service
|
||||
---
|
||||
|
||||
ZITADEL allows users to perform many tasks themselves.
|
||||
For these tasks we either provide a user interface, or the tasks can be initiated or completed through ZITADEL's APIs.
|
||||
|
||||
It is important to understand that, depending on your use case, there will exist different user-types that want to perform different actions:
|
||||
|
||||
- `Users` are the end-users of your application. Like with any CIAM solution, users should be able to perform tasks like register/join, update their profile, manage authenticators, etc. There are certain actions that can be executed pre-login, yet others require the user to have a valid session.
|
||||
- `Managers` are users with a [special administrator role](../../guides/manage/console/managers) within ZITADEL and can perform administrative actions such as system configuration or granting access rights to users.
|
||||
|
||||
All self-service interfaces are available in different [languages](/guides/manage/customize/texts#internationalization-i-18-n).
|
||||
|
||||
<Callout>
|
||||
ZITADEL covers the typical "CIAM" self-service capabilities as well as delegated access management for multi-tenancy scenarios. Please refer to the section [Managers](#managers).
|
||||
</Callout>
|
||||
|
||||
## Registration
|
||||
|
||||
<Callout>
|
||||
You can pre-select a given organization by passing the scope `urn:zitadel:iam:org:domain:primary:{domainname}` in the authorization request.
|
||||
This will force users to register only with the specified organization.
|
||||
Furthermore, the branding and login settings (e.g., Social Login Providers) are directly shown to the user.
|
||||
</Callout>
|
||||
|
||||
### Local account
|
||||
|
||||
Allows anonymous users and authenticated users, who are not yet in the given organization, to create an account (register) themselves.
|
||||
|
||||
- Mandatory profile fields
|
||||
- Set password
|
||||
- Accept terms of service and privacy policy
|
||||
- User receives an email with a one-time code for verification purpose
|
||||
- User has to enter the one-time code to finish registration
|
||||
- User can re-request a new one-time code
|
||||
|
||||
The user is prompted on the first login to set up MFA.
|
||||
This step can be made mandatory if MFA is enforced in the login policy.
|
||||
|
||||
### Existing Identity / SSO / Social Login
|
||||
|
||||
Anonymous users and authenticated users, who are not yet in the given organization, to register with an external identity provider.
|
||||
An external identity provider can be a Social Login Provider or a pre-configured identity provider.
|
||||
|
||||
- Information from the external identity provider is used to pre-fill the profile information
|
||||
- User can update the profile information
|
||||
- An account is created within ZITADEL and linked with the external identity provider
|
||||
|
||||
#### Account Linking
|
||||
|
||||
When you log in with an external identity provider, and the user does not exist in ZITADEL, then an autoregister flow is triggered. The user is presented with two options:
|
||||
|
||||
- Create a new account: A new account will be created as stated above
|
||||
- Autolink: The user is prompted to log in with an existing [local account](#local-account). If successful, the existing identity from the external identity provider will be linked with the local account. A user can now log in with either the local account or any of the linked external accounts.
|
||||
|
||||
## Login
|
||||
|
||||
### SSO / Social Logins
|
||||
|
||||
Given an external identity provider is configured on the instance or on the organization, then:
|
||||
|
||||
- the user will be shown a button for each identity provider as an alternative to log in with a [local account](#local-account)
|
||||
- when clicking the button, the user will be redirected to the identity provider
|
||||
- after successful login, the user will be redirected to the application
|
||||
|
||||
### Machines
|
||||
|
||||
Machine accounts can't use an interactive login but require other means of authentication, such as privately signed JWT or personal access tokens.
|
||||
Read more about [Service Users](/guides/integrate/service-users/authenticate-service-users) and recommended [OpenID Connect Flows](/guides/integrate/login/oidc/oauth-recommended-flows#different-client-profiles).
|
||||
|
||||
## Logout
|
||||
|
||||
Users can terminate the session for all their users (logout).
|
||||
A client can also implement this by calling the [specific endpoint](/apis/openidoauth/endpoints#end-session-endpoint).
|
||||
|
||||
## Profile
|
||||
|
||||
These actions are available for authenticated users only.
|
||||
ZITADEL provides a self-service UI for the user profile out-of-the box under the path _$CUSTOM_DOMAIN/ui/console/users/me_.
|
||||
You can also implement your own version in your application by using our APIs.
|
||||
|
||||
### Change password
|
||||
|
||||
Users can change their passwords.
|
||||
The current password must be entered first.
|
||||
|
||||
### MFA / FIDO Passkeys
|
||||
|
||||
Users can set up and delete a second factor and FIDO Passkeys (Passwordless).
|
||||
Available authenticators are:
|
||||
|
||||
- Time-based one-time password (TOTP) (Which are Authenticator Apps like Google/Microsoft Authenticator, Authy, etc.)
|
||||
- One-time password sent as E-Mail
|
||||
- One-time password sent as SMS
|
||||
- FIDO Universal Second Factor (U2F) (Security Keys, Device, etc.)
|
||||
- FIDO2 WebAuthN (Passkeys)
|
||||
|
||||
### Update Information
|
||||
|
||||
Users can change their profile information. This includes
|
||||
|
||||
- UserName
|
||||
- First- and Last name
|
||||
- Nickname
|
||||
- Display Name
|
||||
- Gender
|
||||
- Language
|
||||
- Email address
|
||||
- Phone number
|
||||
|
||||
### Email Verification
|
||||
|
||||
Users can change their email address.
|
||||
The user receives a one-time password and can verify control over the given email address.
|
||||
|
||||
### Phone Verification
|
||||
|
||||
Users can change their phone number.
|
||||
The user receives a one-time password and can verify control over the given phone number.
|
||||
|
||||
### Identity providers
|
||||
|
||||
Users can create a connection between a [local user account](#local-account) and an [external identity](#existing-identity--sso--social-login).
|
||||
The user can log in with any of the linked accounts.
|
||||
[Linking of external accounts](#account-linking) is done during the login process.
|
||||
|
||||
## Managers
|
||||
|
||||
It is important to note that a `Manager` is not simply an administrative user, but can be used to create much more advanced scenarios such as delegating administration of a whole organization to a user, acting then as administrator and permission manager of that user group.
|
||||
|
||||
Thus, we will explain service for two of the most common scenarios in ZITADEL:
|
||||
|
||||
- `Managers in isolation`: Granting administrative permissions within a single organization context.
|
||||
- `Managers in delegation`: Granting administrative permissions to a user from a different organization where the organizations depend on each other
|
||||
|
||||
A list of [Administrator Roles](../../guides/manage/console/managers#roles) is available with a description of permissions.
|
||||
Managers can be assigned to both human users and service users, e.g., for managing certain tasks programmatically.
|
||||
|
||||
### Managers in isolation
|
||||
|
||||
A user with Administrator roles `IAM_OWNER` or `ORG_OWNER` might want to assign other users from their organization elevated permissions to handle certain aspects of the IAM tasks.
|
||||
This could be permission to assign authorizations within this isolated organization (`ORG_USER_MANAGER`) or handling setup of projects and applications (`PROJECT_OWNER`).
|
||||
|
||||
### Managers in delegation
|
||||
|
||||
In a setup like described in the [B2B Scenario](/guides/solution-scenarios/b2b), there exists an organization of the project owner and a customer organization.
|
||||
The project is granted to the customer organization, such that the customer can access the project and assign authorization to their users.
|
||||
|
||||
Given such as set up the owner might want to give one administrative user of the customer organization the role `ORG_OWNER`.
|
||||
Equipped with this Administrator Role, the user can perform actions like configuring their own SSO/Identity Provider, set security policy for their organization, customize branding, or assign project or Administrator roles to other users.
|
||||
|
||||
An `ORG_OWNER` can also not only delegate Administrator roles to other users [as described in the earlier section](#managers-in-isolation) but also manage all aspects of their own organization as well as authorize users to use the granted project.
|
||||
With ZITADEL there is no need to replicate all settings and projects across organizations.
|
||||
Instead, you could set up the project in one organization, delegate it to different organizations, and then appoint users as Managers of that organization to allow for self-service in a multi-tenancy scenario.
|
||||
Reference in New Issue
Block a user