Applications

import ThemedImage from "@/components/docusaurus/themed-image"; import AuthType from "../../integrate/application/_auth-type.mdx"; import ReviewConfig from "../../integrate/application/_review-config.mdx"; import AppType from "./_application-types.mdx";

What is an application?

Applications are the entry point to your Project Overview . Users either login into one of your applications (Frontend) and interact with them directly, or use one of your APIs (Backend).

All applications within a project share the same Roles and Role Assignments. This means you define a role once (e.g., admin) on the Project level, and it applies across all your web, mobile, and API applications.

To access your applications, navigate to your Project in the Management Console and select your application.

Create an Application

To add an application to your project, click on the New button and select your application type.

Application Types

ZITADEL offers five application types to cover different architectural patterns:

<AppType components={props.components} />

The first three options (Web, Native, and User Agent) require user interaction. The fourth option (API) is for machine-to-machine communication without direct user interaction.

Depending on the app type, there are small differences in the possible settings. To get a good understanding about user profiles and recommended flows, read the Recommended Flows Guide.

Web

Web applications are server-side rendered applications that users interact with.

• Examples: Applications using Java (Spring/Thymeleaf), .NET (Razor), PHP, Python (Django/Flask), or enabling SSO in tools like GitLab.
• NextJS: A NextJS app is typically a Web Application because it can execute server-side code (SSR/API routes) to keep secrets safe.
• Authentication: Uses Authorization Code Flow (PKCE recommended) with a Client Secret.

<AuthType components={props.components} appType="web" />

Native

Native Applications are installed on a thin client, such as a smartphone or desktop computer.

• Examples: Android Apps, iOS Apps, Desktop Apps (Electron, Tauri).
• Authentication: Uses the Key file generated by ZITADEL to authenticate or Authorization Code Flow with PKCE (for user login).

<AuthType components={props.components} appType="native" />

User Agent

User Agent Applications are executed entirely in the web browser (Client-Side).

• Examples: Single Page Applications (SPA) built with React, Angular, Vue, or Svelte that do not have a backend server.
• Authentication: Uses Authorization Code Flow with PKCE (implicit flow is supported but not recommended).

<AuthType components={props.components} appType="user-agent" />

API

These are applications without human interaction, accessed by other applications or services (Machine-to-Machine).

• Examples: Background workers, CLIs, Daemons, Microservices.
• Authentication: Uses Client Credentials (JWT Profile or Basic Auth) or Private Key JWT.

<AuthType components={props.components} appType="api" />

SAML

If your application doesn't support the OIDC standard but supports SAML 2.0, choose this type. SAML is an XML-based open standard for exchanging authentication and authorization data.

After creating a SAML app, you can either:

1. Add a link to a SAML metadata file.
2. Upload the metadata XML file directly.

You can find example settings for SAML 2.0 in our integrate services guides.

Settings

Redirect URIs

App Types with user interaction (Web, Native, and User Agent) require Redirect URIs. These are the allowed URLs where ZITADEL sends the user after a successful login.

• Security: ZITADEL strictly checks these URIs during the login process. They must match exactly what is defined in your application code.
• Protocols: Native applications can use custom protocols (e.g., myapp://) instead of http/https.

Development Mode

If you are developing locally or need to redirect users to a non-secure protocol (other than https://), you must enable Development mode. When disabled, ZITADEL enforces strict security and only allows https.

Glob Patterns: Development mode allows the use of glob patterns in Redirect URIs for flexibility:

Special Terms	Meaning
*	Matches any sequence of non-path-separators.
/**/	Matches zero or more directories.
?	Matches any single non-path-separator character.
[class]	Matches any single character against a class of characters (e.g., [a-z]).
{alt1,...}	Matches a sequence if one of the comma-separated alternatives matches.

<Callout type="note"> Double stars (`**`) should appear surrounded by path separators (e.g., `/**/`). A pattern like `path/to/**.txt` is invalid; use `path/to/**/*.txt`. </Callout> <Callout type="tip"> IPv6 When IPv6 URIs are used as redirects in development mode, square brackets must be escaped as they are special terms for globs. Example: `http://\[::1\]:80` </Callout>

Review Settings

<ReviewConfig components={props.components} authType="code" />

Application Settings

After creating an application, you can modify its settings.

• Auth Method: You can switch authentication methods (e.g., from Basic to Private Key JWT) via the toggle or dropdowns.
• OIDC Compliance: The Management Console checks if your settings are OIDC compliant and shows tasks for completion if anything is missing.

<Callout type="caution"> You **cannot** change the Application Type (e.g., from Web to Native) after creation. You must delete and recreate the application. </Callout>

Token Settings

In the Token Settings section, you can customize the tokens issued for this application:

• Token Type: Switch between Bearer Token (Opaque) and JWT.
• Content: Check options to include User Roles and User Information inside the ID Token.
• ClockSkew: Optionally set a time buffer added to the expiration time of the issued token to handle server time differences.

Additional Origins

If your application makes requests from domains other than the Redirect URI (e.g., a Javascript app fetching data from an API on a different domain), you can specify them here to configure CORS (Cross-Origin Resource Sharing).

Security Considerations

Ensure the management of application settings is limited to authorized users only.

• Use Administrator roles to limit permissions for your users to make changes to your applications.
• When granting projects to other organizations, the receiving organization cannot see or change the application settings. They can only assign roles.

References

• Recommended OIDC Flows