TheArchive/zitadel
1
0
Fork 0
mirror of https://github.com/zitadel/zitadel.git synced 2025-01-06 13:37:40 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(integrate): Update login users docs (#7414)

Browse Source 
* wip

* update intro of device auth

* add custom domain concept

* wip sidebar

* wip introduction

* add passkeys

* replace azure ad with entra id

* wip

* wip

* login methods

* expand sections automatically

* update selfservice docs

* wip - hosted done

* move onboarding

* clean up

* wip

* unbreak my hrefs

* finish login users

* update managers

* add console as feature

* update b2b with multi-tenancy

* update saml

* update console concept

* add opaque tokens as knowledge

* redirects

* intro b2b

* remove login/saml

* unbreak link

* Apply suggestions from code review

Co-authored-by: Fabi <fabienne@zitadel.com>

* passkeys: add custom domain first

* update passkeys

* Apply suggestions from code review

Co-authored-by: Florian Forster <florian@zitadel.com>

* Update docs/docs/guides/integrate/login/login-users.mdx

Co-authored-by: Florian Forster <florian@zitadel.com>

---------

Co-authored-by: Fabi <fabienne@zitadel.com>
Co-authored-by: Florian Forster <florian@zitadel.com>
This commit is contained in:
mffap 2024-02-26 09:34:09 +02:00 committed by GitHub
parent 1890e28f79
commit da8a79f280
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
43 changed files with 561 additions and 196 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/docs/apis/introduction.mdx
View File

