Delegated access management

Hosted Login

Multifactor Authentication

Passwordless Authentication

Audit Trail

Identity Brokering

Platform

Service Accounts

Features

Easy integration

B2B (Business to Business)

Self Service

Existing identities

Secure authentication

Use Cases

Learn how to install, setup, and use ZITADEL.

Documentation

ZITADEL Cloud

Self-hosting

Trust center

Examples and Guides

Github Repository

Develop

Get Started

Contribute

Roadmap

Changelog

About Us

Jobs

Contact

Company

Read the blog

Sign up

Login

Pricing

Blog


<img
    src="/blog/2024-01-18-upcoming-features-2024-01.jpg" 
    width="100%"
    alt="Banner Image"
    style={{ margin: '0 auto' }}
  />

## Upcoming Features

After [a year of solid growth and improvements in 2023](https://zitadel.com/blog/recap-2023), we are already gearing up for what 2024 has in store for ZITADEL. Our focus is always on how we can make things better for you, and it’s not just about keeping up; it's about paving the way forward.

In this post, we want to give you a sneak peek into some of the key features on our [roadmap](https://github.com/orgs/zitadel/projects/6/views/1) for 2024. These features and enhancements will help make ZITADEL more intuitive, responsive, and, most importantly, aligned with your needs. We are excited to share these developments and continue our journey together in enhancing your experience with our platform. Here are the top features and offerings for 2024:

### 1. Authentication Examples and SDKs for the Most Used Languages

ZITADEL will be rolling out more easy-to-understand examples and SDKs this year. Whether you are working on a frontend or backend project, you will find clear, hands-on examples that show you how to integrate ZITADEL's authentication into your app. For frontend apps, you will see more examples with session management, user roles, and even how to handle user profiles. For the backend, you will see examples on how to handle various types of access control. All of them will use recommended OIDC libraries or SDKs. 

After setting the stage with these examples, ZITADEL's next move is to bring in more SDKs for languages like Java, Python, and PHP. We are planning to take them up a notch, showing you how to interact with ZITADEL APIs for more complex tasks, like managing user profiles or setting up security features. There will also be a wide range of languages and integration patterns. Whether you are coding in Python, PHP, or Java, or working on a mobile app, there is something in the pipeline for you. Plus, we are looking into making ZITADEL play nice with popular third-party tools. See this [epic](https://github.com/zitadel/zitadel/issues/5124) for more details. 

### 2. ZITADEL Cloud’s Data Region Expansion: Introducing US and EU Hosting in 2024

This year, ZITADEL is taking a significant step forward in its service offerings with the introduction of data regions in the US and EU (European Union). This move is all about giving customers more control and assurance over where their data is hosted.

Data location is a big deal. It's about knowing the specific region, which could be a country or a group of countries, where your data lives. ZITADEL understands that for many businesses and users, where their data is stored is as important as how it is stored. 

ZITADEL's cloud service is already offering a range of regions through Google Cloud Platform. These include:

- **Global:** This is the broadest option, where your data can be hosted in any of the cloud regions offered by ZITADEL’s provider.

- **Switzerland:** For those who prefer their data to stay in Switzerland, this option ensures hosting exclusively within the Swiss region.

- **GDPR Safe Countries:** This is for those who want to align with GDPR guidelines. Data is hosted within EU member states and other countries recognized as adequate under GDPR.

And the big news for this year:

- **US and EU Regions:** Recognizing the demand and importance of these regions, ZITADEL is set to offer cloud instances in both the US and the EU. This expansion means increased flexibility and more choices for businesses and individuals with specific needs or preferences for data hosting in these areas. We expect this expansion to go live by early Q1. As always, keep an eye on our website for the most current information regarding available regions.


### 3. Say Hello to Customizable User Schemas

ZITADEL is about to roll out a game-changer for businesses managing user data—[customizable user schemas](https://github.com/zitadel/zitadel/issues/6433)! This update responds to the growing demand for flexibility in user information management, allowing businesses to tailor user data fields to their specific needs and compliance requirements.

The new user schema feature in ZITADEL enables complete customization of user data fields. Businesses now have the freedom to determine which fields are necessary and which are not, eliminating the need to fill irrelevant fields. This flexibility also extends to defining which fields users can manage on their own and which ones require admin oversight.

Most importantly, despite the customizations, the user sign-in process will remain straightforward. ZITADEL ensures that the system works seamlessly without additional configurations. The update also promises efficient performance, with validations happening swiftly to ensure a smooth user experience. We are keeping it simple and user-friendly. 

We will enhance the user object structure to include a variety of fields like unique IDs, schema types, contact information, and custom profile fields, aligning with various user types. The introduction of a diverse range of authenticators will further enrich user interaction, catering to different security and access needs.

Incorporating JSON Schema Validation, the new feature allows robust validation of fields, ensuring data integrity and compliance. This flexibility also extends to management methods, with comprehensive options for creating, updating, and deleting users and schemas. Keep an eye out for this; it's going to make life a whole lot easier!


### 4. Custom Actions for Every Event and API Request

ZITADEL will be [extending actions to let you create custom actions](https://github.com/zitadel/zitadel/issues/7235) for every event, API call, and the functions you are already used to in ZITADEL. This means you can now tailor custom workflows to fit your exact needs. With this feature, you will be able to add your code, your own rules, right into ZITADEL's events and API calls. Whether it's an event in the system or an API request you are making, you will be able to hook in custom actions. 

- **Event-Based Actions:** You can attach actions to specific events within ZITADEL. After the event is stored, you decide when your custom action should kick in.

- **API Request Actions:** Similarly, for any API request, you can define actions to occur at different stages—during the request or in the response phase.

- **Multi-Event Actions:** And here's the kicker-you can create actions that run across multiple events. Think of it as a way to implement a consistent response or workflow across various parts of the system.

For developers, this feature is a game-changer. It means you can integrate ZITADEL more deeply into your systems and workflows. You are no longer just reacting to a few points during code execution—you gain the full flexibility of the programming language of your choice to customize the behavior of ZITADEL and react to events in real time. This level of customization is unprecedented and will unlock new ways of leveraging ZITADEL for your projects.



### 5. Streamlining User Management with Outbound Provisioning via SCIM

In 2024, ZITADEL will roll out a pretty cool feature that's going to make life a lot easier for businesses using Single Sign-On (SSO)—[outbound provisioning with SCIM (System for Cross-domain Identity Management)](https://github.com/zitadel/zitadel/issues/6601), and it's all about simplifying how user accounts sync up with external systems and applications.

Many SSO systems need a user account to already exist in their platform. Plus, these accounts must stay updated, especially when someone's status changes in the identity provider. This can get tricky when you're juggling multiple systems.

Understanding the need for pre-existing user accounts in many SSO systems, and the importance of keeping user statuses in sync with Identity Providers (IdPs), ZITADEL's solution focuses on extended actions. These allow for real-time updates and custom integrations with third-party systems, overcoming the challenges posed by standard SCIM implementations. This approach is not only more flexible but also caters to diverse use cases, offering businesses the ability to tailor their user management workflows.

Extended actions offer several advantages:
- They adapt to various third-party systems, allowing for a more personalized approach to user management.
- Changes in user accounts are instantly reflected across systems, ensuring up-to-date information.
- Supporting SCIM and generic API endpoints, this feature broadens the scope of integration possibilities.

The new feature enhances functionality through:
- Changes in user status automatically initiate actions, enabling immediate response to user management events.
- Fine-tuned control over actions based on user metadata or attributes.
- Options for executing REST calls or utilizing a SCIM module, enhancing data synchronization flexibility.
- Including all aspects of user management like creating, reading, updating, deleting, enabling/disabling users, and schema discovery.
- Detailed Documentation and Testing: Ensuring ease of integration and understanding.


### 6. Enhancing Team and Organization Onboarding with Improved Invitation Flows

ZITADEL is addressing a vital need in the B2B sector: [better and more intuitive ways to invite team and organization members](https://github.com/zitadel/zitadel/issues/7083). Recognizing the importance of streamlined team management and onboarding processes, ZITADEL is set to introduce enhanced invitation flows that cater to the specific requirements of business-to-business scenarios.

The proposed solution focuses on empowering managers to invite new users to their organization effortlessly. Here’s what it entails:

- **Email Invitations:** Users can be invited through an email containing a registration link specific to the organization from which the invite was sent.

- **SSO Integration:** If Single Sign-On is enabled, invitees have the option to sign up using an external identity provider, enhancing the ease of the onboarding process.

- **Customizable Email Texts:** The content of the invitation emails can be tailored to match the organization's tone and branding, offering a personalized touch.


This update is more than just about inviting members; it’s about enabling comprehensive team management within an application. This includes creating a new organization, appointing an admin user, configuring security settings like SSO and 2FA, and assigning roles to users. ZITADEL aims to make this process as intuitive as possible, addressing the common challenge of balancing authentication, authorization, and self-service configuration in cloud solutions.

ZITADEL recognizes that creating a custom onboarding experience is a frequent requirement. The new update will make it easier to understand and implement various methods for user registration, whether it’s through username/password, external IdPs, or social logins.
This feature will further enhance the critical aspects of the B2B onboarding process. 


### 7. User Group Authorizations

In 2024, ZITADEL will also introduce [user group authorizations](https://github.com/zitadel/zitadel/issues/5822), a game-changing feature for administrators. This update streamlines the way permissions and roles are managed by leveraging group-based authorizations. Its key advantages are:

- **Group-Based Access Control:** Admins can now manage permissions at the group level, rather than for individual users, saving time and reducing complexity.

- **Easy User and Group Management:** Features include creating, updating, searching, and deleting groups. Users can be added effortlessly or removed from these groups.

- **Merged Authorizations:** A standout feature where individual user roles are seamlessly combined with their group roles, enhancing flexibility and ensuring comprehensive access rights.

- **Integrated Authorization Visibility:** Group authorizations are integrated into tokens and user information, maintaining consistency across the platform.

In essence, ZITADEL's user group authorizations simplify and enhance access management, making it more efficient for administrators, especially in larger organizations. 


## Let's Go

As we wrap up our preview of what 2024 holds for ZITADEL, we are genuinely excited and hope you are too. A lot of hard work is going into developing these features, and we're eager for you to start using them. Make sure to stay tuned for our release announcements.

Your continuous support and feedback are what drive us. So, thank you for being an integral part of our journey. Here's to a groundbreaking year ahead!







This article provides an insightful overview of the exciting new features and updates that ZITADEL is set to roll out in 2024.

Exciting ZITADEL Features to Watch for in 2024

As we approach the end of 2023, it's an excellent time to reflect on how ZITADEL progressed throughout the year. We've remained committed to our promise of continuous innovation and delivering exceptional user experiences, as we set out to do at the beginning of the year.

ZITADEL significantly enhanced the developer experience by focusing on two key areas: API design and documentation. Firstly, we made a significant shift in our API design, moving towards a [resource-based approach](https://zitadel.com/blog/resource-api). This shift wasn't just a change; it was a strategic move to make our APIs more intuitive and developer-friendly. 

Then there's our documentation overhaul, making it more informative and user-friendly. This revamp was coupled with a streamlined onboarding process, designed to be quicker and more intuitive, particularly benefiting new users who are integrating ZITADEL into their systems for the first time. 

Here's a look back at the significant milestones we achieved:

## A Detailed Recap of ZITADEL's Product Features and Enhancements in 2023

###  Authentication and Identity Management

- **[Configurable Social/Enterprise Identity Provider Templates](https://zitadel.com/docs/guides/integrate/identity-providers):** We launched new social and enterprise SSO options, expanding our identity provider support to include Google, Github, Gitlab, Microsoft Azure AD, and Apple.
- **[Self-Hosting with Terraform](https://zitadel.com/docs/guides/manage/terraform/basics):** Simplified management of ZITADEL resources for a seamless setup.
- **[OIDC Version 2.0 Release](https://zitadel.com/blog/oidc-v2-release):** This was a significant update to our OpenID Connect library, including device authorization and token exchange.
- **[LDAP Login](https://zitadel.com/docs/guides/integrate/identity-providers/ldap):** Integration with Active Directory/LDAP for enabling the use of legacy systems as identity providers. 
- **[Device Authorization Grant](https://zitadel.com/blog/device-authorization):** Acknowledging the challenge of text input on certain devices, we implemented OAuth 2.0 Device Authorization Grant for a smoother user experience on input-constrained devices.
- **Email and SMS OTP Support:** Introduced one-time password for two-factor authentication.
- **ZITADEL API V2:** We've boosted our API with enhanced user registration and email verification features. Now in the beta stage, it allows you to create custom login interfaces and enables effective session management. Additionally, it supports integration with external providers, multifactor authentication options like TOTP and U2F/WebAuthN, streamlined password reset processes, and customizable methods for crafting your own login UI. This upgrade is all about giving you more control and flexibility.

### Security and Compliance

- **Event Audit Log with Advanced Filters and Threat Detection:** Our new audit log feature provides a comprehensive view of all actions and modifications, enhancing security and compliance capabilities.
- **[Client Credentials](https://zitadel.com/docs/guides/integrate/client-credentials) as JWT & PAT Alternative:** We introduced a third authentication method for service accounts, offering more flexibility.
- **Improved Password Change Notifications and Logging:** Enhanced security measures for user account management.
- **Support for Multiple Hashing Algorithms, Including PBKDF2:** Strengthened password hashing and migration capabilities. See the [ZITADEL passwap package]( https://github.com/zitadel/passwap), which provides a unified implementation between different password hashing algorithms. 
- **Technical Advisories and Updates:** We introduced [technical advisories](https://zitadel.com/docs/support/technical_advisory) to inform users about critical issues and updates for seamless operations.
- **Amplified Penetration Testing:** Complementing our secure coding practices, we intensified [third-party penetration tests](https://zitadel.com/blog/tags/pentest) and continued to encourage researchers to responsibly test and disclose vulnerabilities through our [disclosure policy](https://zitadel.com/docs/legal/policies/vulnerability-disclosure-policy). Adhering to this process, we consistently published [security advisories on GitHub](https://github.com/zitadel/zitadel/security/advisories) and proactively informed affected users and customers about any vulnerabilities.

### Developer Experience and Customization

- **Custom Claims and Role Integration:** Actions now allow for enhanced token customization, such as flat role claims and custom claims. This adds flexibility to include additional attributes in SAML responses as well.
- **Customizable Login UI:** ZITADEL now allows businesses to craft their own user interface for login, offering greater flexibility and personalization, along with guides to customize the login experiences using ZITADEL APIs.
- **Language Support:** Added Polish, Japanese, Spanish, Bulgarian, Macedonian, Brazilian Portuguese, Russian, and Dutch thanks to many contributions from our community.
- **Improved Onboarding Process:** An interactive in-app approach for a smoother user experience.

### Platform Enhancements and Integrations

- **Event Store Optimizations:** With ZITADEL's unique approach to event sourcing and CQRS, users can follow along the change track of the system. During the year, we took a big step forward in improving performance and parallel requests, and we prepared the storage layer for future improvements. Stay tuned for the upcoming blog series, which covers all the details of our journey. 
- **General Availability of PostgreSQL Support in ZITADEL:** PostgreSQL support is now fully integrated and generally available in ZITADEL, complete with Enterprise support. For more details, visit our guide on [managing databases with ZITADEL](https://zitadel.com/docs/self-hosting/manage/database).
- **Migration Guides:** We've developed thorough guides to smoothly transition your systems from platforms like [Auth0](https://zitadel.com/docs/guides/migrate/sources/auth0) and [Keycloak](https://zitadel.com/docs/guides/migrate/sources/keycloak) to ZITADEL, ensuring a hassle-free migration experience.


## Team and Community Updates

<figure>
  <img
    src="/blog/2023-12-29-recap-2023-01.png" 
    width="100%"
    alt="Team Retreat"
    style={{ margin: '0 auto' }}
  />
  <figcaption>
  The ZITADEL Team in Bucharest in October 
  </figcaption>
</figure>

### Welcoming New Team Members

[Tim Mohlmann](https://www.linkedin.com/in/tim-mohlmann/) joined as a Software Engineer, enhancing our development team with his technical expertise. Next, [Jason Burkhead](https://www.linkedin.com/in/jasonburkhead-06/) came on board as an Account Executive, bringing a new dynamism to our sales strategies.

### Team Retreats

Our first retreat in May in the scenic town of Habkern in Interlaken was a blend of team bonding and strategic planning amidst the beauty of Switzerland. In October, the team gathered in Bucharest,  absorbing the vibrant culture of Romania and fostering strong team unity.

### Community Engagement and Achievements

- **Contributions from the Community:** We had over a hundred contributions this year and would like to acknowledge and thank all our external contributors for their significant role in enhancing ZITADEL's features and functionalities.

- **Discord Community Grows to 1500 Members**: This milestone is a clear reflection of the engaging nature of our platform and the supportive spirit of our user base. We have an expanding community of enthusiasts and professionals who actively contribute to and benefit from our [Discord channel](https://zitadel.com/chat).

- **5750 GitHub Stars**: ZITADEL hit 5750 GitHub stars, a clear indicator of our growing influence and acceptance in the open-source community. This achievement is a collective success, made possible by the incredible support of our community members. Our [GitHub repository](https://github.com/zitadel/zitadel) continues to be a hub of innovation and collaboration. 


## New Updated Subscription Model: Aligning with Customer Needs

In 2023, ZITADEL took a customer-centric approach to update our subscription model for ZITADEL Cloud. 

In response to feedback from our users, we transitioned to using **Daily Active Users (DAUs)** as the primary metric for our subscriptions. We designed this shift from the previous request-based model to provide a clearer, more predictable structure that closely aligns with user engagement. The updated subscription plans are now more intuitive and tailored to actual usage, ensuring that our services resonate with your daily operations. The plans were made available for all customers, with existing subscribers given the option to switch at their convenience.

For a comprehensive overview of the subscription model, please see [ZITADEL's New Pricing](https://zitadel.com/pricing). Here, you'll find all the necessary details to understand how these changes might affect your current usage and future plans.

This update was a significant step in ZITADEL's journey this year, reflecting our commitment to evolving with market needs and enhancing customer experience.


## Recognition and Achievements in 2023

- **Featured in Star History Monthly Pick**: In January 2023, ZITADEL was featured in the Star History Monthly Pick. This feature by Star History HQ delved into the story behind our project, showcasing our journey and the impactful strides we've made in the identity and access management domain. The article is available for a detailed read at [Star History](https://star-history.com/blog/star-history-monthly-pick-202301).

- **Top 100+ Developer Tools for 2022 by StackShare**: ZITADEL's commitment to simplifying identity and access management for developers was further acknowledged when we were listed among the Top 100+ Developer Tools for 2022 by StackShare. For more information, visit [StackShare](https://stackshare.io/posts/top-developer-tools-2022).

- **Fastest-Growing Open-Source Startups in Q1 2023 ROSS Index**: The first quarter of 2023 brought us another significant milestone. ZITADEL was ranked among the fastest-growing open-source startups in the Q1 2023 ROSS Index. We extend our gratitude to Runa Capital for this recognition. To learn more about our ranking, visit the [ROSS Index](https://runacap.com/ross-index/q1-2023).

- **Switzerland's Most Influential Information Services Startups for 2023**: ZITADEL was honored with this award by Startup Bubble, recognizing our significant role in the information services sector. They positioned ZITADEL prominently in the fields of cybersecurity and web security in Switzerland. For more information about this recognition, visit [Startup Bubble](https://startupbubble.news/what-are-switzerlands-most-influential-information-services-startups-in-2023).

## Thank You

![Thank you](/blog/2023-12-29-recap-2023-02.png)

These updates highlight ZITADEL's commitment to providing a robust, secure, and user-friendly platform. We've made changes across the board to ensure our platform not only meets but exceeds the expectations of our users and the developer community.

As we wave goodbye to 2023, we're buzzing with excitement for the new horizons 2024 will bring. A huge shoutout to our awesome community and customers—your support, feedback, and ideas have been the secret sauce in ZITADEL's growth this year.

So, here's raising a toast to more innovation and even better user experiences! Wishing you all a fantastic and happy 2024! 



This post looks back at the pivotal moments and key updates that have shaped ZITADEL's journey in 2023

ZITADEL's 2023 in Review: Key Highlights and Updates

Using ZITADEL's OIDC integrations as a guide, this article offers insights into mastering the essential security measures of session timeouts, logouts, and token expriy.

Navigating Session Logouts, Timeouts, and Token Expiry


We decided to adopt a resource-based API for ZITADEL in response to feedback from our customers and community members.
Our overarching goal has always been to provide an exceptional experience for developers using our platform.
However, through ongoing conversations with users, we came to the understanding that while some of our architecture and design decisions were technically sound, they didn't necessarily translate into an intuitive and user-friendly experience from a developer's perspective.

Our API design was identified as one area where we could significantly enhance the developer experience.
By transitioning to a resource-based API, we are making our system more intuitive and easy to understand.
A resource-based API structure focuses on "resources" as the main entities, as opposed to methods or operations, which aligns better with the way developers think about their interactions with our platform.
We believe this change will make ZITADEL more approachable and enjoyable for developers to use.


## Persona-based API design

ZITADEL's API design is grounded in the concept of personas, each with different use cases.
The distinct APIs cater to these various personas and their specific needs, creating a more personalized and intuitive interface.
For instance, the Authentication API is designed primarily for currently authenticated users.
Therefore, if you're developing a user profile or settings page for authenticated users, the Authentication API would be your main resource. 

<figure>
  <img
    src="/blog/2023-08-03-resource-based-api-01.png"
    width="100%"
    alt="Persona-based API"
  />
  <figcaption>
    Figure 1: Persona-based API design
  </figcaption>
</figure>


Similarly, different APIs are designated for different roles.
The Management API is accessible to the administrator of an organization, while the Admin API is available for the IAM administrator.

At first glance, the division of responsibilities and access based on roles appears to make a lot of sense.
However, when we take into account how developers typically interact with our platform, potential complications become evident.
It's not uncommon for developers to dive straight into implementation without thoroughly studying the documentation. 

Let's take an example: a developer wants to create a settings page for a user and needs to retrieve the user information.
They would go to the API documentation and search for "get user".
This seemingly simple query returns multiple results, each tied to a different API and with different permissions:

- Auth API: "Get my own user"
- Management API: "Get user by ID from my organization"
- Admin API: "Get user by ID from any organization"

Without proper understanding of the differences between these APIs, developers may become confused and unsure about which option is the right one for their needs.
This is the kind of complication we aim to reduce with our new API design.

## Resource-based API design

After considering all the above factors, we have concluded that a resource-based API is significantly more straightforward to understand than a persona-based API.

By "resource-based API", we mean an API that allows access to the various resources ZITADEL provides, irrespective of the user's role or persona.
The fundamental principle here is that users access resources through a single API, and the depth or breadth of the results they see depends on the permissions of the user making the request.
This design simplifies the user's navigation through the API and makes for a more intuitive experience.


<figure>
  <img
    src="/blog/2023-08-03-resource-based-api-02.png"
    width="100%"
    alt="Resource-based API"
  />
  <figcaption>
    Figure 2: Resource-based API design
  </figcaption>
</figure>


Let's take an example of how this resource-based API design works.
Let's say we have a 'users' resource in the API.
This resource supports various operations such as create, update, delete, get by ID, and search for users.

- If I'm an end user, and I request a 'get by id' operation, the API will only permit me to retrieve my own user information, respecting the principle of least privilege.

- If I'm an administrator of an organization, I can utilize the 'search users' operation to retrieve details of all users within my organization, representing a higher level of access.

- Finally, if I'm an Identity and Access Management (IAM) administrator, I can use the 'search users' operation to access information on users across any organization in the system, reflecting the highest level of access.

This approach simplifies interactions by centralizing operations on a single resource, while still maintaining appropriate access control based on the user's role.

## Our Progress and Future Plans

We have already made considerable progress with the new API. 
All the necessary requests to construct your own login and registration UI have been implemented. 
As we continue to expand this new API, we will add new requests and gradually transition existing requests from the previous APIs (Auth, Management, Admin) to this new, resource-based API.

With the full implementation of this new API design, we are confident that we will significantly enhance the developer experience. We believe that these changes will simplify not only our customers' experience but also streamline our own operations. 
We look forward to offering a more efficient, user-friendly platform thanks to this resource-based API design.

Stay tuned for more updates! 


## Read the API Documentation

See the documentation of the currently available API resources of the new API if you want to learn more right away.

- [User](https://zitadel.com/docs/apis/resources/user_service)
- [Session](https://zitadel.com/docs/apis/resources/session_service)
- [Settings](https://zitadel.com/docs/apis/resources/settings_service)
- [OIDC](https://zitadel.com/docs/apis/resources/oidc_service)


We decided to adopt a resource-based API for ZITADEL in response to feedback from our customers and community members.

From Persona-based to Resource-based: Rethinking ZITADELs API Design


## Introduction

The current technological landscape has sparked a substantial shift in security strategies, steering us away from traditional perimeter-based models and towards a zero-trust approach. The embrace of multi-cloud infrastructures and remote work has further catalyzed this transition. An essential part of the shift to zero trust that often goes undiscussed is the move from coarse-grained to fine-grained security.

**[ZITADEL](https://zitadel.com/)**, a global and scalable identity and access management platform, provides robust default capabilities for managing access control through Role-Based Access Control (RBAC) and Delegated Access, laying a solid foundation for efficient and scalable access management. Yet, as we journey towards a zero-trust mindset, the limitations of coarse-grained security become increasingly apparent. The traditional RBAC system may grant an editor the rights to modify all documents, but interconnected and dynamic work environments require more fine-grained control. What if we want to grant editors access to edit documents related only to a specific project, within a certain time frame, or access only to a specific document? This is where fine-grained authorization steps in.

Fine-grained authorization enables access decisions based on various attributes such as user roles, specific attributes, actions they are trying to perform, and even contextual factors such as the time or location of access. Such nuanced access control is critical in modern applications.

In this article, we will delve into how ZITADEL responds to the growing demand for fine-grained authorization patterns. By leveraging ZITADEL's roles, meta-data, and actions, you can achieve a level of granularity and precision in access control that meets the demands of a zero-trust environment. Furthermore, ZITADEL can also integrate with external authorization services. Let’s explore!

## The Need for Fine-Grained Authorization and its Potential Benefits

<figure>
  <img src="/blog/2023-06-15-fine-grained-authorization-02.jpeg" width="100%" alt="fine-grained-auth" />
</figure>

Fine-grained authorization goes beyond traditional access control models by allowing access decisions to be based on more specific and varied factors. For instance, access might be granted based on the user's specific attributes, the resource they're trying to access, their location, the time of day, or any combination of these and more.

The key benefits of implementing fine-grained authorization are enhanced security, greater flexibility, regulatory compliance, and improved auditability. Thus, adopting a fine-grained authorization strategy can offer both enhanced security and operational advantages.

### Decoding Fine-Grained Authorization Techniques

Implementing fine-grained authorization isn't a one-size-fits-all proposition, and each organization may require a unique approach based on its specific use cases, existing infrastructure, and security requirements. Nonetheless, several common techniques and methodologies serve as the foundation of most fine-grained authorization strategies. Here, we'll decode some of these essential techniques.

- **Policy-Based Access Control (PBAC)**: A powerful tool in the fine-grained authorization arsenal is PBAC. This approach uses specific policies, typically written in declarative language, to decide whether a user or system should have access to a particular resource. Policies can factor in an extensive range of conditions, providing a granular level of control.

- ** Attribute-Based Access Control (ABAC)**: This technique expands upon the traditional role-based access control (RBAC) method. In ABAC, permissions are assigned based on user attributes, such as department or job title. This model provides more flexibility, as access decisions can be made based on a variety of user attributes and environmental conditions.

- **Relationship-Based Access Control (ReBAC)**: ReBAC is a recent evolution in access control models. It introduces the concept of relationships between subjects (users or groups) and objects (resources), allowing for even more specific access controls. This model can provide a powerful tool for multi-tenant applications, where resources need to be shared based on complex relationships.

- **Risk-based Access or Conditional Access**: Some applications may need to alter their behavior based on where a user is logged in from, what region the application is running in, or the day/time an operation is invoked. This is often due to regional differences in service levels or compliance requirements.

- **Fine-Grained Security Logging and Events**: The evolution towards fine-grained security also applies to security logging. Instead of merely recording logins, it's now crucial to log every access decision an application makes during a user's session. This helps identify and rectify over-provisioned or misconfigured permissions more effectively.

## ZITADEL’s Current Authorization Mechanisms

ZITADEL is a cloud-native Identity and Access Management solution (IAM) that provides various security mechanisms to secure applications and services. It employs a range of different authorization strategies, including Role-Based Access Control (RBAC) and Delegated Access.

### Role-Based Access Control (RBAC) and Delegated Access

ZITADEL employs RBAC as a primary mechanism for assigning and managing user permissions. In RBAC, permissions are associated with roles, and users are assigned to these roles. For example, you have the option to enforce access to resources by defining roles in the form of functional user roles (e.g., admin, editor, reader) or related to an application feature (e.g., book:read, book:edit). This approach provides a simple way to manage user access based on their roles within an organization.

The delegated access feature further extends this capability by allowing roles to be delegated to other organizations. This means you can provide an external organization with certain permissions within your system. This is particularly useful for organizations that work closely together or have a hierarchical structure.

These features provide a strong base for controlling access in various contexts. However, they may not be sufficient or can get too complicated for more complex authorization requirements that require a finer level of control, which leads us to the topic of implementing fine-grained authorization in ZITADEL.

## Extending ZITADEL's Existing Capabilities for Fine-Grained Access Control

Despite the comprehensive features that come with ZITADEL, there may be instances where a more customized or fine-grained approach is needed. Currently, the most effective way to implement fine-grained authorization in ZITADEL is by using custom application logic for smaller projects, or for larger scale projects, leveraging an available third-party tool such as [warrant.dev](https://warrant.dev/), [cerbos.dev](https://cerbos.dev/), etc. These tools can integrate with ZITADEL, further enhancing your capacity for nuanced, fine-grained authorization.

### Leverage the Actions Feature, Custom Metadata, and Claims for ABAC

ZITADEL goes beyond the static nature of RBAC with its dynamic [**Actions**](https://zitadel.com/docs/apis/actions/introduction) feature, designed to facilitate the implementation of attribute-based access control (ABAC). In contrast to RBAC, which assigns access rights based on a user's role, ABAC is a more flexible method that evaluates a set of attributes associated with the user, action, and resource for each access request.

In ZITADEL, the Actions feature can be used to create a post-authentication script that checks for specific user attributes and denies access if necessary. You can also use Actions to create custom claims that can further enhance your ABAC system. This powerful feature opens up the possibility for advanced authorization models, such as denying access to a resource based on the user's location, time of access, or any attribute that you can define and evaluate.

ZITADEL allows administrators or authorized developers to set custom metadata on users and organizations, further enhancing your ability to create fine-grained access control. Even aggregated claims are possible, where you request additional information from a third-party system and return the claims in the user information. This could be information from a CRM system, a training or certification tool, an HR system, or any other relevant source. Moreover, ZITADEL can handle application-specific resources such as shipping orders, IoT devices, and documents, and manage the policies defining access to these resources based on certain attributes. These attributes include User-Sub, Roles, Claims, IP, Tenant/Organization, and others.

## A Use Case

<figure>
  <img src="/blog/2023-06-15-fine-grained-authorization-01.jpeg" width="100%" alt="The roles in a media company" />
</figure>

In the fast-paced world of digital media, ensuring the right access to the right resources for the right employees is crucial. For a media company employing a host of journalists and editors, each with differing levels of experience and responsibility, the challenge lies in effectively managing access rights across various applications.

Let's consider such a media house. Here, the primary roles are journalists, who write articles, and editors, who review, edit, and publish these articles. The employees are further categorized based on their experience levels: junior, intermediate, and senior.

Let’s assume the media house has two primary applications in use. The first is a Newsroom Application, where journalists write their articles, and editors review, edit, and publish them. The second application is an HR Application. This handles all employee-related data and tracks their progress within the organization, including promotions and experience level changes. For example, when a journalist gets promoted from junior to intermediate, this change is recorded in the HR application. Access to certain features in the Newsroom Application needs to be strictly controlled. Junior journalists should only write articles, intermediate and senior journalists should be able to review articles, and only editors, particularly those with higher experience levels, should have the rights to edit and publish articles.

To manage these varied and complex access requirements, the media house utilizes ZITADEL, which they use for their general identity and access management needs. The goal here is to use ZITADEL's capabilities to ensure that access rights are correctly attributed according to both an employee's role and the seniority level, providing a clear separation of responsibilities within the media house.

Let's see how we can create a Flask API that upholds these access controls and how to configure ZITADEL to handle these authorization needs.

### The Application

Let’s assume that the main operational application within the media company is the Newsroom Application, a Flask-based API. The Flask API acts as the primary interface where journalists write articles and editors review, edit, and publish these articles. The API has been designed with specific endpoints that correspond to these permissions, enforcing role and experience-based access control.

Here are the primary endpoints that map to the permissions:

- **write_article**: This resource endpoint is exclusively for **journalists** to write articles. **All journalists**, regardless of their experience level, have access to this resource.
- **edit_article**: This resource endpoint is specifically for **editors**. It enables them to edit the articles written by the journalists.
- **review_articles**: This resource endpoint provides access to review articles, which is a responsibility given to **senior journalists**, and both **intermediate and senior editors**.
- **publish_article**: This resource endpoint is for publishing articles, a task designated to **intermediate and senior journalists**, and **senior editors**.

Each of these endpoints is accessible based on a combination of role and experience level, ensuring the right people have the right access.

Under the hood, the Flask API uses JWT (JSON Web Tokens) for authentication and authorization. When a user makes a request, they must provide a valid JWT as part of the request's Authorization header. This token is then decoded to verify its validity and to extract any custom claims.

[Custom claims](https://zitadel.com/blog/custom-claims) are key to this use case. They contain additional information about the user, in this case, the user's role and experience level. When a request is made to the API, these claims are extracted from the JWT and used to determine if the user has the necessary permissions to access the requested resource.

### Configure ZITADEL and Create the API

- Let’s first set up ZITADEL for this use case as explained in the [Set up ZITADEL](https://github.com/zitadel/example-fine-grained-authorization#1) section.
- Next, set up the API as explained in the [Set up the API Project](https://github.com/zitadel/example-fine-grained-authorization#2) section.
- Finally, test the API as explained in the [Run and Test the API](https://github.com/zitadel/example-fine-grained-authorization#3) section.

You can find all source files and instructions [here](https://github.com/zitadel/example-fine-grained-authorization).

### The Application Logic

<figure>
  <img src="/blog/2023-06-15-fine-grained-authorization-03.png" width="100%" alt="Application Flow" />
  <figcaption>
    Figure 1: Interactions showcasing the application of fine-grained authorization in a real-world Newsroom Application
  </figcaption>
</figure>

**User Role Assignment at Onboarding**: As part of the user onboarding process, each user is assigned a role. The role could be that of a `journalist` or `editor`. This role assignment is crucial as it is the basis for access control in our system.

**Experience Level Management by HR app**: Beyond the user role, the system also considers the user's experience level. The experience level (`junior`, `intermediate`, `senior`) is determined and managed by an HR application. When a change occurs in a user's experience level, it is updated as metadata in ZITADEL. It's worth noting that the system assumes a 'junior' level by default when no experience level is specified in the token claims.

**Token Validation**: [auth.py](https://github.com/zitadel/example-fine-grained-authorization/blob/main/auth.py) is responsible for token validation. When a request hits the API, [auth.py](https://github.com/zitadel/example-fine-grained-authorization/blob/main/auth.py) validates the token by calling ZITADEL's token introspection endpoint. If the token is valid and active, it is then decoded and printed for inspection. The decoded token (containing the user's role and experience level) is then made available globally using the Flask g object.

Note: Although JWTs can be validated locally using JWKS, we chose to use ZITADEL's token introspection endpoint for enhanced security and real-time token validity. This approach enables immediate revocation, simplifies implementation by centralizing control, and reduces the risk of security vulnerabilities. This helps ensure our API's authentication and authorization processes remain robust, accurate, and in sync with the current server state.

**Fine-Grained Access Control**: The Python Flask application is responsible for authorizing access to resources based on a user's role and experience level. It leverages a predefined access control list that maps each resource endpoint to the user roles and experience levels authorized to access them. This list serves as the rulebook for granting or denying access to resources. Each time a user attempts to access a resource, the function `authorize_access` checks if the user's role and experience level meet the access requirements for the requested endpoint. If they do, access is granted; if not, the function returns a message stating that access is denied, with details of the user's role and experience level and the resource they attempted to access.

**Business Logic**: [app.py](https://github.com/zitadel/example-fine-grained-authorization/blob/main/app.py) is the main Flask application file. It defines the resource endpoints and applies the token_required decorator (from [auth.py](https://github.com/zitadel/example-fine-grained-authorization/blob/main/auth.py)) to secure them. Each time a request is made to these secured endpoints, the token_required decorator first verifies the token. Then, the authorize_access function (from [access_control.py](https://github.com/zitadel/example-fine-grained-authorization/blob/main/access_control.py)) is called to check if the user is authorized to access the endpoint based on their role and experience level.
**Separation of Concerns**: In the design of this API, special attention was given to ensuring that business logic and access control rules are cleanly separated. This is crucial for the maintainability and scalability of the application.

The business logic is independent of who is allowed to access these endpoints, thus it is concerned only with performing actions rather than checking who can trigger these actions. [access_control.py](https://github.com/zitadel/example-fine-grained-authorization/blob/main/access_control.py) is strictly focused on implementing fine-grained access control rules. It does not concern itself with the specifics of how requests are processed, but only with who has the permission to make these requests. These rules are based on roles and experience levels stored in JWT token claims. The authorize_access function in [access_control.py](https://github.com/zitadel/example-fine-grained-authorization/blob/main/access_control.py) is used in the business logic layer ([app.py](https://github.com/zitadel/example-fine-grained-authorization/blob/main/app.py) ) to guard the endpoints.

The separation of business logic and access control rules allows for a clean, modular design where changes to business processes and access rules can be made independently of each other. This increases the maintainability of the code and makes it easier to manage as the application scales. Additionally, this design makes the system more secure as access rules are abstracted away from the main business logic, reducing the risk of accidentally introducing security vulnerabilities when modifying the business logic.

## Integrate with an External Authorization Service

ZITADEL allows integration with external authorization services such as [warrant.dev](https://warrant.dev/), [cerbos.dev](https://cerbos.dev/), or essentially any service that can consume ZITADEL's users and roles.
By using an external authorization service, you have the flexibility to create a fine-tuned authorization strategy that precisely meets your organization's needs. This could involve creating complex policies that dictate access based on a variety of user attributes and conditions, extending far beyond the traditional roles used in RBAC.

Instead of enforcing a one-size-fits-all solution, ZITADEL believes in giving users the tools and options to construct an access control framework that perfectly suits their organization's unique needs and challenges. This emphasis on flexibility ensures that as those needs evolve, the access control strategy can adapt seamlessly.


This articles showcases fine-grained authorization with ZITADEL and delves into managing access control, validating tokens, and separating business logic from authorization rules.

ZITADEL and Fine-Grained Authorization: A Code-Focused Exploration


When you attempt to access a system, network, or resource, it is critical that **the administration of the platform verifies your identity** to prevent unauthorized access to your personal data. This procedure is called **authentication**. 

The **piece of evidence** users need to provide to complete the authentication process may come in **various forms and quantities**: Be it a password, a fingerprint, a combination of the two, or something completely different. However, though there is a wide selection of common authentication methods, **not all are equally beneficial for end-users' safety**. 

With **[ZITADEL](https://zitadel.com/)** as your Identity and Access Management (IAM) solution, your end-users have the option to **enable any of our available authentication methods**: FIDO Universal 2nd Factor (U2F), FIDO2 Passkeys, Mobile Transaction Authentication Numbers (mTAN), Mobile One-Time-Passwords (OTP) and Password-based authentication. To help you weigh each method's pros and cons, this article **describes each process in greater detail**. 

Here are **ZITADEL's five implementable authentication methods** ranked from worst to best regarding **security and user experience (UX)**. 

![ZITADEL's Authentication Methods Overview](/blog/2023-06-01-authentication-methods-03.PNG "ZITADEL's Authentication Methods")

## Authentication Methods - Worst to Best

### 5. Passwords

Unsurprisingly, the title of the **lowest-ranking entry** on our list has to go to the most infamous form of authentication in the book: **passwords**. 

Since their inception in the 1960s, passwords have been a **standardized practice in validating our digital identities**. Their invention has not only brought the **concept of authentication** to light but also that of **cybersecurity** itself. 

However revolutionary passwords might have been for cybersecurity, the **rapid evolution of technical knowledge** amongst the public also opened the door for more and more cybercriminals who **take advantage of the simplicity of this authentication method**. As a response to these new cyberattacks, the notion of **password hygiene** has emerged: More and more platforms started urging their users to make their passwords **more complex and to change them periodically**. 

As of the 2020s, any password that does not include **at least one uppercase letter, one number, one symbol, and a total of 9 characters** can be [cracked within a maximum of three days](https://www.statista.com/chart/26298/time-it-would-take-a-computer-to-crack-a-password/). While setting up a long and convoluted password might solve the guessability issue, it simultaneously **defeats their original purpose of being easily recallable**. Moreover, even the most complex passwords are vulnerable to other cyberattacks, such as **brute-force attacks and [social engineering](https://zitadel.com/blog/social-engineering)**. 

Fortunately, the traditional username-password login approach is **no longer your sole option to protect your virtual identities**. There is a great variety of newer authentication methods to choose from that **significantly outperform passwords both in terms of User Experience and level of security**. 

### 4. One-Time-Passwords (OTP) mTAN

**One-time passwords (OTPs)** (also known as One-time codes) are a type of authentication in which **a unique password is generated for each login attempt** and, as the name suggests, can only be used once. Since OTPs are **commonly used as a second factor in two-factor authentication (2FA) or [multi-factor authentication (MFA)](https://zitadel.com/features#multifactor) systems**, most of us have likely already encountered this method of authentication in practice. 

**Mobile Transaction Authentication Number (mTAN)** is an off-device method of generating one-time passwords (OTPs) **specifically created for financial transactions**. It is commonly employed by banks as an **additional layer of protection** to verify the identity of the person attempting to initiate a payment. 

At the start of the transaction process, a **TAN (a single-use code of 6-8 characters)** is generated and sent to the user's mobile phone **via SMS or a dedicated banking app**. This TAN must then be **supplied on the transaction page** to validate the payment attempt. Thus, even if a cybercriminal gets their hands on your password, they still **won't be able to conduct payments on your behalf** without this additional verification code. 

While mTAN offers **robust protection against identity theft and fraudulent transactions**, it still ranks low on our list due to its **vulnerability against various forms of [2FA bypass attacks](https://zitadel.com/blog/2fa-bypass-attacks)** (such as [SIM-Jacking](https://zitadel.com/blog/2fa-bypass-attacks#:~:text=6.%20SIM-Jacking,of%20the%20hacker) and social engineering), as well as its inconvenient user experience. To migate some of the security concerns around mTAN, **ZITADEL chose not to support SMS-reliant OTPs** - instead, with the **upcoming login API**, your login flow can be extended easily with external 2FA providers that offer SMS TAN.

### 3. One-Time-Passwords (OTP) Mobile 

**Mobile OTPs** operate very similarly to the previously mentioned mTAN authentication method. Like TAN codes, Mobile OTPs are **single-use, off-device numerals typically used as an additional authentication factor** to ensure a safer login process. The main differences are that this method is not explicitly intended for financial transactions and that the **OTP is sent to the user via an authentication application of the user's choice (f.e. Authy or Google Authenticator)**. 

Take signing into a social media account as an example. With Mobile OTP enabled on your profile, you will be **prompted to navigate to your authentication app after you enter your login credentials**. The app will display a **6-digit code (the OTP)** which must be entered on the social media login page as part of the **secondary authentication process**. Akin to the case of mTAN, the requirement of an additional OTP **safeguards your profile from unwanted access**, even if your password might have been compromised. Moreover, the code refreshes after a short amount of time (30-60s), making the old one automatically useless after its expiration. 

Despite their many similarities, **mobile OTP typically suprasses mTAN in terms of safety**, because the code is generated on the user’s device and **does not rely on a SIM card**. Accordingly, a potential SIM-jacking attack will still not get the attacker closer to accessing the user’s account. Despite this perk, mobile OTP is **still subjectable to the [Duplicate-Generator attack](https://zitadel.com/blog/2fa-bypass-attacks#:~:text=5.%20Duplicate-Generator,time-password%20(OTP).), as well as social engineering attacks (f.e. [phishing](https://zitadel.com/blog/social-engineering#:~:text=1.%20Phishing%20and,card%20suspension%20notice.))**. 

### 2. FIDO Universal 2nd Factor (U2F)

**FIDO (Fast Identity Online)** describes a **set of open protocols based on public key cryptography**. It was developed by the **FIDO Alliance**, consisting of technology giants such as Google, Visa and Microsoft, to create **convenient but highly-secure standards for authentication**. As a groundbreaking domain- and hardware-bound open solution, FIDO has established itself as a **widely used and highly recommended identity and access management (IAM) practice**. Since its founding in 2012, the FIDO Alliance has published three specifications: **Universal 2nd Factor (U2F), Universal Authentication Framework (UAF), and [FIDO2](https://fidoalliance.org/fido2/)**. 

The **U2F protocol** was designed to be used as a **second-factor token-based authentication system** in addition to the first factor (the user's password) to enhance the security of the traditional password-based login method. Accordingly, U2F prompts users to present **two pieces of evidence to validate their identity**:

* **A knowledge factor**: The user's password or PIN
* **A possession factor**: Security devices known as U2F tokens that can be embodied in various form factors, such as a USB device (f.e. Yubikey), a Near Field Communication (NFC) device, or a BlueTooth LE device.

With U2F's extra layer of security added to the authentication process, the service can **simplify its passwords without compromising security**. Furthermore, its reliance on **public key cryptography and physical security keys** makes it far safer and **less vulnerable to 2FA bypass attempts** than the previously stated OTP-based approaches. 

Evidently, even the earlier installations of FIDO (such as U2F) can already be considered **highly innovative and secure** (especially compared to traditional login methods). However, the constant evolution of security standards inevitably led to the need for a newer protocol that **carries on the benefits of its predecessors while also bringing new advancements (such as higher UX)**. This is where FIDO2 comes into play.

### 1. FIDO2 Passkeys

**FIDO2 (aka FIDO 2.0)** is the latest set of specifications published by FIDO, with the primary pursuit of **entirely eradicating password use on the internet**. Ever since its release, FIDO2 has been widely supported by technological giants such as Google, Microsoft and Apple. Unlike previous specifications, this new protocol comprises the **W3C Web Authentication (WebAuthn)** specification and corresponding **Client-to-Authenticator Protocols (CTAP)** from the FIDO Alliance. This innovative collaboration provides users with **[passwordless](https://zitadel.com/blog/passwordless), second-factor and multi-factor user experiences** with **embedded** (such as biometric authentication or PINs) or **external authenticators** (such as physical security keys, mobile devices, wearables, etc.). 

The release of FIDO2 also marked the introduction of **Passkeys - passwordless credentials that allow users to access their FIDO sign-in information across multiple devices**, including new ones, without needing to enroll each device separately for every account. The WebAuthn API of FIDO2 enables the **standardization of passkeys**, which also provides **libraries for their use in both the front- and back-end**. 

As the highest-rated entry on our list, **FIDO2 Passkeys surpass every other authentication technique available on ZITADEL** both in terms of security and UX. To sum up why, here are some of **the key reasons why users should enable FIDO2 Passkeys as their preferred authentication method:**

* Passwordless systems are **less susceptible to phishing and other cyberattacks** due to their complete waiver of passwords.
* Login via Passkeys is **less time-consuming and does not rely on the user's memory**. 
* WebAuthn provides FIDO2 with a **standardized framework that improves compatibility** and ensures **consistent security practices across different platforms**.
* Passkeys ensure a **fast and convenient recovery process** by allowing users to enroll and de-enroll devices via **their service provider's cloud backup**.
* Passkeys enable users to **authenticate seamlessly across different vendor platforms**, ensuring a **convenient UX and cost-effectiveness**.

## In Conclusion

The main goal of the **Identity and Access Management (IAM) solution ZITADEL** is to ensure that the end-users of your application can **verify their virtual identities in the safest and most convenient way possible**. To make this goal a reality, we highly recommend that **they either set up a FIDO U2F token or a FIDO2 Passkey as their preferred authentication method**. 


This article showcases ZITADEL's five implementable authentication methods ranked from worst to best regarding security and user experience (UX).

5 Authentication Methods at ZITADEL - Ranked from Least to Most Secure


The most distinct feature of ZITADEL is how you can structure your identity architecture around Users and Organizations.
Whether you're building a customer-facing app and looking for a CIAM solution to handle authentication for you, or trying to offer hundreds of business customers and partners the ability to use their identities and delegate permission management to your customer, it's worth understanding how you can build your solution scenarios with ZITADEL.

This article aims to give you an overview of the overall concepts used and explain the most important points, so you can get started with enough knowledge at hand.

## Organization vs. Instance

The highest level of separation in ZITADEL is an [instance](/docs/concepts/structure/instance).
ZITADEL allows you to operate multiple virtual instances on the same system with the same database.

Access across instances is not possible.
Instances can be managed with the [System API](/docs/apis/introduction#system) as described in this [Guide](/docs/guides/integrate/access-zitadel-system-api).

<figure>
  <img
    src="/blog/2023-04-15-multi-tenancy-with-organizations-12.png"
    width="80%"
    alt="Two instances with each organizations in it using the same database"
  />
  <figcaption>Two isolated instances with individual organization structures using the same database</figcaption>
</figure>

It's important to note that some settings can only be set per instance, specifically:

- SMTP Service: All emails within the instance will be sent from this service
- Custom Domain: You can define under which domains (eg, `login.demo-vendor.com`) the ZITADEL service can be accessed

> **Note:**  
> At the time of writing, token lifetimes can only be configured on instance level.
> There is no technical limitation, but it is an outstanding [feature](https://github.com/zitadel/zitadel/issues/5219).

Instances provide one form of multi-tenancy in ZITADEL, where each tenant is completely isolated.
However, most scenarios might involve some form of self-service or fluidity between the different tenants to reduce administrative overhead.
These cases most often leverage our organization model within a single instance.

## Organizations

Think of an organization as a way to group users and set shared policies (our term for "settings") such as login, security, branding.
Organizations also allow you to manage applications centrally and grant other organizations to them.

### User Management

In the following diagram, you can see two organizations.
One for a service provider, for example a software vendor or project like you, and one for a customer organization.
Each organization has its own users.

![](/blog/2023-04-15-multi-tenancy-with-organizations-01.png)

[Users](https://zitadel.com/docs/concepts/structure/users) will always belong to one [organization](https://zitadel.com/docs/concepts/structure/organizations).
You have a high degree of flexibility when it comes to how you structure your identities.
You can put all your users in one organization and use ZITADEL like any other CIAM.
Just as well, you might want to split users in different groups.
For example, you may want to separate your customers from your team members or employee identities.
Alternatively, you may want to keep each of your customers' identities in its own organization.

<figure>
  <img
    src="/blog/2023-04-15-multi-tenancy-with-organizations-02.png"
    width="100%"
    alt="List of organizations of an instance"
  />
  <figcaption>List of organizations of an instance</figcaption>
</figure>

### Managing Roles and Applications

Each organization can have multiple [projects](https://zitadel.com/docs/concepts/structure/projects), and each project can contain multiple applications with a shared set of [roles](https://zitadel.com/docs/concepts/structure/projects#roles).
Think of a project like a "shared security context" for [applications](https://zitadel.com/docs/concepts/structure/applications) that logically belong together.
For example, a web app and mobile app, or a front-end and back-end of the same service.

In the example below, you can see that the service provider has the two projects **Portal** and **Data Cube**.
**Portal** would serve as customer portal for all customers to access their services and contains roles like **reader**, **admin**, **support:read**, **support:write** to grant users a different set of permissions.

<figure>
  <img
    src="/blog/2023-04-15-multi-tenancy-with-organizations-03.png"
    width="100%"
    alt="Multiple projects in one organization"
  />
  <figcaption>Multiple projects in one organization</figcaption>
</figure>

The service **Data Cube** may require different roles, such as **analyst**, **engineer**, **manager**, and could be granted to customer organizations based on a subscription option.

<figure>
  <img
    src="/blog/2023-04-15-multi-tenancy-with-organizations-04.png"
    width="100%"
    alt="Multiple applications in a project that share the same roles"
  />
  <figcaption>Multiple applications in a project that share the same roles</figcaption>
</figure>

### Login and Access Policies

For each organization, you can define individual policies around login, access, branding, and domains.

With the [security settings](https://zitadel.com/docs/concepts/structure/policies) per organization, it is possible, for example, to configure different external identity providers per customer organization.
You could configure one organization to allow login with a customers' AzureAD tenant, while configuring another customer organization to login with a local password and 2FA.

At this point, you might ask yourself: How to redirect users to the correct domain?

One way would be to setup [domain discovery](/docs/guides/solution-scenarios/domain-discovery) on your instance to route users according to their login name or email address.
Another option is to send a reserved scope with your auth request to enforce the organization's policies on the login.

## Delegated Access Management

> **Broken Authorization is a Major Risk to Web Applications**  
> The highest-ranking risk for web-applications is [Broken Access Control](https://owasp.org/Top10/A01_2021-Broken_Access_Control/), according to the [OWASP Top 10](https://owasp.org/Top10/).
> Providing a secure way of authorization in a multi-tenancy setup, while allowing for self-service, is difficult to achieve.
> We built ZITADEL, based on our experience, from the ground up with this particular challenge in mind, so you don't have to worry about it.

Now we get to the more interesting part of the setup.

How can you give other organizations access to a project and its applications?
And once the organization has access, how can they give permissions to their users?

That is where the unique delegated access management feature of ZITADEL comes into play.

Instead of copying over all projects or applications to each customer organization, which would result in quite some overhead to manage at scale, you can [grant projects](https://zitadel.com/docs/concepts/structure/granted_projects) to other organizations.

### Project Grants

With a [project grant](https://zitadel.com/docs/concepts/structure/granted_projects), you can select a subset of roles that the receiving organization can assign to their users.

![](/blog/2023-04-15-multi-tenancy-with-organizations-01.png)

As an example you could keep certain administrative roles for support or developers in your own organization.
Or you might want to only grant a role once the customer has subscribed to a feature in your application.

Think of a project grant as creating a link to the project.
You don't need to manage the applications within each organization, but only grant them to other organizations.
The receiving organization will see an incoming projects as a "Granted Project" and cannot change the project and that project's applications directly, but only use the roles to authorize their own users.

In the following screen, you can see that the project **Portal**, which is owned by the organization **Demo-Vendor**, has two active grants to **Demo-Customer** and **Demo-Customer2** respectively.

<figure>
  <img
    src="/blog/2023-04-15-multi-tenancy-with-organizations-05.png"
    width="100%"
    alt="Project grants from Demo-Vendor to customer organizations"
  />
  <figcaption>Project grants from the service provider Demo-Vendor to customer organizations</figcaption>
</figure>

The organization **Demo-Customer2** sees the granted project under the tab "Granted Projects". When clicking on it, you can't edit the project itself, like how Managers of **Demo-Vendor** could, but only assign the granted roles to your users, given you have the permissions.
We will discuss Managers in the next section.

<figure>
  <img src="/blog/2023-04-15-multi-tenancy-with-organizations-06.png" width="100%" alt="List of granted projects" />
  <figcaption>Granted (incoming) projects in the customer organization</figcaption>
</figure>

You can always get an overview of all authorizations under the **Authorizations** tab in the ZITADEL console.
Here you can also see that the user **Eric Employee** has the role **reader** in the granted Project **Portal**.

<figure>
  <img
    src="/blog/2023-04-15-multi-tenancy-with-organizations-07.png"
    width="100%"
    alt="Authorizations can be given to granted projects"
  />
  <figcaption>Authorizations can be given to granted projects</figcaption>
</figure>

When **Demo-Vendor** removes the project grant to an organization, then all authorizations will be removed as well.

### Delegate Self-Service to Customers

[Managers](https://zitadel.com/docs/concepts/structure/managers) allow you to let organizations self-assign roles to users, thus authorizing them to access the granted Project.
Managers are an internal role and permission concept of ZITADEL.
The concept offers many use cases for delegating [self-service](https://zitadel.com/docs/concepts/features/selfservice) to users in other organizations.

<figure>
  <img
    src="/blog/2023-04-15-multi-tenancy-with-organizations-08.png"
    width="100%"
    alt="Machine and human users can take on different manager memberships"
  />
  <figcaption>Machine and human users can take on different manager memberships</figcaption>
</figure>

For example, in a SaaS application, you might assign a manager role to the first user in a new organization.
With that, this user could, for example, configure SSO and assign roles to their team members.

Integrate self-service features for managers into your application by using our APIs, or start your POC by letting users configure their organization via the branded console.
The console will always be scoped to the manager permissions of a user.

## Authorize Users Outside of Your Organization

But wait... there is more 🤯! We've already learned that you can isolate tenants with [instances](/docs/concepts/structure/instance). We also saw how create a multi-tenancy setup with [organizations](https://zitadel.com/docs/concepts/structure/organizations) that allow for grouping users, individual security policies (such as configurations of external identity providers), and delegating access management using [managers](https://zitadel.com/docs/concepts/structure/managers).

So, how about a situation where one of your customers wants to invite users from another of your partners/customers and give them access to their organization's resources?

Here are a few of use cases for this:

- Accounting: You offer an accounting platform for SMEs. Your customers are the SMEs but also fiduciaries and accounting firms as partners that manage the finances of the SMEs. Each SME and partner would have their own organization with their own users and either log in with their business account or with a local account on your platform. The SMEs can grant access to their organization by inviting users of partners and authorize them with specific roles as part of your organization, so that they get access to the data they need.
- Education: You are an EdTech provider for different schools. You have an organization per school with teachers and students as users. Some teachers are, however, also responsible for conducting classes at another school. You can create a user grant for these teachers to the secondary placement. Note: in case the accounts would not be managed by one primary school, you would anyway set up two accounts and manage the logic to select an account in your application.
- Healthcare: A university hospital is sponsoring a platform for cross-hospital knowledge and case exchange (e.g., scientific boards). Instead of creating separate accounts for each participant in your organization, you could create an organization for each participating organization. Then let users sign in with their existing accounts from their hospital and create a user grant, such that they get access to your project where you assign roles for the digital collaboration workspace.

Technically this would look similar as indicated in the next diagram.
As service provider, for example for a time-keeping app, ACME organization owns a project with the roles **Accountant** and **Developer**.
The project is granted to both Alpha and Beta where Beta has assigned Bob already the role **Developer**.

Alice from Alpha is the accountant of Beta and requires regular access to the time-keeping app to do her job.
Beta can create a User Grant for Alice and assign her the role **Accountant** in self-service.
Alice can now access the Project as external user of Beta with her role.

ACME must implement the application permissions for such cases within their application.

<figure>
  <img
    src="/blog/2023-04-15-multi-tenancy-with-organizations-10.png"
    width="100%"
    alt="User Grants allow you to grant access to users managed by another organization and assign them roles"
  />
  <figcaption>
    User grants allow you to grant access to users managed by another organization and assign them roles
  </figcaption>
</figure>

This feature goes beyond a traditional multi-tenancy approach by also allowing delegated access management tenant-to-tenant via user grants.
You can integrate such external user management with ease in your application using our [APIs](/docs/category/apis/resources/auth/user-authorizations-grants).

Here is how you can set up a user grant via the ZITADEL console:

1. Go to **Authorizations** and press **N** (or click the button) to create a new authorization.
2. Under the text field **Loginname** there is a hint "If you want to grant a user of another organization click here".
3. Click on **click here** to switch to external users.
4. Enter the loginname of the external user and select a granted or owned project.
5. Go to the next screen and add the roles to the user.

<figure>
  <img
    src="/blog/2023-04-15-multi-tenancy-with-organizations-11.png"
    width="100%"
    alt="Create a user grant in the console"
  />
  <figcaption>Create a user grant in the console</figcaption>
</figure>

The user will be now visible under Authorizations.
You can't view or edit the user's details, since it is being managed by another organization.
But you can change the associated roles like for internal users.

## Conclusion

We went through several aspects of multi-tenancy of ZITADEL:

- Use instances to completely separate tenants
- Use organizations to group users, security policies, and other settings
- Manage your project centrally in one organization and grant the project to other organizations
- By assigning a Manager, a receiving organization can give permissions to their users via the incoming project
- You can also invite external users from another organization to your organization and give them permission to your owned or granted projects

In conclusion, ZITADEL has a high degree of flexibility to fit your use case. ZITADEL's multi-tenancy features provide a comprehensive solution for managing users, projects, and security policies across multiple tenants, ensuring a secure and efficient environment for your applications and services.
Check out our [Solution Scenarios](/docs/guides/solution-scenarios/introduction) and try out the [Sample B2B application](https://github.com/zitadel/zitadel-nextjs-b2b) for more hands-on learning.


This article explains the most important concepts on how you can structure your multi-tenancy identity architecture with organizations.

Multi-Tenancy and Delegated Access Management with Organizations


## Initial Position
From user feedback and our own observation, we got quite a few hints that instance owners get lost after their initial onboarding with what to do next. So we knew that we had to do something about it. Our first thought was an informational email with further instructions and provided links, but it was clear to us that this wasn’t a proper solution and was a bit outdated. So we thought of a more direct “in-app” approach that is more interactive.

## What We Wanted to Improve
After some research, we came to the conclusion that the home page in the console is where most of our customers “get stranded” and that provides the most visibility to our new guiding. We want to give the user some guidance on what could be helpful to set up next and what is missing for a successful authentication experience. We want the instance owner to feel more engaged in the setup process.

<figure>
  <img
    src="/blog/2023-04-11-onboarding-process-01.png"
    width="100%"
    alt="Onboarding Process"
  />
  <figcaption>Figure 1 - Our old start page with the focus on customizable general shortcuts and some helpful links like docs</figcaption>
</figure>


## Our New Approach
To achieve this new interactive setup for our customers, we thought of a small “to-do list” with some gentle gamification to keep them engaged. And we wanted the home page of the console to focus on these next steps rather than the general shortcuts the old page had.

So we added a progress bar that is prominently visible on the start page so the instance owner can see how far in they are with the setup. This progress bar will also show in a smaller form in the header at all times. When the setup is complete (as far as the guidance goes) this progress bar will be removed.

<figure>
  <img
    src="/blog/2023-04-11-onboarding-process-02.png"
    width="50%"
    alt="Onboarding Process"
  />
  <figcaption>Figure 2 - Progress bar as shown on the home page of the console</figcaption>
</figure>


These steps in the progress bar are shown on the start page as cards, declaring each step and with a short description of what it is about. Steps that are already done will be faded out and checked so the user can see at first glance which steps are done and which are still to do.

<figure>
  <img
    src="/blog/2023-04-11-onboarding-process-03.png"
    width="50%"
    alt="Onboarding Process"
  />
  <figcaption>Figure 3 - Progress steps cards as shown on the start page</figcaption>
</figure>


Furthermore, by hovering over the small progress bar, the user can instantly overview this list in a more compact form anywhere in the ZITADEL console with direct links to the according subpage for the task. Here the user can also opt out of this guidance if they don’t want that additional information.

<figure>
  <img
    src="/blog/2023-04-11-onboarding-process-04.png"
    width="40%"
    alt="Onboarding Process"
  />
  <figcaption>Figure 4 - The overview panel is accessible from the small progress bar in the header bar, including an opt-out option</figcaption>
</figure>


This all results in the new start page that looks like this: 

<figure>
  <img
    src="/blog/2023-04-11-onboarding-process-05.png"
    width="100%"
    alt="Onboarding Process"
  />
  <figcaption>Figure 5 - The new and improved home page of ZITADEL console</figcaption>
</figure>


You can see that we still provide the help links but put them a bit further down the list. Note that once the progress is completed, the progress steps will convert to normal shortcuts and provide the user with direct links to the most used pages.

## Conclusion
With these changes, we hope to provide a smoother setup process, especially for new customers. But this should also come in handy for our more veteran ZITADEL users, as it gives them a handy checklist for what they might haven’t set up yet. 

We are constantly trying to enhance the user experience and if you have any suggestions on how to improve our workflow or ZITADEL in general, feel free to let us know.


This post explains what's new in ZITADEL's user onboarding process.

ZITADEL's New and Improved User Onboarding Process


## Introduction

With the release of [ZITADEL v2.22.0](https://github.com/zitadel/zitadel/releases/tag/v2.22.0), we announced the availability of Flat Role Claims. This feature enables you to easily integrate user roles into your tokens through customizable actions, providing greater flexibility and control over the claims in your access tokens, ID tokens, and user info.

Flat role claims are a way of representing user roles in a simplified and easily readable format. Instead of using nested structures or complex JSON objects, flat role claims utilize a list of strings where each string represents a user's role, often combined with additional identifiers, such as organization or project IDs. For example, a flat role claim could look like this: 

`["{orgId}:{role}", "{orgId}:{role}", ...]`

Before supporting flat role claims, ZITADEL represented role claims using a JSON object structure. While this format provided all the necessary information, it could be difficult to parse and integrate with certain third-party tools and applications that expected roles in a simpler format.

ZITADEL switched to supporting flat role claims to provide more flexibility and ease of integration with various tools and systems. For example, better compatibility with tools such as [OAuth2 Proxy](https://github.com/oauth2-proxy/oauth2-proxy) or using ZITADEL as an OIDC provider with [Hashicorp Vault](https://www.vaultproject.io/). Flat role claims are easier to read, parse, and work with, reducing the complexity of managing user roles without having to recreate the role information as user metadata. 

## A Practical Use Case

Let’s consider that an organization has a project management application that integrates with ZITADEL for user authentication. The project management application requires user roles and permissions to be included in the ID token as custom claims in a specific format.

The organization uses ZITADEL's built-in roles and permissions for its users. However, the project management application expects user roles in a flat format (e.g., `orgId:role`), while ZITADEL provides roles as a JSON object.

To address this requirement,  ZITADEL allows the organization to reformat the user roles into the required flat format and include them as custom claims in the ID token. This way, the project management application can receive the ID token containing the custom claim and use it to grant the user access based on their roles and permissions.

By supporting flat role claims, ZITADEL enables the organization to customize the ID token to meet the specific requirements of their third-party application.

## How to Configure Flat Role Claims in ZITADEL

### Terminology: Actions, Triggers, and Flows
[ZITADEL Actions](https://zitadel.com/docs/apis/actions/introduction) is a key feature to extend the functionality of ZITADEL and continuously improve upon ZITADEL features and expand use cases. Actions allow you to create extended functionality by writing scripts using JavaScript. For example, the script of an action called doSomething should have a function called doSomething and would look like this:

```
function doSomething(ctx, api){
   // read from ctx and manipulate with api
}
```

[Trigger Types](https://zitadel.com/docs/apis/actions/introduction#trigger-types) define the point during the execution of a request. Each trigger defines which readable information (`ctx`) and mutual properties (`api`) are passed into the called function as well as which libraries are available for the function. 

[Flows](https://zitadel.com/docs/apis/actions/introduction#flows) are the links between an action and a trigger type. Currently, ZITADEL provides the following flows:

- Internal Authentication
- External Authentication
- Complement Token

The **Complement Token Flow** is the process flow of token creation and token introspection. The flow contains the following triggers: 

**Pre Userinfo creation**: This is the trigger that is called before `userinfo` is set in the token or response, and takes in the parameters (`ctx` and `api`) and their respective fields, such as `claims`, `getUser()`, `user`, `getMetadata()`, `grants`, and `setClaim()`.

**Pre access token creation**: This is the trigger that is called before claims are set in the access token and the token type is set to JWT. It takes in the parameters (`ctx` and `api`) and their fields, including `claims`, `getUser()`, `user, getMetadata()`, `grants`, `setClaim()`, and `appendLogIntoClaims()`.

You can define custom claims within the Complement Token Flow. You can create an action and use roles from ZITADEL to add a claim to your tokens/userinfo in the format of your choice. 

### A Sample Action
This code snippet is a JavaScript function named`flatRoles` that sets additional role claims in a token, combining the project ID and role name as a key-value pair. The function is part of the Complement token flow and is triggered during Pre Userinfo creation and Pre access token creation.

``` JavaScript

/**
 * Sets the roles as an additional claim in the token with roles as the value and project as the key.
 *
 * The role claims of the token look like the following:
 *
 * // Added by the code below
 * "my:zitadel:grants": ["{projectId}:{roleName}", "{projectId}:{roleName}", ...],
 * // added automatically
 * "urn:zitadel:iam:org:project:roles": {
 *   "asdf": {
 *     "201982826478953724": "zitadel.localhost"
 *   }
 * }
 *
 * Flow: Complement token, Triggers: Pre Userinfo creation, Pre access token creation
 *
 * @param ctx
 * @param api
 */
function flatRoles(ctx, api) {
    if (ctx.v1.user.grants === undefined || ctx.v1.user.grants.count == 0) {
        return;
    }
    let grants = [];
    ctx.v1.user.grants.grants.forEach(claim => {
        claim.roles.forEach(role => {
            grants.push(claim.projectId + ':' + role)
        })
    })
    api.v1.claims.setClaim('my:zitadel:grants', grants)
}

```


1. The function accepts two parameters: `ctx` and `api`.
  - `ctx`: Contains context information about the user, including user grants.
  - `api`: Provides methods to interact with ZITADEL's API.
2. The function checks if `ctx.v1.user.grants` is undefined or has no elements; if true, it returns immediately, as there's nothing to process.
3. If there are user grants, the function initializes an empty array called `grants`, which will be used to store the flattened roles.
4. Next, it iterates through the user's grants and roles, concatenating the `projectId` and `role` with a colon (":") separator, and then pushes the result into the `grants` array.
5. Finally, the function sets a new claim called `my:zitadel:grants` with the content of the grants array using the `api.v1.claims.setClaim()` method.
6. When the function is executed, it adds the flat role claims to the token in the format `{projectId}:{roleName}`.

### Enable the Action in ZITADEL
To use this flat role claim feature in ZITADEL, follow these steps:

1. Log in to the ZITADEL management console and navigate to the project where you want to use the flat role claim feature. Click on **Actions**. 

<figure>
  <img
    src=" /blog/2023-03-30-custom-claims-01.png"
    width="100%"
    alt="Custom Claims."
  />
</figure>

2. Click on the **New** button to create a new action.

<figure>
  <img
    src=" /blog/2023-03-30-custom-claims-02.png"
    width="100%"
    alt="Custom Claims."
  />
</figure>

3. In the **Create an Action** section, give the action the same name as the function name, e.g., flatRoles. In the script field, paste the provided flatRoles code. Click on **Add**.

<figure>
  <img
    src=" /blog/2023-03-30-custom-claims-03.png"
    width="100%"
    alt="Custom Claims."
  />
</figure>

4. The **flatRoles** action will now be listed. 

<figure>
  <img
    src="/blog/2023-03-30-custom-claims-04.png"
    width="100%"
    alt="Custom Claims."
  />
</figure>

5. Next, we must select a **Flow Type**. Select **Complement Token** from the dropdown. 

<figure>
  <img
    src="/blog/2023-03-30-custom-claims-05.png"
    width="100%"
    alt="Custom Claims."
  />
</figure>

6. Next, you must choose a trigger. Click **Add trigger**.  

<figure>
  <img
    src="/blog/2023-03-30-custom-claims-06.png"
    width="100%"
    alt="Custom Claims."
  />
</figure>


7. Select **Pre Userinfo creation** as the **Trigger Type** and select **flatRoles** as the associated action. 

<figure>
  <img
    src="/blog/2023-03-30-custom-claims-07.png"
    width="100%"
    alt="Custom Claims."
  />
</figure>

8. You will see the **Pre Userinfo creation** trigger listed. 

<figure>
  <img
    src="/blog/2023-03-30-custom-claims-08.png"
    width="100%"
    alt="Custom Claims."
  />
</figure>


9. Follow the same steps to add the  **Pre access token creation** trigger and add **flatRoles** as the associated action. Afterwards, you will see both triggers listed as shown below: 

<figure>
  <img
    src="/blog/2023-03-30-custom-claims-09.png"
    width="100%"
    alt="Custom Claims."
  />
</figure>

10. Don't forget to select the **Assert Roles on Authentication** checkbox on the Project dashboard and click **Save**. 

<figure>
  <img
    src="/blog/2023-03-30-custom-claims-10.png"
    width="100%"
    alt="Custom Claims."
  />
</figure>

Now, when a user logs in and receives an ID token, the action will be executed, transforming the user roles into the required flat format and adding them as a custom claim with the key `my:zitadel:grants`. This custom claim can then be used by third-party applications to manage user access based on their roles and permissions in the desired format.

## Closing Remarks

In summary, supporting custom role claims in ZITADEL enhances the user experience by providing more customization options, better compatibility with third-party tools, and improved adaptability to different use cases

Thanks for reading!

ZITADEL is FREE! So, go on and [try it out](https://zitadel.com/signin). 


This article demonstrates how to add custom claims to your tokens through customizable actions.

Configuring Custom Claims in ZITADEL

This follow-up article demonstrates how to use ZITADEL to secure APIs and how back-end applications can access these protected APIs.

API Access and Token Introspection with OpenId Connect in ZITADEL


## New Features

The [ZITADEL OIDC library](https://github.com/zitadel/oidc) is where we implement the OpenID Connect standard in a Go library. It is used by ZITADEL and our clients. Whenever we need to support additional parts of the specification or OAuth2-related RFCs in ZITADEL, the first step is to implement it in our OIDC library. In short, the following features lay important groundwork for later support in ZITADEL.

### Dynamic Issuer

The framework can now set the issuer of tokens based on the hostname in the request. This is an improvement for multi-domain deployments. The feature was already in use for almost a year in ZITADEL and now is finally merged to be available to a wider audience.

### Token Exchange (RFC 8693)

We have received a significant contribution from the community that completes the implementation of the Token Exchange flow. Big shoutout to [lefelys](https://github.com/lefelys) for his pull request!

### Device Authorization (RFC 8628)

The OIDC framework now offers device authorization flow as defined by RFC 8628. This feature allows authorization of devices that cannot open a browser for users to authenticate themselves. Instead, a code is generated and displayed along with a URL where the user should point their browser to authenticate and authorize the device.

## Test Coverage

We had a big bump in coverage after a community contribution from [muir](https://github.com/muir) (Thanks!!) last November from 12% to almost 40%. Ever since then,  we have been steadily growing coverage. And today we have crossed the 50% line!

## Refactoring

We have started refactoring some core parts of the library. For v2, we have started to simplify the usage of the collection of token claims, user info, and introspection response. These used to be interfaces, with their implementations as private structs and tons of getter/setter methods. In the case of custom claims a `map[string]interface{}` had to be used, with awkward type assertions.

Now we export those structs, and by the use of generics/type parameters, it is now possible to replace the OIDC types with custom types as decoding/unmarshal targets, essentially allowing type-safe access to additional fields. Don’t worry, the standard types still carry a map if you need the flexibility.

## The Future

We aim to continue to refactor parts of the library. We are looking to get rid of redundant code. Also, we are working hard to replace stale dependencies such as gorilla/mux. And we have some priorities planned, such as improving error handling and logging. In essence, the [issue list](https://github.com/zitadel/oidc/issues?q=is%3Aissue+is%3Aopen+label%3Aenhancement) gives a good overview of what we are planning to do.

Given the fact that we have some major refactoring in the pipeline, it might not be long until we tag a v3. However, we didn’t want to postpone the release of v2, as we had a split development target for almost a year now. Instead, we’ve decided to be more proactive when it comes to increasing to a new major version while refactoring.

## Conclusion

The release notes for this and the upcoming releases can always be found on the [Github releases page](https://github.com/zitadel/oidc/releases). We are forever grateful for PRs sent in by our [Contributors](https://github.com/zitadel/oidc/graphs/contributors).


We have released version 2.0 of our OpenID Connect library, which includes many changes.

OIDC Version 2.0 Release

Last month, we said goodbye to the old year by reflecting on the **[many ways ZITADEL improved in 2022](https://zitadel.com/blog/best-of-zitadel-2022)**. Now that that is all said and done, it is time to **take a peek at the horizon**.

As a company that always strives for innovation in an ever-changing digital world, our biggest goal is to **provide our customers with the best possible user experience and the most value for their money** by constantly keeping ZITADEL up to date. This article showcases **the most significant features [scheduled to launch in the year 2023](https://zitadel.com/roadmap).**

## 1. Configurable Social/Enterprise Login Templates

After lengthy anticipation, **the new [social login](https://zitadel.com/blog/social-logins) options for ZITADEL** are just around the corner!

Social login, and more generally [identity brokering](https://zitadel.com/blog/what-is-an-identity-broker), is an authentication method that utilizes users’ pre-existing **social media identities to facilitate sign-ups** on third-party platforms. This popular alternative for the standard username-password login **does not require completing a registration form**, thus saving you valuable time and the hassle of remembering yet another password.

Whereas thus far, ZITADEL has exclusively supported OIDC-compliant identity providers, this restriction will soon be completely removed to provide a **wider range of options** - ensuring that both you and your customers can **seamlessly log in using your preferred social media profiles**.

Our new identity providers include:

* Google
* Github
* Gitlab
* and Azure AD

## 2﻿. Fully customizable Login UI

Ever since the launch of the platform, ZITADEL has enabled businesses to **seamlessly authenticate their users with a customizable [hosted login and registration page](https://zitadel.com/docs/guides/solution-scenarios/b2c#hosted-login)**: a fixed authentication endpoint that is secure by default. Whereas so far, you have had the option to disable the hosted registration page and **build your onboarding process from scratch**, a **custom login API was not yet implemented**. While the hosted login page offers various personalization options for branding purposes - such as colors, logo, and typography – the range of potential alterations is ultimately limited. 

Within the course of 2023, we would like to give businesses with specific needs the option to **replace the default hosted login page and build their [own login User Interface (UI)](https://github.com/zitadel/zitadel/issues/5015).** While this alternative will completely lift the limitation on the scope of aesthetic personalization, the core functionality of the custom login UI will remain unchanged to satisfy the highest security standards.

## 3. New Event Audit Log – Filters and Threat Detection

Thousands of **modifications are performed on ZITADEL instances every minute**, ranging from minor adjustments like adding a user nickname to prominent ones like an improved password policy. Every crucial information about these so-called “events” is **collected and stored in a log** - including the event’s date, description, and the user who initiated it.

With the introduction of the **new ZITADEL event audit log**, every action and modification performed on an organization will be **accessible and reviewable directly in the console or via our APIs**. Users may utilize a variety of filters to quickly and efficiently sort and find specific events. Having this report readily available will not only **facilitate general surveillance,** but also **troubleshooting security investigations, and compliance reporting**. Should you detect a suspicious event (such as unauthorized access), the audit log allows you to flag and report it right away.

Furthermore, the log will provide developers the opportunity to **create an action using custom code** for each possible ZITADEL event, enabling them to construct unique workflows.

## 4. Client Credentials as JWT & PAT Alternative

In the year 2022, ZITADEL’s service accounts could **authenticate by using a JSON Web Token (JWT)-Profile** or directly generate a **[Personal Access Token (PAT)](https://zitadel.com/blog/new-personal-access-token)** for authorization. While the former method is undoubtedly the more secure path to take, it is not universally supported. As a response, PATs were introduced to authenticate service users that have trouble integrating their accounts with JWT Profile.

Since both of these options come with their respective weaknesses in terms of compatibility and usability, we have decided to implement a **3rd alternative to authenticate service accounts: [Client Credential Grant](https://www.rfc-editor.org/rfc/rfc6749#section-4.4)**. By using this grant type, clients are enabled to request an access token to **retrieve protected resources under their control** or those of **another resource owner** that have been previously arranged with the authorization server.

## 5. Device Authorization Grant

While obtaining an access token should be quick and simple, **authenticating a device that does not have an easy way to enter text** can be frustrating at best and impossible at worst.

In the following months, ZITADEL aims to fix this inconvenience by **implementing [Device Authorization Grant](https://github.com/zitadel/oidc/issues/264)**. This extension **allows input-constrained devices,** such as smart TVs and printers, as well as **devices with no browser**, **to obtain an access token** with the help of a secondary device.

## 6. More ZITADEL Cloud Data Regions

When it comes to **data processing**, there is no "one size fits all"; different businesses tend to have their main customer base, offices, and headquarters at distinct locations. The country or **region where an institution will store and process your organization’s data should be carefully considered** to prevent latency problems and possible data loss.

Since the latest version of ZITADEL Cloud launched in 2022, the platform’s **SaaS service offers [three data regionality options](/docs/legal/service-description/cloud-service-description#data-location)** to choose from: Switzerland, Global, and GDPR-compliant regions. To facilitate our customers' decision in choosing the right data center, the latter two options **automatically select three housing regions** based on the locality of end-users.

While this automation comes as a big help to many, in 2023, we would also like **to give users more directly selectable data locations to choose from**, such as “Germany”, “Japan” or “Canada”. Which locations are ultimately chosen will rely on both user demand and if they adhere to ZITADEL's privacy standards.

Do you have a data region you would like to suggest? **Please feel free to share your ideas on [Github](https://github.com/zitadel/zitadel) or by contacting us directly.**

## 7. Improved Developer Experience

Since documentation is essential for offering **additional information about a platform's functionality**, ensuring that the guides are coherent and easily comprehensible should be a top priority.

In the following months, ZITADEL is planning a **complete rewrite of its [documentation](https://zitadel.com/docs)** that will additionally **provide a more efficient way to explore our APIs** and **more example applications in your language of choice** to facilitate your onboarding process.

But documentation is not enough to offer a great experience and have a pre-configured ZITADEL platform that is ready to use within minutes. This year, we are implementing some **essential tweaks** that will make this **onboarding process faster and easier than ever,** including:

* New users will be offered additional assistance with the first relevant steps.
* Fewer steps will be needed to create a new instance.
* Relevant settings will be easier to find with the help of an improved console.

 An **improved documentation, quickstarts and an easy to understand user interface** make it overall faster and easier to use ZITADEL. Not only to get started quickly, but also to make it your own.

## 8. More Trust

We are happy that our **community of open source and ZITADEL Cloud users is thriving** and many discussions and questions happen in the open on Github or our [Chat](http://zitadel.com/chat). However, there are situations when **disclosing some private information is necessary to resolve a problem**. So far, our customers have only been able to do so via email. Our goal is to provide a **more seamless private and secure support channel** to share relevant information directly with our engineers to get help as easily as possible.

**Transparency and Support** are keystones for us in building trust. This year we want to prove that we are **fully committed to safeguarding your data**. Not only are we **[GDPR-compliant](https://zitadel.com/gdpr)**, and conduct regular security audits of our platform and **[publish the results on our website](https://zitadel.com/blog/tags/pentest)**, but we strive to certify our information security standards through an external audit this year. With that, we can provide you with certifications for the highest compliance requirements.

This article showcases the most significant features scheduled to launch in the year 2023.

All posts/ #features