Introduction

All documentations are under active work and subject to change soon!

The documentation for ZITADEL comprises two major subject areas:

  1. Manuals for users, support organisations and administrators.
  2. Technical resources for developers and integrators.

Please be reminded that ZITADEL is open source — and so is the documentation. Should you happen to stumble over an incorrectness, a spelling mistake, a hard-to-understand text passage, please don’t hesitate to leave a comment or propose a corresponding change.

Principles

ZITADEL engineering and design principles

  • Be transparent about your decisions
  • Embrace stateless application design
  • System of records is the event store
  • Everything else needs to be able to be regenerated
  • Try not so solve complex problems outside of the IAM Domain
  • Use a scalable storage for the event store and read models
  • Try to be idempotent whenever possible
  • Reduce necessity of external systems or dependencies as much as possible
  • Embrace automation
  • Design API first
  • Optimize all components for day-two operations
  • Use only opensource projects with permissive licenses
  • Don't roll your own crypto algorithm
  • Embrace (industry) standard as much as possible
  • Make use of platform features
  • Be able to run with a CDN and WAF
  • Releases utilized sematic versioning and release whenever feasible

Architecture

TBD

OpenID Connect 1.0 & OAuth 2.0

Endpoints and Domains

This chapter documents the OpenID Connect 1.0 and OAuth 2.0 features provided by ZITADEL.

Under normal circumstances ZITADEL need four domain names to operate properly.

Domain Name Example Description
issuer issuer.zitadel.ch Provides the OpenID Connect 1.0 Discovery Endpoint
api api.zitadel.ch All ZITADEL API's are located under this domain see API explanation for details
login accounts.zitadel.ch The accounts.* page provides server renderer pages like login and register and as well the authorization_endpoint for OpenID Connect
console console.zitadel.ch With the console.* domain we serve the assets for the management gui

OpenID Connect 1.0 Discovery

The OpenID Connect Discovery Endpoint is located with the issuer domain. For example with zitadel.ch this would be the domain issuer.zitadel.ch. This would give us https://issuer.zitadel.ch/.well-known/openid-configuration.

Link to spec. OpenID Connect Discovery 1.0 incorporating errata set 1

authorization_endpoint

https://accounts.zitadel.ch/oauth/v2/authorize

The authorization_endpoint is located with the login page, due to the need of accessing the same cookie domain

token_endpoint

https://api.zitadel.ch/oauth/v2/token

userinfo_endpoint

https://api.zitadel.ch/oauth/v2/userinfo

end_session_endpoint

https://accounts.zitadel.ch/oauth/v2/endsession

The end_session_endpoint is located with the login page, due to the need of accessing the same cookie domain

jwks_uri

https://api.zitadel.ch/oauth/v2/keys

Be aware that these keys can be rotated without any prior notice. We will however make sure that a proper kid is set with each key!

OAuth 2.0 Metadata

ZITADEL does not provide a OAuth 2.0 Metadata endpoint but instead provides a OpenID Connect Discovery Endpoint.

Scopes

How scopes work

TODO describe

Reserved Scopes

In addition to the standard compliant scopes we utilize the following scopes.

Scope Description Example
urn:zitadel:iam:org:project:role:{rolename} By using this scope a client can request the claim urn:zitadel:iam:roles:rolename} to be asserted when possible. As an alternative approach you can enable all roles to be asserted from the project a client belongs to. See details here urn:zitadel:iam:org:project:role:user
urn:zitadel:iam:org:domain:primary:{domainname} When requesting this scope ZITADEL will enforce that the user is member of the selected organisation. If the organisation does not exist a failure is displayed urn:zitadel:iam:org:domain:primary:acme.ch
urn:zitadel:iam:role:{rolename}

Claims

TODO describe

Reserved Claims

Claims Description Example
urn:zitadel:iam:org:domain:primary:{domainname} {"urn:zitadel:iam:org:domain:primary": "acme.ch"}
urn:zitadel:iam:org:project:roles:{rolename} {"urn:zitadel:iam:org:project:roles": [ {"user": {"id1": "acme.zitade.ch", "id2": "caos.ch"} } ] }
urn:zitadel:iam:roles:{rolename}

Grant Types

For a list of supported or unsupported Grant Types please have a look at the table below.

Grant Type Supported
Authorization Code yes
Authorization Code with PKCE yes
Implicit yes
Resource Owner Password Credentials no
Client Credentials yes
Device Authorization under consideration
Refresh Token work in progress
JSON Web Token (JWT) Profile partially
Security Assertion Markup Language (SAML) 2.0 Profile no
Token Exchange work in progress

Authorization Code

Link to spec. The OAuth 2.0 Authorization Framework Section 1.3.1

Proof Key for Code Exchange

Link to spec. Proof Key for Code Exchange by OAuth Public Clients

Implicit

Link to spec. The OAuth 2.0 Authorization Framework Section 1.3.2

Client Credentials

Link to spec. The OAuth 2.0 Authorization Framework Section 1.3.4

Refresh Token

Link to spec. The OAuth 2.0 Authorization Framework Section 1.5

JSON Web Token (JWT) Profile

Link to spec. JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants

Token Exchange

Link to spec. OAuth 2.0 Token Exchange

Device Authorization

Link to spec. OAuth 2.0 Device Authorization Grant

Not Supported Grant Types

Resource Owner Password Credentials

Due to growing security concern we do not support this grant type. With OAuth 2.1 it looks like this grant will be removed.

Link to spec. OThe OAuth 2.0 Authorization Framework Section 1.3.3

Security Assertion Markup Language (SAML) 2.0 Profile

Link to spec. Security Assertion Markup Language (SAML) 2.0 Profile for OAuth 2.0 Client Authentication and Authorization Grants