@ -15,7 +15,7 @@ The [OpenID Connect & OAuth endpoints](/docs/apis/openidoauth/endpoints) and [SA
## Authentication & authorization
ZITADEL implements industry standards such as OpenID Connect, OAuth 2.0, or SAML for authentication.
Please refer to our guides how to [authenticate users](/docs/guides/integrate/human-users) through an interactive authentication process and how to [authenticate service users](/docs/guides/integrate/serviceusers) with a programmatic authentication.
Please refer to our guides how to [authenticate users](/docs/guides/integrate/login/login-users) through an interactive authentication process and how to [authenticate service users](/docs/guides/integrate/serviceusers) with a programmatic authentication.
### OpenID Connect & OAuth

4
docs/docs/apis/openidoauth/authrequest.mdx
View File

@ -57,7 +57,7 @@ Depending on the authentication and authorization flow of your application you m
for most application types. The playground appends automatically a code challenge
for PKCE flows.
You need to append a "Code Challenge" by providing a random <span className="text-teal-600">Code Verifier</span> that is being hashed and encoded in the request to the token endpoint, please see our [guide](/guides/integrate/login-users#token-request) for more details.
You need to append a "Code Challenge" by providing a random <span className="text-teal-600">Code Verifier</span> that is being hashed and encoded in the request to the token endpoint, please see our [guide](/guides/integrate/login/oidc/login-users#token-request) for more details.
More in the [documentation](/apis/openidoauth/authn-methods) about authentication methods.
@ -123,6 +123,6 @@ This can be achieved by adding the scope `urn:zitadel:iam:org:project:id:zitadel
## How to use ZITADEL in your project
Please refer to our [guide](/guides/integrate/login-users) on how to login users.
Please refer to our [guide](/guides/integrate/login/oidc/login-users) on how to login users.
OpenID Connect certified libraries should allow you to customize the parameters and define scopes for the authorization request. You can also continue by using one of our [example applications](/docs/sdk-examples/introduction).

33
docs/docs/concepts/features/console.md Normal file
View File

@ -0,0 +1,33 @@
---
title: "ZITADEL Console: Resource management and customization"
sidebar_label: Console
---
The ZITADEL 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 console is available by navigating to the [custom domain](/docs/concepts/features/custom-domain) of your instance and appending the path `/ui/console`.
Administrators can [restrict end-users from accessing the console](/docs/guides/solution-scenarios/restrict-console).
Here's an overview of what the console enables users to do:
1. **Default Settings:** [Managers](/docs/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 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 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 console offers access to [audit logs](/docs/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 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](/docs/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 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 console](/docs/guides/manage/console/overview)
- [Restrict access](/docs/guides/solution-scenarios/restrict-console) to the console

13
docs/docs/concepts/features/custom-domain.md Normal file
View File

@ -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](http://localhost:3000/docs/guides/manage/cloud/instances#add-custom-domain) or how to configure [custom domain when self-hosting](http://localhost:3000/docs/self-hosting/manage/custom-domain).

37
docs/docs/concepts/features/passkeys.md Normal file
View File

@ -0,0 +1,37 @@
---
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 passwordless 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](/docs/guides/integrate/login-ui/passkey)
* **Create Passkey Registration Link API:** [https://zitadel.com/docs/guides/manage/user/reg-create-user](/docs/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](/docs/concepts/features/custom-domain.md) before setting up passkeys.
Don't hesitate to ask if you have further questions about integrating passkeys in your ZITADEL application!

63
docs/docs/concepts/features/selfservice.md
View File

@ -57,43 +57,6 @@ When you login with an external identity provider, and the user does not exist i
## Login
:::info Customization and Branding
The login page can be changed by customizing different branding aspects and you can define a custom domain for the login (eg, login.acme.com).
By default, the displayed branding is defined based on the user's domain. In case you want to show the branding of a specific organization by default, you need to either pass a primary domain scope (`urn:zitadel:iam:org:domain:primary:{domainname}`) with the authorization request, or define the behavior on your Project's settings.
:::
### Web, Mobile, and Single-Page Applications
[This guide](/guides/integrate/login-users) explains in more detail the login-flows for different application types.
Human users are redirected to ZITADEL's login page and complete sign-in with the interactive login flow.
It is important to understand that ZITADEL provides a hosted login page and the device of the users opens this login page in a browser, even on Native/Mobile apps.
#### MFA / 2FA
Users are automatically prompted to provide a second factor, when
- Instance or organization [login policy](/concepts/structure/policies#login-policy) is set
- Requested by the client
- A multi-factor is setup for the user
When a multi-factor is required, but not set-up, then the user is requested to set-up an additional factor.
#### FIDO Passkeys
Users can select a button to initiate passwordless login or use a fall-back method (ie. login with username/password), if available.
The passwordless login flow follows the FIDO2 / WebAuthN standard.
Briefly explained the following happens:
- User selects button
- User's device will ask the user to provide a gesture (e.g., FaceID, Windows Hello, Fingerprint, PIN)
- The user is being redirected to the application
With the introduction of passkeys the gesture can be provided on ANY of the user's devices.
This is not strictly the device where the login flow is being executed (e.g., on a mobile device).
The user experience depends mainly on the used operating system and browser.
### SSO / Social Logins
Given an external identity provider is configured on the instance or on the organization, then:
@ -105,31 +68,7 @@ Given an external identity provider is configured on the instance or on the orga
### 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/serviceusers) and recommended [OpenID Connect Flows](/guides/integrate/oauth-recommended-flows#different-client-profiles).
### Other Clients
We currently do not expose the Login API.
Whereas you can register users via the management API, you can't login users with our APIs.
This might be important in cases where you can't use a website (eg, Games, VR, ...).
### Account picker
A list of accounts that were used to log-in are shown to the user.
The user can click the account in the list and does not need to type the username.
Users can still login with a different user that is not in the list.
:::info
This behavior can be changed with the authorization request. Please refer to our [guide](/guides/integrate/login-users).
:::
### Password reset
Unauthenticated users can request a password reset after providing the loginname during the login flow.
- User selects reset password
- An email will be sent to the verified email address
- User opens a link and has to provide a new password
Read more about [Service Users](/guides/integrate/serviceusers) and recommended [OpenID Connect Flows](/guides/integrate/login/oidc/oauth-recommended-flows#different-client-profiles).
## Logout

70
docs/docs/concepts/knowledge/opaque-tokens.md Normal file
View File

@ -0,0 +1,70 @@
---
title: "Opaque Tokens in Zitadel: Enhancing Application Security"
sidebar_label: Opaque tokens
---
In the context of application security, robust authentication mechanisms are essential for safeguarding sensitive data and ensuring user trust.
Opaque tokens, the default token type within the ZITADEL platform, play a crucial role in bolstering security measures.
This documentation elucidates the principles behind opaque tokens, their implementation within ZITADEL, and their advantages over alternative token types.
## What are Opaque Tokens?
Opaque tokens are a type of access token utilized in authentication processes, particularly within OAuth 2.0 and OpenID Connect (OIDC) frameworks. Unlike self-contained tokens like [JSON Web Tokens (JWT)](https://datatracker.ietf.org/doc/html/rfc7519), opaque tokens do not divulge user information directly.
Instead, they serve as opaque references to session data stored securely on the authorization server.
## Authentication Workflow with Opaque Tokens
1. **Token Generation**: When a user initiates an authentication process within an application integrated with ZITADEL, the authentication server generates a unique opaque token associated with the user's session.
2. **Token Presentation**: The generated opaque token is provided to the client, which subsequently presents it during requests to access protected resources within the application.
3. **Token Verification**: Upon receiving the opaque token, the application server interacts with the authorization server to validate its authenticity and retrieve detailed information about the user's session. This process ensures the integrity of the authentication flow and verifies the user's permissions to access requested resources.
## Benefits of Opaque Tokens in ZITADEL
1. **Reduced Token Exposure**: Opaque tokens mitigate the risk of token exposure since they do not contain sensitive user information directly. This reduces the likelihood of token-based attacks and enhances overall security posture.
2. **Enhanced Server-side Control**: With opaque tokens, validation occurs server-side, granting administrators greater control over authentication flows and access policies. This centralized approach facilitates comprehensive monitoring and enforcement of security measures, including server-side single-logout across all applications.
3. **Protection Against Token Tampering**: Opaque tokens prevent unauthorized manipulation of token contents, thereby ensuring the integrity and authenticity of authentication processes. This protection against token tampering further strengthens the security of applications integrated with ZITADEL.
## Opaque Tokens vs. JWT Tokens
When it comes to implementing authentication and authorization mechanisms within applications, developers often face the choice between different types of tokens, each with its own set of characteristics and advantages.
Two common types of tokens used in authentication protocols are opaque tokens and JSON Web Tokens (JWT).
### Structure
- **Opaque Tokens**: Opaque tokens are essentially references or pointers to information stored on the authorization server. They do not contain any meaningful user data within the token itself. Instead, they typically consist of a unique identifier (e.g., a session ID or database key) that allows the server to look up the associated session information.
- **JWT Tokens**: JSON Web Tokens, on the other hand, are self-contained tokens that contain user information in a JSON format. JWTs consist of three base64-encoded sections: header, payload, and signature. The payload contains claims or assertions about the user (e.g., user ID, roles, expiration time) that are digitally signed to ensure integrity.
### Token verification
- **Opaque Tokens**: Verifying opaque tokens requires interaction with the authorization server. When a client presents an opaque token to a resource server, the resource server sends the token to the authorization server for validation. The authorization server then checks the token's validity and returns the associated user information if the token is valid.
- **JWT Tokens**: JWT tokens can be verified locally by clients without needing to communicate with the authorization server. Clients can validate JWT signatures using public keys or shared secrets obtained during the token issuance process. This decentralized verification process can be faster and more scalable but requires securely distributing and managing keys.
### Token security and size
- **Opaque Tokens**: Since opaque tokens do not contain user information, they are inherently more secure in terms of protecting sensitive data. However, the reliance on server-side validation means there is an overhead associated with each token verification request, which can impact performance in high-throughput scenarios.
- **JWT Tokens**: JWT tokens contain user information within the token itself, which can be convenient for clients as it eliminates the need for frequent interactions with the authorization server. However, this also means that JWT tokens can potentially expose sensitive information if not handled and secured properly. Additionally, JWT tokens tend to be larger compared to opaque tokens due to the encoded payload.
### Use cases and trade-offs
- **Opaque Tokens**: Opaque tokens are well-suited for scenarios where security and confidentiality are top priorities, such as handling highly sensitive user data or complying with strict privacy regulations. They are particularly advantageous in distributed systems where centralized control over authentication and access policies is desired.
- **JWT Tokens**: JWT tokens are often preferred in scenarios where performance and scalability are critical, such as microservices architectures or API-based applications. The ability to verify tokens locally can reduce latency and minimize dependencies on external services. However, developers must carefully consider the implications of including sensitive information in JWT payloads and implement appropriate security measures.
## Conclusion
In conclusion, opaque tokens represent a foundational component in fortifying application security within ZITADEL.
By leveraging opaque tokens, organizations can establish robust authentication mechanisms, mitigate security risks, and maintain stringent control over access policies.
As organizations navigate the complex landscape of application security, integrating technologies such as opaque tokens becomes imperative for safeguarding sensitive data and fostering user trust.
Notes:
- Read more about the differences in our [blog on JWT vs. Opaque tokens](https://zitadel.com/blog/jwt-vs-opaque-tokens)
- Learn how to use [token introspection](/docs/guides/integrate/token-introspection) to validate access tokens
- Decode, verify and generate valid JWT tokens with [jwt.io](https://jwt.io/)

17
docs/docs/concepts/structure/_manager_description.mdx
View File

@ -1,7 +1,12 @@
ZITADEL Managers are Users who have permission to manage ZITADEL itself. This means that those users are allowed to login into your instance console and edit certain parts of the configuration.
There are some different levels for managers.
Managers are [human users or service users](/docs/concepts/structure/users) who have permission to manage resources within ZITADEL.
- **IAM Managers**: This is the highest level. Users with IAM Manager roles are able to manage the whole Instance.
- **Org Managers**: Managers in the Organization Level are able to manage everything within the granted Organization.
- **Project Mangers**: In this level the user is able to manage a project.
- **Project Grant Manager**: The project grant manager is for projects, which are granted of another organization.
Manager permissions can be assigned to different levels in ZITADEL:
- **IAM Managers**: This is the highest level. Users with IAM Manager roles are able to manage the whole [Instance](/docs/concepts/structure/instance).
- **Org Managers**: Managers in the Organization Level are able to view or manage everything, according to their permissions, within the granted [Organization](/docs/concepts/structure/organizations).
- **Project Mangers**: In this level the user is able to manage a [project](/docs/concepts/structure/projects).
- **Project Grant Manager**: The project grant manager is for [granted projects](/docs/concepts/structure/granted_projects) by another organization.
Scope of the managers is restricted based on their level.
That means a Manager, assigned to one organization, will only get access to resources and configurations of that organization.
Only Managers on the instance level can view resources, such as users, across all organizations.

5
docs/docs/concepts/structure/managers.mdx
View File

@ -7,4 +7,7 @@ import ManagerDescription from "./_manager_description.mdx";
<ManagerDescription name="ManagerDescription" />
To read more on how managers are created and which roles exist read the console guide [here](../../guides/manage/console/managers).
Notes:
- Read our [guide on Managers](../../guides/manage/console/managers) to learn more about the role concept and how to use Manager roles in ZITADEL.
- [API reference](/docs/apis/resources/mgmt/management-service-list-org-member-roles) for Managers on organization level

2
docs/docs/examples/call-zitadel-api/dot-net.md
View File

@ -17,7 +17,7 @@ All that is required, is a service account with an Org Owner (or another role, d
However, we recommend you read the guide on [how to access ZITADEL API](../../guides/integrate/access-zitadel-apis) and the associated guides for a basic knowledge of :
- [Recommended Authorization Flows](../../guides/integrate/oauth-recommended-flows.md)
- [Recommended Authorization Flows](../../guides/integrate/login/oidc/oauth-recommended-flows.md)
- [Service Users](../../guides/integrate/serviceusers)
> Be sure to have a valid key JSON and that its service account is either ORG_OWNER or at least ORG_OWNER_VIEWER before you continue with this guide.

2
docs/docs/examples/call-zitadel-api/go.md
View File

@ -16,7 +16,7 @@ The client [SDK](https://github.com/zitadel/zitadel-go) will handle all necessar
All that is required, is a service account with an Org Owner (or another role, depending on the needed api requests) role assigned and its key JSON.
However, we recommend you read the guide on [how to access ZITADEL API](../../guides/integrate/access-zitadel-apis) and the associated guides for a basic knowledge of :
- [Recommended Authorization Flows](../../guides/integrate/oauth-recommended-flows.md)
- [Recommended Authorization Flows](../../guides/integrate/login/oidc/oauth-recommended-flows.md)
- [Service Users](../../guides/integrate/serviceusers)
> Be sure to have a valid key JSON and that its service account is either ORG_OWNER or at least ORG_OWNER_VIEWER before you continue with this guide.

28
docs/docs/guides/integrate/identity-providers/azure-ad.mdx
View File

@ -1,6 +1,6 @@
---
title: Configure Azure AD as an Identity Provider in ZITADEL
sidebar_label: Azure AD
title: Configure Entra ID as an Identity Provider in ZITADEL
sidebar_label: Entra ID
---
import GeneralConfigDescription from './_general_config_description.mdx';
@ -10,11 +10,11 @@ import IDPsOverview from './_idps_overview.mdx';
import TestSetup from './_test_setup.mdx';
import Activate from './_activate.mdx';
<Intro provider="Azure AD"/>
<Intro provider="Entra ID (former Azure Active Directory)"/>
## Azure AD Configuration
## Entra ID Configuration
You need to have access to an AzureAD Tenant. If you do not yet have one follow [this guide from Microsoft](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant) to create one for free.
You need to have access to an Entra ID Tenant. If you do not yet have one follow [this guide from Microsoft](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant) to create one for free.
### Register a new client
@ -69,7 +69,7 @@ To be able to get all the information that ZITADEL needs, you have to configure
<IDPsOverview templates="Microsoft"/>
### Create a new Azure AD Provider
### Create a new Entra ID Provider
The Microsoft template has everything you need preconfigured.
You only have to add the client ID and secret, you have created in the step before.
@ -79,16 +79,16 @@ You can configure the following settings if you like, a useful default will be f
**Scopes**: The scopes define which scopes will be sent to the provider, `openid`, `profile`, and `email` are prefilled.
This information will be taken to create/update the user within ZITADEL. Make sure to also add `User.Read`. ZITADEL ensures that at least `openid` and `User.Read` scopes are always sent.
**Email Verified**: Azure AD doesn't send the email verified claim in the users token, if you don't enable this setting.
**Email Verified**: Entra ID doesn't send the email verified claim in the users token, if you don't enable this setting.
The user is then created with an unverified email, which results in an email verification message.
If you want to avoid that, make sure to enable "Email verified".
In that case, the user is created with a verified email address.
**Tenant Type**: Configure the tenant type according to what you have chosen in the settings of your Azure AD application previously.
**Tenant Type**: Configure the tenant type according to what you have chosen in the settings of your Entra ID application previously.
- Common: Choose common if you want all Microsoft accounts being able to login.
In this case, configure "Accounts in any organizational directory and personal Microsoft accounts" in your Azure AD App.
- Organizations: Choose organization if you have Azure AD Tenants and no personal accounts. (You have configured either "Accounts in this organization" or "Accounts in any organizational directory" on your Azure APP)
- Consumers: Choose this if you want to allow public accounts. (In your Azure AD App you have configured "Personal Microsoft accounts only")
In this case, configure "Accounts in any organizational directory and personal Microsoft accounts" in your Entra ID App.
- Organizations: Choose organization if you have Entra ID Tenants and no personal accounts. (You have configured either "Accounts in this organization" or "Accounts in any organizational directory" on your Azure APP)
- Consumers: Choose this if you want to allow public accounts. (In your Entra ID App you have configured "Personal Microsoft accounts only")
**Tenant ID**: If you have selected *Tenant ID* as *Tenant Type*, you have to enter the *Directory (Tenant) ID* into the *Tenant ID* field, copied previously from the Azure App configuration.
@ -100,12 +100,12 @@ In this case, configure "Accounts in any organizational directory and personal M
<Activate/>
![Activate Azure AD](/img/guides/zitadel_activate_azure.png)
![Activate Entra ID](/img/guides/zitadel_activate_azure.png)
## Test the setup
<TestSetup loginscreen="your Microsoft login"/>
![Azure AD Button](/img/guides/zitadel_login_azure.png)
![Entra ID Button](/img/guides/zitadel_login_azure.png)
![Azure AD Login](/img/guides/microsoft_login.png)
![Entra ID Login](/img/guides/microsoft_login.png)

8
docs/docs/guides/integrate/identity-providers/migrate.mdx
View File

@ -6,7 +6,8 @@ sidebar_label: Migrate IDP
## Migrate Generic OIDC Provider
You can migrate from a generic OIDC provider to the following supported templates:
- AzureAD
- Entra ID (former Azure Active Directory)
- Google
To migrate, you either use the [Migrate Generic OIDC Identity Provider (Instance)](/docs/apis/resources/admin/admin-service-migrate-generic-oidc-provider#migrate-generic-oidc-identity-provider) or [Migrate Generic OIDC Identity Provider (Organization)](/docs/apis/resources/mgmt/management-service-migrate-generic-oidc-provider#migrate-generic-oidc-identity-provider) API request.
@ -19,11 +20,12 @@ These calls change the type of the provider and don't delete any linked users.
The available configuration is described in [Google Configuration](./google).
### AzureAD Configuration
### Entra ID Configuration
The available configuration is described in [AzureAD Configuration](./azure-ad).
The available configuration is described in [Entra ID Configuration](./azure-ad).
## Migrate with Terraform
Please note that you only have to perform this migration if you already have an existing IDP with linked users, that should not loose the connection to the provider.
If that isn't your case please just add a new provider from scratch.
To migrate to a specific provider, you need to follow a few essential steps:

234
docs/docs/guides/integrate/login/login-users.mdx Normal file
View File

@ -0,0 +1,234 @@
---
title: Login users into your application with a hosted or custom login UI
sidebar_label: Hosted vs. Custom Login UI
---
ZITADEL is a comprehensive identity and access management platform designed to streamline user authentication, authorization, and management processes for your application. It offers a range of features, including single sign-on (SSO), multi-factor authentication (MFA), and centralized user management.
With ZITADEL, you can securely authenticate users using industry-standard protocols such as OpenID Connect and SAML. This enables seamless integration with various applications and services, providing a unified authentication experience for your users.
Besides federated authentication with OpenID Connect and SAML, ZITADEL offers an API to authenticate users allowing you to create your own login process and user interface.
In this guide, we will walk through the different protocols, features and concepts that can be used to login users securely into your applications.
![Screenshot of ZITADEL login screen](/img/guides/integrate/login/login-start.png)
## Using industry-standard protocols
### Authenticate users with OpenID Connect 1.0
OpenID Connect (OIDC) offers a modern and lightweight authentication protocol built on top of OAuth 2.0, providing flexible authentication flows and easy integration with web and mobile applications.
ZITADEL offers a certified compliant implementation of the OpenID Connect Standard, ensuring compliance with proven security best practices.
Authenticating users through the OpenID Connect protocol typically requires an application to redirect the user with an [Auth Request](/docs/apis/openidoauth/authrequest) to the identity provider that contains information such as the requesting application, [scopes](/docs/apis/openidoauth/scopes), and redirect url.
The identity provider is not part of the original application, but a standalone service like ZITADEL that may run under the [same domain](/docs/concepts/features/custom-domain.md)
The user will authenticate using their credentials.
After successful authentication, the user will be redirected back to the original application.
### Authenticate users with SAML
SAML (Security Assertion Markup Language) is a widely adopted standard for exchanging authentication and authorization data between identity providers and service providers.
Authentication with SAML (Security Assertion Markup Language) involves a series of exchanges between a service provider (SP), an identity provider (IdP), and the user. Here's an overview of how the process typically works:
1. **User Attempts to Access a Service**: The user tries to access a service or application that requires authentication, such as logging into a web application.
2. **Service Provider Redirects to Identity Provider**: The service provider (SP) detects that the user needs to be authenticated and redirects the user's browser to the designated identity provider (IdP) for authentication. This redirection often occurs via a SAML request, which includes information about the service provider and a request for authentication.
3. **User Authenticates with Identity Provider**: The user is presented with the identity provider's login page, where they enter their credentials (username and password). Alternatively, depending on the IdP's configuration, the user might be authenticated using single sign-on (SSO) mechanisms such as a pre-existing session or multi-factor authentication.
4. **Identity Provider Generates SAML Assertion**: Upon successful authentication, the identity provider creates a SAML assertion containing information about the user, such as their identity and attributes. This assertion is digitally signed by the identity provider to ensure its integrity and authenticity.
5. **SAML Assertion Sent to Service Provider**: The identity provider sends the SAML assertion back to the user's browser as a response to the original SAML request. The browser then forwards the assertion to the service provider.
6. **Service Provider Validates SAML Assertion**: The service provider receives the SAML assertion and validates it to ensure its integrity and authenticity. This typically involves verifying the digital signature of the assertion and checking that it originated from a trusted identity provider.
7. **User Granted Access**: If the SAML assertion is successfully validated, the service provider considers the user authenticated and grants them access to the requested service or application. The user can now interact with the service without needing to reauthenticate until their session expires or they log out.
Overall, authentication with SAML provides a secure and standardized method for enabling single sign-on (SSO) and federated identity management across different applications and systems.
It allows users to access multiple services with a single set of credentials, streamlining the authentication process while maintaining strong security measures.
Note that SAML might not be suitable for mobile applications.
In case you want to integrate a mobile application, use OpenID Connect or our Session API.
There are more [differences between SAML and OIDC](https://zitadel.com/blog/saml-vs-oidc) that you might want to consider.
### ZITADEL's Session API
ZITADEL's [Session API](/docs/apis/resources/session_service) provides developers with a straightforward method to manage user sessions within their applications.
The Session API is not an industry-standard and can be used instead of OpenID Connect or SAML to authenticate users by [building your own custom login user interface](/docs/guides/integrate/login-ui).
#### Tokens in the Session API
The session API will return a session token that can be used to authenticate users from your application.
This token should not be confused with am access or id tokens in opaque or JWT form that is issued during OpenID connect flows.
:::info Token exchange
Token exchange between Session API and OIDC / SAML tokens is not possible at this moment.
:::
#### Key features of the Session API
These are some key features of the API:
1. **Session Management**: The Session API allows you to create, retrieve, update, and delete sessions for users within your application. Sessions represent a user's active login session, providing temporary access to your application's resources.
2. **Creating Sessions**: With the Session API, you can initiate a new session for a user after they successfully authenticate through ZITADEL. This typically involves generating a session token or ID, which is then associated with the user's identity and used to track their session activity.
3. **Retrieving Sessions**: You can retrieve information about existing sessions using the Session API, such as session ID, user ID, creation time, and expiration time. This allows you to monitor active user sessions and retrieve session details as needed for auditing or troubleshooting purposes.
4. **Updating Sessions**: The Session API enables you to update session attributes or extend session lifetimes based on specific application requirements. Each authentication step, such as username / password check or multi-factor verification, will result in an update session. Also you might want to refresh a session token periodically to prevent it from expiring prematurely or update session metadata to reflect changes in user permissions or settings.
5. **Deleting Sessions**: When a user logs out or their session expires, you can use the Session API to delete the corresponding session from your application's records. This helps maintain data integrity and security by ensuring that inactive sessions are properly removed from the system.
Overall, ZITADEL's Session API simplifies session management within your application, providing a convenient and secure way to track user sessions, enforce session policies, and maintain a seamless user experience. By integrating the Session API into your application, you can effectively manage user authentication and access control while ensuring data privacy and security.
## Use the Hosted Login to sign-in users
ZITADEL provides a hosted single-sign-on page to securely sign-in users to your applications.
ZITADEL's hosted login page serves as a centralized authentication interface provided for applications that integrate ZITADEL.
As a developer, understanding the hosted login page is essential for seamlessly integrating authentication into your application.
### Centralized authentication endpoint
ZITADEL's hosted login page acts as a centralized authentication endpoint where users are redirected to authenticate themselves.
When users attempt to access a protected resource within your application, you can redirect them to the hosted login page to authenticate using their login methods and credentials or through Single-sign-on (SSO).
After successful authentication, the user will be redirected back to the originating application.
### Security and compliance
ZITADEL's hosted login page prioritizes security and compliance with industry standards and regulations.
It employs best practices for securing authentication processes, such as encryption, token-based authentication, and adherence to protocols like OAuth 2.0, [OpenID Connect](/docs/guides/integrate/login/oidc), and [SAML](/docs/guides/integrate/login/).
We make sure to harden the login UI and minimize the attack surface.
One of the measures we apply is setting the necessary security heads thus minimizing the risk of common vulnerabilities in login pages, such as XSS vulnerabilities.
Put your current login to the test and compare the results with our hosted login page.
Tools like [Mozilla's Observatory](https://observatory.mozilla.org/) can give you a good first impression about the security posture.
### Developer-friendly integration
Integrating the hosted login page into your application is straightforward, thanks to ZITADEL's developer-friendly documentation, SDKs, and APIs. Developers can easily implement authentication flows, handle authentication callbacks, and customize the user experience to seamlessly integrate authentication with their application's workflow.
Overall, ZITADEL's hosted login page simplifies the authentication process for developers by providing a secure, customizable, and developer-friendly authentication interface. By leveraging this centralized authentication endpoint, developers can enhance their application's security, user experience, and compliance with industry standards and regulations.
## Key features of the hosted login
### Flexible usernames
Different login name formats can be used on ZITADEL's hosted login page to select a user.
Login methods can be a user's username, containing the username and an [organization domain](/docs/guides/manage/console/organizations#domain-verification-and-primary-domain), their email addresses, or their phone numbers.
By default, all of these login methods are allowed and can be adjusted by [Managers](/docs/concepts/structure/managers) to meet their requirements.
### Support for multiple authentication methods
The hosted login page supports various authentication methods, including traditional username/password authentication, social login options, multi-factor authentication (MFA), and passwordless authentication methods like [passkeys](/docs/concepts/features/passkeys.md).
The second factor (2FA) and multi-factor authentication methods (MFA) available in ZITADEL include OTP via an authenticator app, TOTP via SMS, OTP via email, and U2F.
Developers can configure the authentication methods offered on the login page based on their application's security and usability requirements.
### Enterprise single-sign-on
![Screenshot of ZITADEL console showing different identity provider templates](/img/guides/integrate/login/login-external-idp-templates.png)
With the hosted login page from ZITADEL developers will get the best support for multi-tenancy single-sign-on with third-party identity providers.
ZITADEL acts as an [identity broker](/docs/concepts/features/identity-brokering) between your applications and different external identity providers, reducing the implementation effort for developers.
External Identity providers can be configured for the whole instance or for each organization that represents a group of users such as a B2B customer or organizational unit.
ZITADEL offers various [identity provider templates](/docs/guides/integrate/identity-providers) to integrate providers such as [Okta](/docs/guides/integrate/identity-providers/okta), [Entra ID](/docs/guides/integrate/identity-providers/azure-ad) or on-premise [LDAP](/docs/guides/integrate/identity-providers/ldap).
### Multi-tenancy authentication
ZITADEL simplifies multi-tenancy authentication by securely managing authentication for multiple tenants, called [Organizations](/docs/concepts/structure/organizations), within a single [instance](/docs/concepts/structure/instance).
Key features include:
1. **Secure Tenant Isolation**: Ensures robust security measures to prevent unauthorized access between tenants, maintaining data privacy and compliance. [Managers](/docs/concepts/structure/managers) for an organization have only access to data and configuration within their Organization.
2. **Custom Authentication Configurations**: Allows tailored [authentication settings](/docs/guides/manage/console/instance-settings#login-behavior-and-access), [branding](/docs/guides/manage/customize/branding), and policies for each tenant.
3. **Centralized Management**: Provides [centralized administration](/docs/guides/manage/console/managers) for efficient management across all tenants.
4. **Scalability and Flexibility**: Scales seamlessly to accommodate growing organizations of all sizes.
5. **Domain Discovery**: Starting on a central login page, route users to their tenant based on their email address or other user attributes. Authentication settings will be applied automatically based on the organization's policies, this includes routing users seamlessly to third party identity providers like [Entra ID](/docs/guides/integrate/identity-providers/azure-ad).
### Customization options
While the hosted login page provides a default authentication interface out-of-the-box, ZITADEL offers [customization options](/docs/guides/manage/customize/branding) to tailor the login page to match your application's branding and user experience requirements.
Developers can customize elements such as logos, colors, and messaging to ensure a seamless integration with their application's user interface.
:::info Customization and Branding
The login page can be changed by customizing different branding aspects and you can define a custom domain for the login (eg, login.acme.com).
By default, the displayed branding is defined [based on the user's domain](/docs/guides/solution-scenarios/domain-discovery). In case you want to show the branding of a specific organization by default, you need to either pass a primary domain scope (`urn:zitadel:iam:org:domain:primary:{domainname}`) with the authorization request, or define the behavior on your Project's settings.
:::
### Fast account switching
The hosted login page remembers users who have previously authenticated.
In case a user has used multiple accounts, for example, a private account and a work account, to authenticate, then all accounts will be shown on the Account Picker.
Users can still login with a different user that is not on the list.
This allows users to quickly switch between users and provide a better user experience.
:::info
This behavior can be changed with the authorization request. Please refer to our [guide](/guides/integrate/login/oidc/login-users).
:::
### Self-service for users
ZITADEL's hosted login page offers [many self-service flows](/docs/concepts/features/selfservice) that allow users to set up authentication methods or recover their login information.
Developers use the self-service functionalities to reduce manual tasks and improve user experience.
Key features include:
### Password reset
Unauthenticated users can request a password reset after providing the loginname during the login flow.
- User selects reset password
- An email will be sent to the verified email address
- User opens a link and has to provide a new password
#### Prompt users to set up multifactor authentication
Users are automatically prompted to provide a second factor, when
- Instance or organization [login policy](/concepts/structure/policies#login-policy) is set
- Requested by the client
- A multi-factor is set up for the user
When a multi-factor is required, but not set up, then the user is requested to set up an additional factor.
:::info Disabling multifactor prompt
You can disable the prompt, in case multifactor authentication is not enforced by setting the [**Multifactor Init Lifetime**](/docs/guides/manage/console/instance-settings#login-lifetimes) to 0.
:::
#### Enroll passkeys
Users can select a button to initiate passwordless login or use a fall-back method (ie. login with username/password), if available.
The passwordless with [passkeys](/docs/concepts/features/passkeys.md) login flow follows the FIDO2 / WebAuthN standard.
With the introduction of passkeys the gesture can be provided on ANY of the user's devices.
This is not strictly the device where the login flow is being executed (e.g., on a mobile device).
The user experience depends mainly on the operating system and browser.
## Build a custom Login UI to authenticate users
In certain cases, you want to build your own login UI to optimize your user experience.
We have dedicated guides on [how to build your custom login UI](http://localhost:3000/docs/guides/integrate/login-ui) with ZITADEL.
When building your own login UI, you will leverage the [Session API](#zitadels-session-api) to authenticate users and manage user sessions.
:::info Session API support for OIDC and SAML
At the moment developers can only integrate with ZITADEL's Session API and not with standard compliant OpenID Connect or SAML flows.
:::
### When to build your custom Login UI
Main reasons why developers might want to build their own login UI include:
1. **Embedding Login in your application**: From a security standpoint you should follow the best practice recommendation to open a browser and then redirect to your application. For certain applications, such as games or mobile apps, you might want to embed the login for a better user experience
2. **Customize business process**: You might want to change existing flows that are provided by the hosted login to fit your business process. Make sure to validate that your customization can't be handled by [Actions](/docs/guides/manage/customize/behavior) instead.
3. **Customize branding**: We designed the hosted login with security in mind, which limits the [customization capabilities](/docs/guides/manage/customize/branding). Besides that we might not be able to handle all requirements for custom branding. If you believe your customization should be part of the hosted login instead, please open an [improvement idea](https://github.com/zitadel/zitadel/issues/new/choose).
4. **Independence of standards** You don't want or need to rely on industry standards for authentication such as OpenID Connect or SAML for authenticating users.
## Further reference
- Learn how to [register and onboard users](/docs/guides/integrate/onboarding)
- Learn how to [build your own login UI](/docs/guides/integrate/login-ui) based on ZITADEL
- Learn how to [configure ZITADEL](/docs/guides/manage/console/overview) through the Console

0
docs/docs/guides/integrate/_authmethods.mdx → docs/docs/guides/integrate/login/oidc/_authmethods.mdx
View File

0
docs/docs/guides/integrate/authmethods/_basic.mdx → docs/docs/guides/integrate/login/oidc/authmethods/_basic.mdx
View File

0
docs/docs/guides/integrate/authmethods/_implicit.mdx → docs/docs/guides/integrate/login/oidc/authmethods/_implicit.mdx
View File

0
docs/docs/guides/integrate/authmethods/_jwtpk.mdx → docs/docs/guides/integrate/login/oidc/authmethods/_jwtpk.mdx
View File

0
docs/docs/guides/integrate/authmethods/_pkce.mdx → docs/docs/guides/integrate/login/oidc/authmethods/_pkce.mdx
View File

0
docs/docs/guides/integrate/authmethods/_pkcenative.mdx → docs/docs/guides/integrate/login/oidc/authmethods/_pkcenative.mdx
View File

16
docs/docs/guides/solution-scenarios/device-authorization.mdx → docs/docs/guides/integrate/login/oidc/device-authorization.mdx
View File

@ -1,11 +1,23 @@
---
title: OAuth 2.0 Device Authorization Flow
title: Integrating Your Application with ZITADEL using RFC 8628 OAuth 2.0 Device Authorization Flow
sidebar_label: Device Authorization
---
ZITADEL implements device authorization as per [RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628). This document demonstrates its use.
## Setup in ZITADEL
This documentation aims to guide you through the process of seamlessly integrating your application with ZITADEL, leveraging the capabilities of [RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628). ZITADEL is a powerful identity and access management (IAM) solution that provides robust authentication and authorization services for your applications. RFC 8628, also known as "OAuth 2.0 Device Authorization Grant", offers a standardized protocol for devices with limited input capabilities to obtain user authorization. By following the steps outlined here, you'll be able to empower your application with secure authentication and access control mechanisms provided by ZITADEL, ensuring a smooth and secure user experience.
## What is RFC 8628?
[RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628), or the OAuth 2.0 Device Authorization Grant, defines a protocol for OAuth 2.0 clients that have limited input capabilities, such as devices with no browser or low-power sensors. It allows such devices to obtain user consent for authorizing access to protected resources by directing the user to a device-friendly authentication endpoint.
## Why Integrate with Zitadel?
ZITADEL offers a comprehensive identity and access management solution, providing features like single sign-on (SSO), multi-factor authentication (MFA), user management, and more. By integrating your application with ZITADEL, you can leverage these powerful features to enhance the security and usability of your application without reinventing the wheel.
## Getting Started
To begin integrating your application with Zitadel using RFC 8628, follow the steps outlined in this documentation. We'll walk you through the process, from setting up your application in the Zitadel console to handling user authentication and access tokens in your application code.
1. Go to “Organization”/”Projects”.
2. Under “Applications” click the “New” button.

4
docs/docs/guides/integrate/login-users.mdx → docs/docs/guides/integrate/login/oidc/login-users.mdx
View File

@ -1,5 +1,5 @@
---
title: Login Users into your Application with ZITADEL
title: Authenticate users with OpenID Connect
sidebar_label: Login
---
@ -88,7 +88,7 @@ When selecting Native the authentication method always needs to be PKCE.
#### Authentication method
When selecting SPA the recommended authentication method is again PKCE. All common Frameworks like Angular, React, Vue.js and so on
are able to successfully authenticate with PKCE. Our Managament UI Console for instance uses PKCE as well.
are able to successfully authenticate with PKCE. Our management UI Console for instance uses PKCE as well.
<AuthMethods selected="spa" />
</TabItem>

0
docs/docs/guides/integrate/logout.md → docs/docs/guides/integrate/login/oidc/logout.md
View File

44
docs/docs/guides/integrate/oauth-recommended-flows.md → docs/docs/guides/integrate/login/oidc/oauth-recommended-flows.md
View File

@ -1,36 +1,11 @@
---
title: Recommended Authorization Flows
title: Recommended authorization flows with OpenID Connect (OIDC) and OAuth 2.x
sidebar_label: Recommended authorization flows
---
<table className="table-wrapper">
<tbody>
<tr>
<td>Description</td>
<td>Learn about the different authentication flows and which flow we recommend you should use for your application.</td>
</tr>
<tr>
<td>Learning Outcomes</td>
<td>
In this module you will:
<ul>
<li>Learn the basics of federated identities</li>
<li>Understand the basics of OAuth 2.x client profiles and their importance for authorization flows</li>
<li>Get a recommended flow for Web, Native, User-Agent, and API</li>
</ul>
</td>
</tr>
<tr>
<td>Prerequisites</td>
<td>
Basic knowledge about federated identities
</td>
</tr>
</tbody>
</table>
## Introduction
Before we get into setting up our first application within ZITADEL, we need to go through some basics on how to obtain an authorization with OpenID Connect 1.x and OAuth 2.x.
In this guide we will go over some basics on how to obtain an authorization with OpenID Connect 1.x and OAuth 2.x.
ZITADEL does not make assumptions about the application type you are about to integrate. Therefore you must qualify and define an appropriate method for your users to gain authorization to access your application (“authentication flow”). Your choice depends on the application’s ability to maintain the confidentiality of client credentials and the technological capabilities of your application. If you choose a deprecated or unfeasible flow to obtain authorization for your application, your users’ credentials may be compromised.
@ -126,16 +101,3 @@ If you don’t have any technical limitations, you should prefer this method ove
A JWT with a private key can also be used with client profile web to further enhance security.
In case you need alternative flows and their advantages and drawbacks, there will be a module to outline more methods and our recommended fallback strategy per client profile that are available in ZITADEL.
## Summary (3)
- Federated Identities solve key problems and challenges with traditional server-client architecture
- Use “Authorization Code with Proof Key of Code Exchange (PKCE)” for User-Agent, Native, and Web clients
- “JWT bearer token with private key” for Machine-to-Machine clients
- There are alternative flows and fallback strategies supported by ZITADEL, if these flows are technically not possible
### Where to go from here
- Applications
- Service Accounts
- Alternative authentication flows (aka. "The Zoo")

2
docs/docs/guides/solution-scenarios/onboarding/_org_login_description.mdx → docs/docs/guides/integrate/onboarding/_org_login_description.mdx
View File

@ -1,5 +1,5 @@
Per default the login ui of the default organization is shown.
To allow users of a specific organization to register with their IDP (e.g Azure AD) you have two options.
To allow users of a specific organization to register with their IDP (e.g Entra ID) you have two options.
1. Identify organization with organization scope

14
docs/docs/guides/solution-scenarios/onboarding/b2b.mdx → docs/docs/guides/integrate/onboarding/b2b.mdx
View File

@ -1,9 +1,15 @@
---
title: Onboarding B2B Customer
title: Onboard B2B customers using organizations
sidebar_label: Onboard B2B customer
---
In this guide we will explain how you can create and set up new organizations in ZITADEL to help you with your onboarding flows.
Creating a new organization is the best choice for multi-tenancy use cases that require separation of customers, teams, or groups of users.
We will also explain how to leverage [Managers](/docs/guides/manage/console/managers) to delegate self-service team management and configuration of policies to users of each organization.
When you want to build an onboarding process for your business customers you have to go through the following steps:
1. Create an organization: The organization represents the customer or a team
2. Create the first administrator user: This user is the account for your customer, which should be able to configure settings such as SSO, MFA, etc.
3. Give the user permission to configure settings, create users and assign roles to users in ZITADEL
@ -101,11 +107,11 @@ This setting does generally allow users to authenticate with an external provide
#### Auto-register users with SSO
Let's assume you have configured AzureAD as an identity provider, and you want to allow all your employees to login with the corresponding user without having to register.
Let's assume you have configured Entra ID as an identity provider, and you want to allow all your employees to login with the corresponding user without having to register.
This does need some specific configuration on your provider.
1. Go to the detail page of your configured identity provider (In this example AzureAD)
2. Enable "Automatic creation" in the optional settings. Optionally if you want to update the user information in ZITADEL, when they have changed in the Azure AD additionally enable "Automatic update"
1. Go to the detail page of your configured identity provider (In this example Entra ID)
2. Enable "Automatic creation" in the optional settings. Optionally if you want to update the user information in ZITADEL, when they have changed in the Entra ID additionally enable "Automatic update"
3. Enable the "Account creation allowed" if it is not already
4. If you also want to allow users to link to an existing account, if they already have an account in ZITADEL, enable "Account linking allowed"

4
docs/docs/guides/solution-scenarios/onboarding/end-users.mdx → docs/docs/guides/integrate/onboarding/end-users.mdx
View File

@ -6,7 +6,7 @@ sidebar_label: Onboard Users
End Users have three different possibilities on how to login with ZITADEL.
1. Local Account with Username, Password, MFA, Passkey, etc
2. Social Login like Google, Apple, Github, etc
3. External Identity Provider hosted/managed by Organization like Azure AD, LDAP, Okta etc
3. External Identity Provider hosted/managed by Organization like Entra ID, LDAP, Okta etc
You can either use the hosted login of ZITADEL to let users register themselves, or you can build your own UI and use the existing APIs.
@ -61,7 +61,7 @@ The configured providers will be shown on the first login screen or when the use
#### Registration with Organization External Identity Provider
If your business customer already have an identity provider, and you want to allow SSO for them, you can configure their providers directly for their organization.
Configure the needed provider such as Azure AD or OKTA.
Configure the needed provider such as Entra ID or OKTA.
Please follow the configuration guides for the needed providers: [Let Users Login with Preferred Identity Provider in ZITADEL](/docs/guides/integrate/identity-providers)

2
docs/docs/guides/integrate/retrieve-user-roles.md
View File

@ -31,7 +31,7 @@ You must first of all generate a token for the user. If it’s a human user, he
How to generate a token:
- [Generate tokens for human users](/docs/guides/integrate/login-users)
- [Generate tokens for human users](/docs/guides/integrate/login/oidc/login-users)
- [Generate tokens for service users](/docs/guides/integrate/serviceusers)
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 console before requesting the token.

2
docs/docs/guides/manage/console/applications.mdx
View File

@ -47,7 +47,7 @@ At the moment ZITADEL offers four client types:
The first three options (Web, Native and User Agent) require user interaction, the fourth option (API) has no direct user-interaction.
Depending on the app type, there are small differences in the possible settings.
To get a good understanding about user profiles and recommended flows, read the following [guide](../../integrate/oauth-recommended-flows.md#different-client-profiles).
To get a good understanding about user profiles and recommended flows, read the following [guide](../../integrate/login/oidc/oauth-recommended-flows.md#different-client-profiles).
### Web

2
docs/docs/guides/manage/console/instance-settings.mdx
View File

@ -96,7 +96,7 @@ The Login Policy defines how the login process should look like and which authen
| Register allowed | Enable self register possibility in the login ui, this enables username password registration as well as registration with configured external identity providers |
| External IDP allowed | Possibility to login with an external identity (e.g Google, Microsoft, Apple, etc), If you like to allow external Identity providers add them to the providers list |
| Hide password reset | Disable the self-service option for users to reset their password. |
| Domain discovery allowed | If this setting is enabled, the user does't not mandatory have to exist when entering the username. It is required to have verified domains on the organization. Example: ZITADEL is registered as organization with the domain zitadel.com and AzureAD as identity provider. A user enters john@zitadel.com in the login but the user doesn't exist. The domain can be mapped to the organization and therefore the user can be redirected to the AzureAD.
| Domain discovery allowed | If this setting is enabled, the user does't not mandatory have to exist when entering the username. It is required to have verified domains on the organization. Example: ZITADEL is registered as organization with the domain zitadel.com and Entra ID as identity provider. A user enters john@zitadel.com in the login but the user doesn't exist. The domain can be mapped to the organization and therefore the user can be redirected to the Entra ID.
| Ignore unknown usernames | This setting can be enabled, if no error message should be shown if the user doesn't exist. Example: A user enters the login name john@zitadel.com, the user doesn't exist, but will be redirected to the password screen. After entering a password, the user will get an error that either username or password are wrong. |
| Disable login with email address | By default users can additionally [login with the email attribute](/docs/guides/solution-scenarios/configurations#use-an-email-address-as-username) of their user. Check this option to disable. |
| Disable login with phone number | By default users can additionally [login with the phonenumber attribute](/docs/guides/solution-scenarios/configurations#use-a-phone-number-as-username) of their user. Check this option to disable. |

2
docs/docs/guides/manage/customize/branding.md
View File

@ -43,7 +43,7 @@ If you like to trigger your settings for your applications you have different po
### 1. Primary Domain Scope
Send a [reserved scope](/apis/openidoauth/scopes) with your [authorization request](../../integrate/login-users#auth-request) to trigger your organization.
Send a [reserved scope](/apis/openidoauth/scopes) with your [authorization request](../../integrate/login/oidc/login-users#auth-request) to trigger your organization.
The primary domain scope will restrict the login to your organization, so only users of your own organization will be able to login.
You can use our [OpenID Authentication Request Playground](/apis/openidoauth/authrequest) to learn more about how to trigger an [organization's policies and branding](/apis/openidoauth/authrequest#organization-policies-and-branding).

2
docs/docs/guides/manage/customize/user-metadata.md
View File

@ -29,7 +29,7 @@ Use the [OIDC authentication request playground](/docs/apis/openidoauth/authrequ
:::info Getting a token
In case you want to test out different settings configure an application with code flow (PKCE).
Grab the code from the url parameter after a successful login and exchange the code for tokens by calling the [token endpoint](/docs/apis/openidoauth/endpoints#token_endpoint).
You will find more information in our guides on how to [authenticate users](/docs/guides/integrate/login-users).
You will find more information in our guides on how to [authenticate users](/docs/guides/integrate/login/oidc/login-users).
:::
## Use tokens to get user metadata

12
docs/docs/guides/solution-scenarios/b2b.mdx
View File

@ -1,5 +1,5 @@
---
title: ZITADEL for B2B Scenarios
title: Authentication and authorization in multi-tenancy B2B scenarios
sidebar_label: B2B
---
@ -8,8 +8,8 @@ import { B2B } from "../../../src/components/b2b";
## Business to Business
B2B describes the situation where an organization interacts with other organizations.
This **multiple organization architecture** usually adds some form of complexity to an Identity and Access Management System.
In ZITADEL a B2B organization represents a business partner or partner who typically has its own branding and has different access settings like an additional federated login for its users.
This **multi-tenancy architecture** usually adds some form of complexity to an Identity and Access Management System.
In ZITADEL an [organization](/docs/concepts/structure/organizations) 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.
@ -41,8 +41,8 @@ In order to define the need of the **Portal Application** some planning consider
### Login
You can decide whether a organization is preselected for the login or if the user is redirected to the default login screen. You can send the user to a specific organization by defining the organization in a custom scope. (primary domain)
Settings to the branding or the login options of the organization can be made from the organization section in [Console](https://{your_domain}.zitadel.cloud/ui/console/org).
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](/docs/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](/docs/concepts/features/console).
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 resource owner, or the projects resource owner.
### Organizations
@ -85,4 +85,4 @@ In such a case with this high potential of scalability where user counts can gro
- [Creating an organization](../manage/console/organizations)
- [Organization Branding](../manage/customize/branding)
- [Authorization](../integrate/oauth-recommended-flows)
- [Authorization](../integrate/login/oidc/oauth-recommended-flows)

6
docs/docs/guides/solution-scenarios/b2c.mdx
View File

@ -86,7 +86,7 @@ We'd appreciate if you could contribute to our repo with translations of your la
### Projects and applications
As our Hosted Login is a separate authentication screen, you have to determine how you are directing your users from your applications.
ZITADEL's Applications live under ZITADEL's Projects. You may add multiple applications for your different client-types (Native, Web, User Agent, or API). When setting up your applications consider reading our guide about [Authentication Flows](../integrate/login-users).
ZITADEL's Applications live under ZITADEL's Projects. You may add multiple applications for your different client-types (Native, Web, User Agent, or API). When setting up your applications consider reading our guide about [Authentication Flows](../integrate/login/oidc/login-users).
### Access Control
@ -99,10 +99,10 @@ Take the following considerations:
The data required to check if a user has access to a certain API is stored within a user grant. This information typically is stored within roles or custom claims and can be accessed with an `access` or OIDC `id` token.
Read more about Authorization in our [Guide](../integrate/oauth-recommended-flows).
Read more about Authorization in our [Guide](../integrate/login/oidc/oauth-recommended-flows).
## Learn more
- [Creating an organization](../manage/console/organizations#create-a-new-organization)
- [Organization Branding](../manage/customize/branding)
- [Authorization](../integrate/oauth-recommended-flows)
- [Authorization](../integrate/login/oidc/oauth-recommended-flows)

2
docs/docs/guides/solution-scenarios/configurations.mdx
View File

@ -9,7 +9,7 @@ In this section we show you the different use-cases we have already experienced,
## Automatically redirect users if the organization has only one identity provider
You have different customers (organizations) in your ZITADEL instance and they have different needs on how to authenticate their users. One of your customers does only allow login with an external identity provider like Google, Azure AD, and so on.
You have different customers (organizations) in your ZITADEL instance and they have different needs on how to authenticate their users. One of your customers does only allow login with an external identity provider like Google, Entra ID, and so on.
If a user of this organization wants to login, you don't want them to enter their username in the ZITADEL Login UI, they should be redirected directly to the identity provider without their interaction.
### Settings

4
docs/docs/guides/solution-scenarios/domain-discovery.mdx
View File

@ -15,7 +15,7 @@ In the example there is a service provider with a ZITADEL instance running on a
By default all users login on the organization **CIAM** with their preferred social login provider.
Users of the two business customers **Alpha** and **Beta** should login according to their organization login and access policy settings.
In case of Alpha users will login via an external identity provider (eg, [AzureAD](/docs/guides/integrate/identity-providers/azure-ad)).
In case of Alpha users will login via an external identity provider (eg, [Entra ID](/docs/guides/integrate/identity-providers/azure-ad)).
Beta users must only login with username/password and MFA instead.
For this scenario you need to route the user `alice@alpha.com` to the **Alpha Organization** and `bob@beta.com` to the **Beta Organization** respectively.
@ -116,7 +116,7 @@ Chuck
Alice
1. Alice enters alice@alpha.com and clicks next
1. Redirect to AzureAD Tenant (or any other IDP)
1. Redirect to Entra ID Tenant (or any other IDP)
1. Alice logs in with her company credentials
1. Redirected back to your application

2
docs/docs/guides/start/quickstart.mdx
View File

@ -225,7 +225,7 @@ We will now create an application in the project, which will allow our React cli
![Add Application](/img/guides/quickstart/41.png)
4. Select “PKCE” because we recommend the use of [Authorization Code](https://zitadel.com/docs/apis/openidoauth/grant-types#authorization-code) in combination with [Proof Key for Code Exchange (PKCE)](https://zitadel.com/docs/apis/openidoauth/grant-types#authorization-code) for all web applications. More about the different app types can be found [here](https://zitadel.com/docs/guides/integrate/oauth-recommended-flows#different-client-profiles). Click on "Continue".
4. Select “PKCE” because we recommend the use of [Authorization Code](/docs/apis/openidoauth/grant-types#authorization-code) in combination with [Proof Key for Code Exchange (PKCE)](/docs/apis/openidoauth/grant-types#authorization-code) for all web applications. More about the different app types can be found [here](/docs/guides/integrate/login/oidc/oauth-recommended-flows#different-client-profiles). Click on "Continue".
![Add Application](/img/guides/quickstart/42.png)

2
docs/docs/self-hosting/deploy/loadbalancing-example/loadbalancing-example.mdx
View File

@ -70,7 +70,7 @@ This is the IAM admin users login according to your configuration in the [exampl
- **username**: *root@<span></span>my-org.my.domain*
- **password**: *RootPassword1!*
Read more about [the login process](/guides/integrate/login-users).
Read more about [the login process](/guides/integrate/login/oidc/login-users).
<NoteInstanceNotFound/>

2
docs/docs/self-hosting/manage/configure/configure.mdx
View File

@ -98,7 +98,7 @@ This is the IAM admin users login according to your configuration in the [exampl
## What's next
- Read more about [the login process](/guides/integrate/login-users).
- Read more about [the login process](/guides/integrate/login/login-users).
- If you are running ZITADEL in production, you need to [customize your own domain](./custom-domain).
- Check out all possible [runtime configuration properties and their defaults in the source code](https://github.com/zitadel/zitadel/blob/main/cmd/defaults.yaml)
- Check out all possible [setup step configuration properties and their defaults in the source code](https://github.com/zitadel/zitadel/blob/main/cmd/setup/steps.yaml)

105
docs/sidebars.js
View File

@ -5,6 +5,7 @@ module.exports = {
type: "category",
label: "Get Started",
collapsed: false,
link: { type: "doc", id: "guides/start/quickstart" },
items: [
"guides/start/quickstart",
{
@ -50,6 +51,7 @@ module.exports = {
{
type: "category",
label: "Examples & SDKs",
link: {type: 'doc', id: 'sdk-examples/introduction'},
items: [
"sdk-examples/introduction",
"sdk-examples/angular",
@ -126,6 +128,10 @@ module.exports = {
{
type: "category",
label: "Console",
link: {
type: "doc",
id: "guides/manage/console/overview",
},
items: [
"guides/manage/console/overview",
"guides/manage/console/instance-settings",
@ -195,18 +201,68 @@ module.exports = {
items: [
{
type: "category",
label: "Authenticate Users",
collapsed: true,
label: "Login Users",
link: {
type: "generated-index",
title: "Authenticate Human Users",
slug: "guides/integrate/human-users",
description: "How to authenticate human users with OpenID Connect",
title: "Integrate",
slug: "guides/integrate/login",
description:
"Integrate your users and application with ZITADEL. In this section you will find resource on how to authenticate your users, configure external identity providers, access the ZITADEL APIs to manage resources, and integrate with third party services and tools.",
},
items: [
"guides/integrate/login-users",
"guides/integrate/oauth-recommended-flows",
"guides/integrate/logout",
'guides/integrate/login/login-users',
{
type: "category",
label: "Openid Connect",
collapsed: true,
link: {
type: "generated-index",
title: "Authenticate users with OpenID Connect (OIDC)",
slug: "guides/integrate/login/oidc",
description: "This guide explains how to utilize ZITADEL for user authentication within your applications using OpenID Connect (OIDC). Here, we offer comprehensive guidance on seamlessly integrating ZITADEL's authentication features, ensuring both security and user experience excellence. Throughout this documentation, we'll cover the setup process for ZITADEL authentication, including the recommended OIDC flows tailored to different application types. Additionally, we'll provide clear instructions on securely signing out or logging out users from your application, ensuring data security and user privacy. With our guidance, you'll be equipped to leverage ZITADEL's authentication capabilities effectively, enhancing your application's security posture while delivering a seamless login experience for your users.",
},
items: [
"guides/integrate/login/oidc/login-users",
"guides/integrate/login/oidc/oauth-recommended-flows",
"guides/integrate/login/oidc/device-authorization",
"guides/integrate/login/oidc/logout",
],
},
/*
{
type: "category",
label: "SAML",
collapsed: true,
link: {
type: "generated-index",
title: "Authenticate users with openid connect (OIDC)",
slug: "guides/integrate/login/saml",
description: ".",
},
items: [
{
type: "autogenerated",
dirName: "guides/integrate/login/saml",
},
],
},*/
],
},
{
type: "category",
label: "Onboard Customers and Users",
link: {
type: "generated-index",
title: "Onboard Customers and Users",
slug: "/guides/integrate/onboarding",
description:
"When building your own application, one of the first questions you have to face, is 'How do my customers onboard to my application?'\n" +
"These guides will explain the built-in solution for onboarding new tenants, customers, and users and how you can handle more advanced onboarding use cases. ",
},
collapsed: true,
items: [
"guides/integrate/onboarding/b2b",
"guides/integrate/onboarding/end-users",
],
},
{
@ -216,7 +272,7 @@ module.exports = {
type: "generated-index",
title: "Token Introspection",
slug: "/guides/integrate/token-introspection",
description:
description:
"Token introspection is the process of checking whether an access token is valid and can be used to access protected resources. You have an API that acts as an OAuth resource server and can be accessed by user-facing applications. To validate an access token by calling the ZITADEL introspection API, you can use the JSON Web Token (JWT) Profile (recommended) or Basic Authentication for token introspection. It's crucial to understand that the API is entirely separate from the front end. The API shouldn’t concern itself with the token type received. Instead, it's about how the API chooses to call the introspection endpoint, either through JWT Profile or Basic Authentication. Many APIs assume they might receive a JWT and attempt to verify it based on signature or expiration. However, with ZITADEL, you can send either a JWT or an opaque Bearer token from the client end to the API. This flexibility is one of ZITADEL's standout features.",
},
collapsed: true,
@ -416,25 +472,7 @@ module.exports = {
"guides/solution-scenarios/domain-discovery",
"guides/solution-scenarios/configurations",
"guides/solution-scenarios/frontend-calling-backend-API",
"guides/solution-scenarios/device-authorization",
"guides/solution-scenarios/restrict-console",
{
type: "category",
label: "Onboarding Customers and Users",
link: {
type: "generated-index",
title: "Onboarding Customers and Users",
slug: "/guides/solution-scenarios/onboarding",
description:
"When building your own application, one of the first questions you have to face, is 'How do my customers onboard to my application?'\n" +
"This guide will show you the built-in solution you have, within ZITADEL and how you can use ZITADEL when you have more advanced needs.",
},
collapsed: true,
items: [
"guides/solution-scenarios/onboarding/b2b",
"guides/solution-scenarios/onboarding/end-users",
],
}
],
},
{
@ -457,11 +495,14 @@ module.exports = {
"concepts/structure/users",
"concepts/structure/managers",
"concepts/structure/policies",
"concepts/features/identity-brokering",
"concepts/structure/jwt_idp",
"concepts/features/actions",
"concepts/features/audit-trail",
"concepts/features/selfservice",
{
type: "autogenerated",
dirName: "concepts/features",
},
{
type: "autogenerated",
dirName: "concepts/knowledge",
},
],
},
{

BIN
docs/static/img/guides/integrate/login/login-external-idp-templates.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 361 KiB

BIN
docs/static/img/guides/integrate/login/login-start.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 180 KiB

10
docs/vercel.json
View File

@ -19,6 +19,14 @@
{ "source": "/docs/apis/mgmt/:slug*", "destination": "/docs/apis/resources/mgmt/:slug*", "permanent": true },
{ "source": "/docs/apis/auth/:slug*", "destination": "/docs/apis/resources/auth/:slug*", "permanent": true },
{ "source": "/docs/apis/system/:slug*", "destination": "/docs/apis/resources/system/:slug*", "permanent": true },
{ "source": "/docs/apis/admin/:slug*", "destination": "/docs/apis/resources/admin/:slug*", "permanent": true }
{ "source": "/docs/apis/admin/:slug*", "destination": "/docs/apis/resources/admin/:slug*", "permanent": true },
{ "source": "/docs/guides/integrate/human-users", "destination": "/docs/guides/integrate/login", "permanent": true },
{ "source": "/docs/guides/solution-scenarios/device-authorization", "destination": "/docs/guides/integrate/login/oidc/device-authorization", "permanent": true },
{ "source": "/docs/guides/integrate/oauth-recommended-flows", "destination": "/docs/guides/integrate/login/oidc/oauth-recommended-flows", "permanent": true },
{ "source": "/docs/guides/integrate/login-users", "destination": "/docs/guides/integrate/login/oidc/login-users", "permanent": true },
{ "source": "/docs/guides/integrate/logout", "destination": "/docs/guides/integrate/login/oidc/logout", "permanent": true },
{ "source": "/docs/guides/solution-scenarios/onboarding", "destination": "/docs/guides/integrate/onboarding", "permanent": true },
{ "source": "/docs/guides/solution-scenarios/onboarding/b2b", "destination": "/docs/guides/integrate/onboarding/b2b", "permanent": true },
{ "source": "/docs/guides/solution-scenarios/onboarding/end-users", "destination": "/docs/guides/integrate/onboarding/end-users", "permanent": true }
]
}