Building Secure Authorization: A Practical Guide to Token Management in Zitadel

Authorization sits at the heart of every secure application. While authentication answers "who are you?", authorization tackles the more complex question: "what are you allowed to do or see?" For identity and security professionals, getting authorization right means balancing security with usability—ensuring legitimate users can access what they need while keeping unauthorized access at bay.

This challenge becomes more complex in modern distributed architectures. Where applications likely span across multiple services, APIs, and user types. Each component needs to make authorization decisions quickly and accurately, often with limited context about the user's broader permissions and organizational relationships.

Zitadel approaches this challenge through a structured authorization model built around projects, roles, and audience-restricted tokens. The goal is creating a foundation that scales with your organization while maintaining security principles that actually work in practice.

Understanding Zitadel's Authorization Architecture

Authorization in Zitadel starts with understanding how permissions flow through your system. Rather than treating authorization as an afterthought, Zitadel structures it around clear organizational concepts that map to how your business actually operates.

Projects serve as logical containers for related applications and services. Think of a project as a business domain or product area where multiple applications need to share authorization context. For example, your customer portal, mobile app, and backend APIs for customer management might all belong to the same project because they operate on the same business logic and user permissions. Google Drive is another example of this. Whether accessing Google Drive via mobile, web, or desktop app, your authorization remains consistent. All three share the same access but are distinct clients..

Roles define what users can do within those projects. You might have heard this referred to as RBAC or Role-Based Access Control. The important thing to know is these roles aren't just labels—they represent specific permissions that your applications can check when making authorization decisions. The key insight here is that roles belong to projects, not individual applications, which means you can maintain consistent permissions across all the applications in a business domain.

Authorizations connect users to roles within specific projects. This three-way relationship between users, roles, and projects gives you fine-grained control over who can do what, where. You can also create external user grants, which allow users from other organizations to access specific roles in your projects—essential for B2B scenarios where partner organizations need limited access to your systems.

This structure solves a common problem in enterprise authorization: the tension between centralized control and distributed decision-making. Your security team can define roles and projects centrally, while individual applications can make authorization decisions locally using the tokens they receive.

How Scopes and Claims Create Authorization Context

When applications request access or ID tokens, they use scopes to specify what information they need about the user. The real purpose here is building the authorization context that your backend services need to make security decisions.

Zitadel translates specific scopes into claims within the token. Claims carry the authorization information your applications need, including role assignments, organizational membership, and project-specific permissions. You can then approach this in 1 of 2 ways:

1. JSON Web Tokens (JWTs): This approach means your backend services don't need to make additional calls to determine what a user can do—the authorization information travels with the token.
2. Opaque Tokens: This approach means additional calls are needed since a lookup is required for associated claims retrieval.

Each approach has advantages and disadvantages. You can find out more about both in our post JWT vs. Opaque Tokens.

Custom claims extend this concept further. Using Zitadel Actions, you can add business-specific information to tokens based on your authorization logic.This is known as attribute-based access control (ABAC). ABAC manages access to resources through the use of attributes and might include department codes, security clearance levels, or dynamic permissions based on current context like time of day or geographic location.

The practical benefit here is reduced latency and improved reliability. Your applications can make authorization decisions locally using information in the token, rather than making additional network calls to authorization services for every protected resource access.

Controlling Token Audience for Better Security

One of the most important security practices in token-based authorization is audience restriction. Without proper audience controls, a token intended for one application might be accepted by another, creating unintended access paths that attackers can exploit.

Zitadel addresses this through reserved scopes that explicitly define token audiences. When requesting a token, you can include the scope urn:zitadel:iam:org:project:id:{projectId}:aud to restrict that token to a specific project. The resulting token will include the project ID in its audience claim, ensuring it can only be used with applications that belong to that project.

This audience restriction works alongside two additional authentication controls that strengthen your security posture. The "Check authorization on Authentication" setting ensures users can only authenticate if they have at least one role assigned to their account. This prevents unauthorized users from obtaining tokens at all, even if they have valid credentials.

The "Check for Project on Authentication" setting adds another layer by verifying that the user's organization has access to the project they're trying to authenticate against. This is particularly valuable in multi-tenant scenarios where you need to ensure users from one organization can't access another organization's resources.

These controls work together to create defense in depth: unauthorized users can't get tokens, authorized users get tokens restricted to appropriate audiences, and your applications can verify those audience restrictions before granting access.

Implementing Token Validation in Your Backend

Your backend applications play a crucial role in the authorization chain. Even with properly scoped and audience-restricted tokens, your applications need to validate those tokens correctly to maintain security.

The first validation step is checking the token's audience claim. Every token your application receives should include your project ID in its audience claim. If it doesn't, reject the token immediately. This prevents tokens issued for other applications or projects from being used against your services.

Token introspection provides a second validation mechanism that also retrieves detailed token information. The introspection endpoint allows your backend to verify token validity and extract claims in a single API call. Please note, this only works with client authorization:

curl --request POST \
  --url {your_domain}/oauth/v2/introspect \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer \
  --data client_assertion=dxQxghCaq1MOUXnvuR... \
  --data token=D1FEN5o1SVkEvcX_sG4ce0521sFpgrfF4...

This approach gives you both security validation and authorization information in one step. The introspection response includes all the claims your application needs to make authorization decisions, including role assignments and custom claims you've configured.

The introspection pattern also handles token lifecycle management automatically. Revoked tokens will fail introspection, expired tokens are rejected, and you get current authorization information even if user permissions have changed since the token was issued.

Building Authorization That Scales

Effective authorization requires creating systems that remain manageable as your organization grows. Zitadel's project-based approach scales naturally because it mirrors how businesses actually organize work and permissions.

As you add new applications, they inherit the authorization structure of their project. New roles apply across all applications in a project automatically. User permissions remain consistent whether they're accessing your web portal, mobile app, or API directly.

This consistency reduces the administrative overhead that often makes authorization systems difficult to maintain. Security teams can focus on defining business-appropriate roles and projects, while development teams can trust that the authorization information in tokens accurately reflects current user permissions.

The audience restriction and validation patterns also scale effectively because they push authorization decisions to the edge—your applications can make security decisions locally using information in tokens, rather than creating bottlenecks with centralized authorization services.

Next Steps for Your Authorization Strategy

Getting authorization right requires both technical implementation and organizational clarity about roles and permissions. Start by mapping your current applications to logical projects, then define roles that reflect real business permissions rather than technical implementation details.

Zitadel provides the technical foundation for scalable authorization, but the success of your implementation depends on thoughtful role design and consistent application of audience restrictions and token validation patterns.

Ready to implement robust authorization in your applications? Explore Zitadel's authorization features hands-on with our cloud account (for free). You can set up projects, define roles, and test token flows in minutes, giving you practical experience with the concepts covered in this guide.

For organizations evaluating identity infrastructure solutions, our team can help you design an authorization strategy that fits your specific requirements. Contact us to discuss how Zitadel's authorization model can simplify security while supporting your business objectives.