TheArchive/zitadel
1
0
Fork 0
mirror of https://github.com/zitadel/zitadel.git synced 2025-10-20 21:39:18 +00:00
Code Issues Packages Projects Releases Wiki Activity

chore(documentation): documentation and manuals for ZITADEL (#710)

Browse Source 
* chore: cleanup old docs folder

* remove docs path trigger

* wip docs structure

* chore: ignore site changes in ci

* add manuals route

* new structure

* structure

* Use correct title

* remove trigger for code scan for static site generator

* change names

* add lorem ipsum to test styling

* use h3 to deeplink

* add site to dependabot

* lint readme.md

* remove not needed file

* ignore site on pull request code scan

* add initial contrib

* Minor correction

* Added section Developer & Integration

* Changed link list layout, added labels, added translations

* Added missing <li> tags

* Added correct link to section Developer & Integration

* Fixing list style

* Overhauling description texts and translations

* outline

* teaser go

* outline

* wip

* rework

* wip

* wip

* wip

* hop

* wip

* first draft for "administrate" done

* init outline

* fix deploy step

* lint

* commit wip

* commit wip

* md lint

* Link

* fix: path to edit (#711)

* wip

* wip

* wip

* what are...

* use only features

* wip docs

* Update 00-user.en.md

* project

* uppercase en

* wip

* wip

* wip

* policies rework

* improve text

* correct typo

* update readme

* correct styling

* add link to docs guides

* make the linter happy

* rename

* wip

* move api to own file

* correct links and lint

* wip roles and integration

* add pkce

* reduce padding and margin

* wip scope and claims

* wip claim & scopes

* make the linter happy

* insert links where possible

* wip

* wip roles & providers

* Update README.md

* Update 00-user.en.md

* minor text improvements

* use master branch to deploy

* use proper ci file

* Apply suggestions from code review

Co-authored-by: Fabi <38692350+fgerschwiler@users.noreply.github.com>

Co-authored-by: Matthias M. Schneider <mati@matimax.info>
Co-authored-by: Max Peintner <max@caos.ch>
Co-authored-by: Fabi <38692350+fgerschwiler@users.noreply.github.com>
This commit is contained in:
Florian Forster
2020-10-16 14:13:02 +02:00
committed by GitHub
parent b1d61afc8f
commit ef3b7482cd
70 changed files with 1143 additions and 221 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
site/docs/documentation/00-introduction.de.md Normal file
View File

@@ -0,0 +1,3 @@
---
title: Einführung
---

13
site/docs/documentation/00-introduction.en.md Normal file
View File

@@ -0,0 +1,13 @@
---
title: Introduction
description: This is the place for all things ZITADEL. Whether you are a developer, an integrator or a user of ZITADEL, then the following pages are written for your referral.
---
> 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.

20
site/docs/documentation/01-priciples.de.md Normal file
View File

@@ -0,0 +1,20 @@
---
title: Prinzipien
---
- Seien Sie bei Ihren Entscheidungen transparent
- Zustandsloses Anwendungsdesign
- Das System der Aufzeichnungen ist der Ereignisspeicher
- Alles andere muss regeneriert werden können
- Versuchen Sie nicht, komplexe Probleme außerhalb des IAM-Bereichs zu lösen
- Verwenden Sie skalierbaren Speicher für den Ereignisspeicher und die Abfragemodelle
- Versuchen Sie, wenn immer möglich idempotent zu sein
- Reduzieren Sie die Notwendigkeit von System- oder externen Abhängigkeiten so weit wie möglich
- Automatisierung einbeziehen
- Zuerst die Design-API
- Optimieren Sie alle Komponenten für den Betrieb am zweiten Tag
- Verwenden Sie nur Open-Source-Projekte mit permissiven Lizenzen
- Rollen Sie nicht Ihre eigene Krypto
- Standard so weit wie möglich einbeziehen
- Nutzen Sie die Funktionen der Plattform
- Mit einem CDN und einer WAF laufen können

23
site/docs/documentation/01-priciples.en.md Normal file
View File

@@ -0,0 +1,23 @@
---
title: 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

5
site/docs/documentation/02-architecture.de.md Normal file
View File

@@ -0,0 +1,5 @@
---
title: Architektur
---
> TBD

5
site/docs/documentation/02-architecture.en.md Normal file
View File

@@ -0,0 +1,5 @@
---
title: Architecture
---
> TBD

5
site/docs/documentation/03-openidoauth.de.md Normal file
View File

@@ -0,0 +1,5 @@
---
title: OpenID Connect 1.0 & OAuth 2.0
---
> TBD

142
site/docs/documentation/03-openidoauth.en.md Normal file
View File

@@ -0,0 +1,142 @@
---
title: OpenID Connect 1.0 & OAuth 2.0
---
### Endpoints and Domains
This chapter documents the [OpenID Connect 1.0](https://openid.net/connect/) and [OAuth 2.0](https://oauth.net/2/) 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](#openid-connect-10-discovery) |
| api | api.zitadel.ch | All ZITADEL API's are located under this domain see [API explanation](develop#APIs) 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](zitadel.ch) this would be the domain [issuer.zitadel.ch](issuer.zitadel.ch). This would give us [https://issuer.zitadel.ch/.well-known/openid-configuration](https://issuer.zitadel.ch/.well-known/openid-configuration).
**Link to spec.** [OpenID Connect Discovery 1.0 incorporating errata set 1](https://openid.net/specs/openid-connect-discovery-1_0.html)
#### authorization_endpoint
[https://accounts.zitadel.ch/oauth/v2/authorize](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](https://api.zitadel.ch/oauth/v2/token)
#### userinfo_endpoint
[https://api.zitadel.ch/oauth/v2/userinfo](https://api.zitadel.ch/oauth/v2/userinfo)
#### end_session_endpoint
[https://accounts.zitadel.ch/oauth/v2/endsession](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](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](#openid-connect-10-discovery).
### 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](administrate#clients) can request the claim urn:zitadel:iam:roles:rolename} to be asserted when possible. As an alternative approach you can enable all [roles](administrate#Roles) to be asserted from the [project](administrate#projects) a [client](administrate#clients) belongs to. See details [here](administrate#RBAC_Settings) | 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](https://tools.ietf.org/html/rfc6749#section-1.3.1)
#### Proof Key for Code Exchange
**Link to spec.** [Proof Key for Code Exchange by OAuth Public Clients](https://tools.ietf.org/html/rfc7636)
#### Implicit
**Link to spec.** [The OAuth 2.0 Authorization Framework Section 1.3.2](https://tools.ietf.org/html/rfc6749#section-1.3.2)
#### Client Credentials
**Link to spec.** [The OAuth 2.0 Authorization Framework Section 1.3.4](https://tools.ietf.org/html/rfc6749#section-1.3.4)
#### Refresh Token
**Link to spec.** [The OAuth 2.0 Authorization Framework Section 1.5](https://tools.ietf.org/html/rfc6749#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](https://tools.ietf.org/html/rfc7523)
#### Token Exchange
**Link to spec.** [OAuth 2.0 Token Exchange](https://tools.ietf.org/html/rfc8693)
### Device Authorization
**Link to spec.** [OAuth 2.0 Device Authorization Grant](https://tools.ietf.org/html/rfc8628)
### 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](https://tools.ietf.org/html/rfc6749#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](https://tools.ietf.org/html/rfc7522)