TheArchive/zitadel
1
0
Fork 0
mirror of https://github.com/zitadel/zitadel.git synced 2025-08-11 19:07:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat(operator): make running ZITADEL easy (#1562)

Browse Source 
* docs: describe crd mode

* docs: fix links

* docs: fix commands and crdb resources

* feat: add configure command

* chore: use latest ORBOS

* chore: use latest ORBOS

* docs: start gitops docs

* fix: compile

* chore: fix build script path

* chore: remove redundant prebuild

* chore: add configure.go

* docs: describe gitops mode

* docs: point template links to main branch

* docs: fix versions

* feat: initialize empty keys

* feat: reconfigure running ZITADEL

* docs: describe crd mode

* docs: fix links

* docs: fix commands and crdb resources

* feat: add configure command

* chore: use latest ORBOS

* chore: use latest ORBOS

* docs: start gitops docs

* fix: compile

* chore: fix build script path

* chore: remove redundant prebuild

* chore: add configure.go

* docs: describe gitops mode

* docs: point template links to main branch

* docs: fix versions

* feat: initialize empty keys

* feat: reconfigure running ZITADEL

* test: fix

* docs: keys are generated with configure

* docs: remove keys from template

* chore: pass compile time data

* chore: use latest ORBOS

* fix: when in-cluster, use in-cluster k8s client

* fix: try in-cluster config if kubeconfig is empty

* fix: reduce unneeded side effects for configure command

* docs: boom version

* chore: use latest ORBOS

* chore: use latest ORBOS

* initial commit

* inital changes

* commit WIP Information Architecture

* commit a working state

* add static assets and project

* add org and fix img names

* add plausible

* remove img

* change sidebar to easier mgmt

* add openid oauth and domains

* lint md

* quickstarts

* add auth flow

* identity brokering

* remove site

* fix broken links

* extend footer

* extend readme

* fix: styling

* fix: zitadel logo on index

* styling

* border

* fix: nav

* fix: nav

* fix: index

* fix: corrected zitadelctl examples

* fix: rename architecture to concepts

* fix: introductions

* fix: introductions

* fix: introductions

* docs: cli r/w secrets examples

* docs: finish ZITADEL Enterprise Cloud

* docs: mention ZITADEL Enterprise Cloud tier

* docs: comment configuration options

* docs: fix broken links

* docs: move some introduction texts around

* docs: twilio and email are mandatory

* docs: download latest binaries

Co-authored-by: Florian Forster <florian@caos.ch>
Co-authored-by: fabi <fabienne.gerschwiler@gmail.com>
Co-authored-by: Livio Amstutz <livio.a@gmail.com>
Co-authored-by: Stefan Benz <stefan@caos.ch>
This commit is contained in:
Elio Bischof
2021-04-22 18:43:34 +02:00
committed by GitHub
parent 06281b5ccb
commit c0878e4509
73 changed files with 1015 additions and 536 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
docs/docs/apis/admin.md Normal file
View File

@@ -0,0 +1,3 @@
---
title: Administration
---

3
docs/docs/apis/authn.md Normal file
View File

@@ -0,0 +1,3 @@
---
title: Authentication
---

3
docs/docs/apis/mgmt.md Normal file
View File

@@ -0,0 +1,3 @@
---
title: Management
---

2
docs/docs/apis/openidoauth/scopes.md
View File

@@ -23,7 +23,7 @@ In addition to the standard compliant scopes we utilize the following scopes.
| Scopes | Example | Description |
|:------------------------------------------------|:-------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| urn:zitadel:iam:org:project:role:{rolename} | `urn:zitadel:iam:org:project:role:user` | 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](../../guides/projects) a client belongs to. |
| urn:zitadel:iam:org:project:role:{rolename} | `urn:zitadel:iam:org:project:role:user` | 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](../../guides/usage/projects) a client belongs to. |
| urn:zitadel:iam:org:domain:primary:{domainname} | `urn:zitadel:iam:org:domain:primary:acme.ch` | When requesting this scope **ZITADEL** will enforce that the user is a member of the selected organization. If the organization does not exist a failure is displayed |
| urn:zitadel:iam:role:{rolename} | | |
| `urn:zitadel:iam:org:project:id:{projectid}:aud` | ZITADEL's Project id is `urn:zitadel:iam:org:project:id:69234237810729019:aud` | By adding this scope, the requested projectid will be added to the audience of the access and id token |

60
docs/docs/guides/installation/crd.md Normal file
View File

@@ -0,0 +1,60 @@
---
title: CRD Mode on an existing Kubernetes cluster
---
:::tip What I need
I'd like to see an automatically operated ZITADEL instance running on my own [Kubernetes](https://kubernetes.io/) cluster
:::
First, download the template configuration files [database.yml](./templates/crd/database.yml) and [zitadel.yml](./templates/crd/zitadel.yml). Then adjust the values in database.yml and zitadel.yml to match your environment. Especially the values for the domain, cluster DNS, storage class, email and Twilio are important.
```bash
# Download the zitadelctl binary
curl -s https://api.github.com/repos/caos/zitadel/releases/latest | grep "browser_download_url.*zitadelctl-$(uname | awk '{print tolower($0)}')-amd64" | cut -d '"' -f 4 | sudo wget -i - -O /usr/local/bin/zitadelctl && sudo chmod +x /usr/local/bin/zitadelctl && sudo chown $(id -u):$(id -g) /usr/local/bin/zitadelctl
sudo chmod +x /usr/local/bin/zitadelctl
sudo chown $(id -u):$(id -g) /usr/local/bin/zitadelctl
# Deploy the operators to the current-context of your ~/.kube/config file
zitadelctl takeoff
# As soon as the configuration is applied, the operators start their work
kubectl apply --filename ./database.yml,./zitadel.yml
# Write the encryption keys
wget https://raw.githubusercontent.com/caos/zitadel/main/site/docs/start/templates/example_keys && zitadelctl writesecret zitadel.keys.existing --file ./example_keys
# Write the Twiilio sender ID and auth token so that ZITADEL is able to send your users SMS.
TWILIO_SID=<My Twilio Sender ID>
TWILIO_AUTH_TOKEN=<My Twilio auth token>
zitadelctl writesecret zitadel.twiliosid.existing --value $SID
zitadelctl writesecret zitadel.twilioauthtoken.existing --value $TWILIO_AUTH_TOKEN
# Write your email relays app key so that ZITADEL is able to verify your users email addresses
EMAIL_APP_KEY=<My email relays app key>
zitadelctl writesecret zitadel.twilioauthtoken.existing --value $EMAIL_APP_KEY
# Enjoy watching the zitadel pods becoming ready
watch "kubectl --namespace caos-zitadel get pods"
```
ZITADEL needs [gRPC-Web](https://grpc.io/docs/platforms/web/basics/) for client-server communication, which the widely spread [NGINX Ingress Controller](https://kubernetes.github.io/ingress-nginx/) doesn't support out-of-the-box but Ambassador does. If you don't have an [Ambassador](https://www.getambassador.io/) running, we recommend you run it with our operator [BOOM](https://github.com/caos/orbos/blob/v4.0.0/docs/boom/boom.md).
Download the template configuration file [boom.yml](./templates/boom.yml). Then adjust the values in boom.yml to match your environment.
```bash
# Download the orbctl binary
curl -s https://api.github.com/repos/caos/orbos/releases/latest | grep "browser_download_url.*orbctl.$(uname).$(uname -m)" | cut -d '"' -f 4 | sudo wget -i - -O /usr/local/bin/orbctl
sudo chmod +x /usr/local/bin/orbctl
sudo chown $(id -u):$(id -g) /usr/local/bin/orbctl
# Deploy the operator to the current-context of your ~/.kube/config file
orbctl takeoff
# As soon as the configuration is applied, BOOM starts its work
kubectl apply --filename ./boom.yml
# Enjoy watching the ambassador pod becoming ready
watch "kubectl --namespace caos-system get pods"
```
Congratulations, you can accept traffic at four new ZITADEL [subdomains](/docs/apis/domains) now.

55
docs/docs/guides/installation/gitops.md Normal file
View File

@@ -0,0 +1,55 @@
---
title: GitOps Mode on an existing Kubernetes cluster
---
:::tip What I need
I'd like to have a reproducible ZITADEL environment and a pull-based configuration management for safe and comfortable day-two operations.
:::
First, copy the template files [database.yml](./templates/gitops/database.yml) and [zitadel.yml](./templates/gitops/zitadel.yml) to the root of a new git Repository. Then adjust the values in database.yml and zitadel.yml to match your environment. Especially the values for the domain, cluster DNS, storage class, email and Twilio are important.
Now open a terminal and execute the following commands.
```bash
# Download the zitadelctl binary
curl -s https://api.github.com/repos/caos/zitadel/releases/latest | grep "browser_download_url.*zitadelctl-$(uname | awk '{print tolower($0)}')-amd64" | cut -d '"' -f 4 | sudo wget -i - -O /usr/local/bin/zitadelctl && sudo chmod +x /usr/local/bin/zitadelctl && sudo chown $(id -u):$(id -g) /usr/local/bin/zitadelctl
sudo chmod +x /usr/local/bin/zitadelctl
sudo chown $(id -u):$(id -g) /usr/local/bin/zitadelctl
# Create an orb file at ${HOME}/.orb/config
MY_GIT_REPO="git@github.com:me/my-orb.git"
zitadelctl --gitops configure --repourl ${MY_GIT_REPO} --masterkey "$(openssl rand -base64 21)"
# Write the Twiilio sender ID and auth token so that ZITADEL is able to send your users SMS.
TWILIO_SID=<My Twilio Sender ID>
TWILIO_AUTH_TOKEN=<My Twilio auth token>
zitadelctl --gitops writesecret zitadel.twiliosid.encrypted --value $SID
zitadelctl --gitops writesecret zitadel.twilioauthtoken.encrypted --value $TWILIO_AUTH_TOKEN
# Write your email relays app key so that ZITADEL is able to verify your users email addresses
EMAIL_APP_KEY=<My email relays app key>
zitadelctl --gitops writesecret zitadel.twilioauthtoken.encrypted --value $EMAIL_APP_KEY
# Deploy the operators to the current-context of your ~/.kube/config file
zitadelctl --gitops takeoff
# Enjoy watching the zitadel pods becoming ready
watch "kubectl --namespace caos-zitadel get pods"
```
ZITADEL needs [gRPC-Web](https://grpc.io/docs/platforms/web/basics/) for client-server communication, which the widely spread [NGINX Ingress Controller](https://kubernetes.github.io/ingress-nginx/) doesn't support out-of-the-box but Ambassador does. If you don't have an [Ambassador](https://www.getambassador.io/) running, we recommend you run it with our operator [BOOM](https://github.com/caos/orbos/blob/v4.0.0/docs/boom/boom.md). Do so by adding the template [boom.yml](./templates/boom.yml) to the root of your Repository and execute the following commands.
```bash
# Download the orbctl binary
curl -s https://api.github.com/repos/caos/orbos/releases/latest | grep "browser_download_url.*orbctl.$(uname).$(uname -m)" | cut -d '"' -f 4 | sudo wget -i - -O /usr/local/bin/orbctl
sudo chmod +x /usr/local/bin/orbctl
sudo chown $(id -u):$(id -g) /usr/local/bin/orbctl
# Deploy the operator to the current-context of your ~/.kube/config file
orbctl --gitops takeoff
# Enjoy watching the ambassador pod becoming ready
watch "kubectl --namespace caos-system get pods"
```
Congratulations, you can accept traffic at four new ZITADEL [subdomains](/docs/apis/domains) now.

65
docs/docs/guides/installation/managed-dedicated-instance.md Normal file
View File

@@ -0,0 +1,65 @@
---
title: Managed Dedicated Instance
---
:::tip What I need
I'd like to simply use ZITADEL without having to take care of any operational tasks, yet keeping control over all its data.
:::
CAOS bootstraps and maintains a new ZITADEL instance just for you. This includes its underlying infrastructure with Kubernetes on top of it as well as monitoring tools and an API gateway. Contact us at <hi@zitadel.ch> for purchasing ZITADEL Enterprise Cloud.
# Prerequisites
Depending on the infrastructure provider you choose, you need to ensure some prerequisites.
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
<Tabs
defaultValue="gce"
values={[
{label: 'Google Compute Engine', value: 'gce'},
{label: 'Cloudscale', value: 'cs'},
{label: 'Static Provider', value: 'static'},
]}>
<TabItem value="gce">
<ul>
<li>
A JSON key for the infrastructure management to authenticate with a service account named orbiter-system assigned with the following roles
<ul>
<li>roles/compute.admin</li>
<li>roles/iap.tunnelResourceAccessor</li>
<li>roles/serviceusage.serviceUsageAdmin</li>
<li>roles/iam.serviceAccountUser</li>
</ul>
</li>
<li>
A JSON key for the backups storage to authenticate with a service account assigned with the role roles/storage.admin
<ul>
<li>roles/storage.admin</li>
</ul>
</li>
</ul>
</TabItem>
<TabItem value="cs">
<ul>
<li>A Cloudscale API token</li>
</ul>
</TabItem>
<TabItem value="static">
<ul>
<li>A List of available CentOS 7 machines with their IP addresses</li>
<li>A passwordless sudo user called orbiter on all machines</li>
<li>A Bootstrap SSH key to login as orbiter (are replaced by ORBITER)</li>
<li>A storage solution (contact us)</li>
</ul>
</TabItem>
</Tabs>
- We need you to point [four DNS subdomains](/docs/apis/domains) to the CAOS-generated IP address.
- For being able to send SMS, we need a Twilio sender name, SID and an auth token.
- ZITADEL also needs to connect to an email relay of your choice. We need the SMTP host, user and app key as well as the ZITADEL emails sender address and name.
If you give us a Cloudflare user, an API key and a user service key, we can also manage the DNS entries, wildcard certificate and the IP whitelisting automatically using the Cloudflare API.
Metrics, logs and traces are collected and monitored by CAOS.

9
docs/docs/guides/installation/orbos.md Normal file
View File

@@ -0,0 +1,9 @@
---
title: GitOps Mode on dedicated Kubernetes Clusters using ORBOS
---
:::tip What I need
I'd like to avoid platform failures caused by other applications or environments to have an impact on ZITADEL's production availability. So I run a near-identical dedicated GitOps managed Kubernetes cluster for each ZITADEL environment and region for proper isolation.
:::
> This will be added later on

11
docs/docs/guides/installation/shared-cloud.md Normal file
View File

@@ -0,0 +1,11 @@
---
title: Shared Cloud at zitadel.ch
---
:::tip What I need
I'd like to simply use ZITADEL without having to take care of any operational tasks.
:::
Just register your [Organization](../usage/organizations) at [zitadel.ch](https://console.zitadel.ch) and start by using [ZITADEL Free](https://zitadel.ch/pricing). You will immediately be able to integrate as many applications with as many users as you want. Serve your users multiple secure login methods for free.
[Jump](../usage/get-started) to the more detailed docs.

37
docs/docs/guides/installation/templates/boom.yml Normal file
View File

@@ -0,0 +1,37 @@
apiVersion: caos.ch/v1
kind: Boom
metadata:
name: boom
namespace: caos-system
spec:
boom:
version: v4.0.0
forceApply: true
currentStatePath: caos-internal/boom
apiGateway:
deploy: true
replicaCount: 1
proxyProtocol: true
metricCollection:
deploy: false
logCollection:
deploy: false
nodeMetricsExporter:
deploy: false
systemdMetricsExporter:
deploy: false
monitoring:
deploy: false
kubeMetricsExporter:
deploy: false
reconciling:
deploy: false
metricsPersisting:
deploy: false
logsPersisting:
deploy: false
metricsServer:
deploy: false
preApply:
deploy: false
folder: preapply

53
docs/docs/guides/installation/templates/crd/database.yml Normal file
View File

@@ -0,0 +1,53 @@
apiVersion: caos.ch/v1
kind: Database
metadata:
# This value must be database
name: database
# This value must be caos-system
namespace: caos-system
spec:
kind: databases.caos.ch/Orb
version: v0
spec:
# Print debug logs
verbose: false
# This is the version of the database operator deployment
version: 1.0.0
# If true, the operator overwrites its own deployment using the version above
selfReconciling: true
database:
kind: databases.caos.ch/CockroachDB
version: v0
spec:
# Resources for the database pods
resources:
limits:
memory: 8Gi
requests:
cpu: 1
memory: 6Gi
# Print debug logs
verbose: false
# Number of database pods
replicaCount: 1
# PVC storage request
storageCapacity: 368Gi
# PVC storage class
storageClass: fast
# This value must match with your cluster DNS
clusterDNS: cluster.local
# If empty, the database isn't backuped
backups: {}
# bucket:
# kind: databases.caos.ch/BucketBackup
# version: v0
# spec:
# # Print debug logs
# verbose: true
# # Schedule periodic backups
# cron: 0 * * * *
# # Specify the S3 bucket name
# bucket: dummy
# # The Google service accounts json key to use
# # Use the zitadelctl writesecret command
# serviceAccountJSON: {}

74
docs/docs/guides/installation/templates/crd/zitadel.yml Normal file
View File

@@ -0,0 +1,74 @@
apiVersion: caos.ch/v1
kind: Zitadel
metadata:
# This value must be zitadel
name: zitadel
# This value must be caos-system
namespace: caos-system
spec:
kind: zitadel.caos.ch/Orb
version: v0
spec:
# Print debug logs
verbose: false
# This is the version of the ZITADEL operator deployment and the ZITADEL binary deployment
version: 1.0.0
# If true, the operator overwrites its own deployment using the version above
selfReconciling: true
iam:
kind: zitadel.caos.ch/ZITADEL
version: v0
spec:
# Print debug logs
verbose: false
# If true, Kubernetes resources are applied forcefully
force: false
# Number of ZITADEL pods
replicaCount: 1
# ZITADEL deployment configuration
configuration:
cache:
maxAge: 12h
sharedMaxAge: 168h
shortMaxAge: 5m
shortSharedMaxAge: 15m
# Keys ZITADEL uses for symmetric encryption
secrets:
existingKeys:
key: keys
name: zitadel
userVerificationID: userverificationkey_1
otpVerificationID: otpverificationkey_1
oidcKeysID: oidckey_1
cookieID: cookiekey_1
csrfID: cookiekey_1
domainVerificationID: domainverificationkey_1
idpConfigVerificationID: idpconfigverificationkey_1
notifications:
# Email configuration is used for sending verification emails
email:
smtpHost: smtp.gmail.com:465
smtpUser: dummy
senderAddress: dummy
senderName: dummy
tls: true
# Twilio configuration is used for sending second factor SMS
twilio:
senderName: dummy
# If true, no emails or SMS are sent to users
debugMode: true
# ZITADEL pods log level
logLevel: info
dns:
# The main domain, the ZITADEL APIs should be published at
domain: myzitadel.ch
# The tls wildcard certificate used for publishing the zitadel endpoints over HTTPS
tlsSecret: tls-cert-wildcard
# The subdomains, the ZITADEL APIs should be published at
subdomains:
accounts: accounts
api: api
console: console
issuer: issuer
# This value must match with your cluster DNS
clusterdns: cluster.local

6
docs/docs/guides/installation/templates/example_keys Normal file
View File

@@ -0,0 +1,6 @@
otpverificationkey_1: passphrasewhichneedstobe32bytes!
cookiekey_1: passphrasewhichneedstobe32bytes!
domainverificationkey_1: passphrasewhichneedstobe32bytes!
idpconfigverificationkey_1: passphrasewhichneedstobe32bytes!
oidckey_1: passphrasewhichneedstobe32bytes!
userverificationkey_1: passphrasewhichneedstobe32bytes!

45
docs/docs/guides/installation/templates/gitops/database.yml Normal file
View File

@@ -0,0 +1,45 @@
kind: databases.caos.ch/Orb
version: v0
spec:
# Print debug logs
verbose: false
# This is the version of the database operator deployment
version: 1.0.0
# If true, the operator overwrites its own deployment using the version above
selfReconciling: true
database:
kind: databases.caos.ch/CockroachDB
version: v0
spec:
# Resources for the database pods
resources:
limits:
memory: 8Gi
requests:
cpu: 1
memory: 6Gi
# Print debug logs
verbose: false
# Number of database pods
replicaCount: 1
# PVC storage request
storageCapacity: 368Gi
# PVC storage class
storageClass: fast
# This value must match with your cluster DNS
clusterDNS: cluster.local
# If empty, the database isn't backuped
backups: {}
# bucket:
# kind: databases.caos.ch/BucketBackup
# version: v0
# spec:
# # Print debug logs
# verbose: true
# # Schedule periodic backups
# cron: 0 * * * *
# # Specify the S3 bucket name
# bucket: dummy
# # The Google service accounts json key to use
# # Use the zitadelctl writesecret command
# serviceAccountJSON: {}

54
docs/docs/guides/installation/templates/gitops/zitadel.yml Normal file
View File

@@ -0,0 +1,54 @@
kind: zitadel.caos.ch/Orb
version: v0
spec:
# Print debug logs
verbose: false
# This is the version of the ZITADEL operator deployment and the ZITADEL binary deployment
version: 1.0.0
# If true, the operator overwrites its own deployment using the version above
selfReconciling: true
iam:
kind: zitadel.caos.ch/ZITADEL
version: v0
spec:
# Print debug logs
verbose: false
# If true, Kubernetes resources are applied forcefully
force: false
# Number of zitadel pods
replicaCount: 1
# ZITADEL deployment configuration
configuration:
cache:
maxAge: 12h
sharedMaxAge: 168h
shortMaxAge: 5m
shortSharedMaxAge: 15m
notifications:
# Email configuration is used for sending verification emails
email:
smtpHost: smtp.gmail.com:465
smtpUser: dummy
senderAddress: dummy
senderName: dummy
tls: true
# Twilio configuration is used for sending second factor SMS
twilio:
senderName: dummy
# If true, no emails or SMS are sent to users
debugMode: true
# ZITADEL pods log level
logLevel: info
dns:
# The main domain, the ZITADEL APIs should be published at
domain: myzitadel.ch
# The tls wildcard certificate used for publishing the zitadel endpoints over HTTPS
tlsSecret: tls-cert-wildcard
# The subdomains, the ZITADEL APIs should be published at
subdomains:
accounts: accounts
api: api
console: console
issuer: issuer
# This value must match with your cluster DNS
clusterdns: cluster.local

6
docs/docs/guides/introduction.md
View File

@@ -2,4 +2,8 @@
title: Introduction
---
With our guides you will learn everything you need to know about specific topics. You get step-by-step instructions for certain tasks and have a knowledge check at the end.
With our guides you will learn everything you need to know about specific topics. You get step-by-step instructions for certain tasks and have a knowledge check at the end.
You can either use our cloud-instance [zitadel.ch](https://zitadel.ch) or deploy a dedicated **ZITADEL** instance. To get started, we recommend you to try out our free tier first. Jump directly to the [get started](./usage/get-started) docs.
When you are familiar with the ZITADEL usage, you can choose to stay on [zitadel.ch](./installation/shared-cloud), order your own [dedicated instance](./installation/shared-cloud) which is also availabe on premise, or install ZITADEL easily on your own using [Custom Kubernetes Resources](./installation/crd), [GitOps](./installation/gitops) or [ORBOS](./installation/orbos).

14
docs/docs/guides/access-zitadel-apis.md → docs/docs/guides/usage/access-zitadel-apis.md
View File

@@ -21,8 +21,8 @@ title: Access ZITADEL APIs
<td>Prerequisites</td>
<td>
<ul>
<li>Knowledge of <a href="/docs/guides/oauth-recommended-flows">Recommended Authorization Flows</a></li>
<li>Knowledge of <a href="/docs/guides/serviceusers">Service Users</a></li>
<li>Knowledge of <a href="/docs/guides/usage/oauth-recommended-flows">Recommended Authorization Flows</a></li>
<li>Knowledge of <a href="/docs/guides/usage/serviceusers">Service Users</a></li>
</ul>
</td>
</tr>
@@ -37,7 +37,7 @@ ZITADEL Managers are Users who have permission to manage ZITADEL itself. There a
- **Project Mangers**: In this level the user is able to manage a project.
- **Project Grant Manager**: The project grant manager is for projects, which are granted of another organisation.
On each level we have some different Roles. Here you can find more about the different roles: [ZITADEL Manager Roles](../manuals/admin-managers)
On each level we have some different Roles. Here you can find more about the different roles: [ZITADEL Manager Roles](../../manuals/admin-managers)
## Exercise: Add ORG_OWNER to Service User
@@ -61,7 +61,7 @@ This is already described in the [Service User](serviceusers), so make sure you
With the encoded JWT from the prior step, you will need to craft a POST request to ZITADEL's token endpoint:
To access the ZITADEL APIs you need the ZITADEL Project ID in the audience of your token.
This is possible by sending a custom scope for the audience. More about [Custom Scopes](../apis/openidoauth/scopes)
This is possible by sending a custom scope for the audience. More about [Custom Scopes](../../apis/openidoauth/scopes)
Use the scope `urn:zitadel:iam:org:project:id:{projectid}:aud` to include the project id in your audience
@@ -77,7 +77,7 @@ curl --request POST \
```
* `grant_type` must be set to `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`
* `scope` should contain any [Scopes](../apis/openidoauth/scopes) you want to include, but must include `openid`. For this example, please include `profile` and `email`
* `scope` should contain any [Scopes](../../apis/openidoauth/scopes) you want to include, but must include `openid`. For this example, please include `profile` and `email`
* `assertion` is the encoded value of the JWT that was signed with your private key from the prior step
You should receive a successful response with `access_token`, `token_type` and time to expiry in seconds as `expires_in`.
@@ -93,7 +93,7 @@ Content-Type: application/json
}
```
With this token you are allowed to access the [ZITADEL APIs](../apis/introduction) .
With this token you are allowed to access the [ZITADEL APIs](../../apis/introduction) .
## Knowledge Check
@@ -129,4 +129,4 @@ With this token you are allowed to access the [ZITADEL APIs](../apis/introductio
Where to go from here:
* [ZITADEL API Documentation](../apis/introduction)
* [ZITADEL API Documentation](../../apis/introduction)

14
docs/docs/guides/get-started.md → docs/docs/guides/usage/get-started.md
View File

@@ -7,15 +7,9 @@ Most applications need to know the identity of a user allowing to securely store
ZITADEL's authentication provides backend services, easy-to-use SDKs, and ready-made UI libraries to authenticate users in your application. It supports authentication using passwords and applies additional security with the help of a second factor, for example OTP, to ensure a safe and secure access.
It additionally leverages industry standards like OAuth 2.0 and OpenID Connect such that it can be easily integrated in your custom backend.
This documentation demonstrates the different installation methods of ZITADEL and provides a quick start guide on how to register your organization as well as creating your first project.
This provides a quick start guide on how to register your organization as well as creating your first project.
## Trying out ZITADEL
### Installation Types
You can either use our cloud-instance [zitadel.ch](https://zitadel.ch) or deploy a dedicated **ZITADEL** instance. To get started, we recommend you to try out our free tier first.
### Use cloud instance zitadel.ch
## Trying out ZITADEL on zitadel.ch
To create a ZITADEL project, you have to register as an organization first. Click [here](https://accounts.zitadel.ch/register/org) to register.
You will receive an email prompting you to verify your mail.
@@ -23,7 +17,7 @@ Then go to your [Console Projects](https://console.zitadel.ch/projects) view and
![Organisation Register](/img/accounts_org_register_light.png)
Now you can proceed adding users to your organization as well as integrating your applications. We refer to our guides as well as our [Quickstarts](../quickstarts/introduction) to do so.
Now you can proceed adding users to your organization as well as integrating your applications. We refer to our guides as well as our [Quickstarts](../../quickstarts/introduction) to do so.
#### Verify your domain name (optional)
@@ -32,7 +26,7 @@ If you verify a domain you get the benefit that your organisations users can use
#### Elect Managers
ZITADEL allows you to give other users control over ZITADEL Console itself. This can be restricted to some kind of write and/or read. This can be especially useful for directing administration over several users. You can have managers able to edit project settings and others able to create/add users only.
Read the [guides](introduction) for more information.
Read the [guides](../introduction) for more information.
> Note: ZITADEL Managers are always located on the right sidepanel of console.

2
docs/docs/guides/identity-brokering.md → docs/docs/guides/usage/identity-brokering.md
View File

@@ -22,7 +22,7 @@ title: Identity Brokering
<td>Prerequisites</td>
<td>
<ul>
<li>Knowledge of <a href="/docs/guides/organizations">Organizations</a></li>
<li>Knowledge of <a href="/docs/guides/usage/organizations">Organizations</a></li>
</ul>
</td>
</tr>

0
docs/docs/guides/oauth-recommended-flows.md → docs/docs/guides/usage/oauth-recommended-flows.md
View File

0
docs/docs/guides/organizations.md → docs/docs/guides/usage/organizations.md
View File

0
docs/docs/guides/projects.md → docs/docs/guides/usage/projects.md
View File

6
docs/docs/guides/serviceusers.md → docs/docs/guides/usage/serviceusers.md
View File

@@ -22,7 +22,7 @@ title: Service Users
<td>Prerequisites</td>
<td>
<ul>
<li>Knowledge of <a href="/docs/guides/oauth-recommended-flows">Recommended Authorization Flows</a></li>
<li>Knowledge of <a href="/docs/guides/usage/oauth-recommended-flows">Recommended Authorization Flows</a></li>
</ul>
</td>
</tr>
@@ -110,7 +110,7 @@ Payload
* `iat` is a unix timestamp of the creation signing time of the JWT, e.g. now
* `exp` is the unix timestamp of expiry of this assertion. Must be less than 1 hour from `iat`
Please refer to [JWT_with_Private_Key](../apis/openidoauth/authn-methods#jwt-with-private-key) in the documentation for further information.
Please refer to [JWT_with_Private_Key](../../apis/openidoauth/authn-methods#jwt-with-private-key) in the documentation for further information.
> **Information:** The `exp` claim is currently not validated, but will be with a future release. Make sure that `exp` is less than 1 hour starting from `iat`.
@@ -130,7 +130,7 @@ curl --request POST \
```
* `grant_type` should be set to `urn:ietf:params:oauth:grant-type:jwt-bearer`
* `scope` should contain any [Scopes](../apis/openidoauth/scopes) you want to include, but must include `openid`. For this example, please include `profile` and `email`
* `scope` should contain any [Scopes](../../apis/openidoauth/scopes) you want to include, but must include `openid`. For this example, please include `profile` and `email`
* `assertion` is the encoded value of the JWT that was signed with your private key from the prior step
You should receive a successful response with `access_token`, `token_type` and time to expiry in seconds as `expires_in`.

4
docs/docs/quickstarts/angular.md
View File

@@ -302,6 +302,10 @@ If you get stuck consider checking out our [template](https://github.com/caos/zi
### Whats next?
<<<<<<< HEAD:docs/docs/quickstarts/angular.md
Now you can proceed implementing our APIs to include Authorization. Refer to our [Docs](../apis/apis) or checkout our Console Code on [Github](https://github.com/caos/zitadel) which is using GRPC to access data.
=======
Now you can proceed implementing our APIs to include Authorization. Refer to our [Docs](introduction) or checkout our Console Code on [Github](https://github.com/caos/zitadel) which is using GRPC to access data.
>>>>>>> main:site/docs/angular/02-code.md
For more information about creating an angular application we refer to [Angular](https://angular.io/start) and for more information about the used oauth/oidc library consider reading their docs at [angular-oauth2-oidc](https://github.com/manfredsteyer/angular-oauth2-oidc).

48
docs/sidebars.js
View File

@@ -39,9 +39,43 @@ module.exports = {
{
type: 'category',
label: 'Get to know ZITADEL',
items: ['guides/get-started', 'guides/organizations', 'guides/projects', 'guides/oauth-recommended-flows', 'guides/serviceusers', 'guides/access-zitadel-apis', 'guides/identity-brokering'],
collapsed: false,
items: [
'guides/usage/get-started',
'guides/usage/organizations',
'guides/usage/projects',
'guides/usage/oauth-recommended-flows',
'guides/usage/serviceusers',
'guides/usage/access-zitadel-apis',
'guides/usage/identity-brokering',
],
},
{
type: 'category',
label: 'Installation',
collapsed: false,
items: [
{
type: 'category',
label: 'CAOS Managed',
collapsed: true,
items: [
'guides/installation/shared-cloud',
'guides/installation/managed-dedicated-instance'
],
},
{
type: 'category',
label: 'Self Managed',
collapsed: true,
items: [
'guides/installation/crd',
'guides/installation/gitops',
'guides/installation/orbos'
],
},
],
}
],
apis: [
'apis/introduction',
@@ -50,6 +84,7 @@ module.exports = {
{
type: 'category',
label: 'Proto API Definition',
collapsed: false,
items: [
'apis/proto/auth',
'apis/proto/management',
@@ -66,13 +101,18 @@ module.exports = {
'apis/proto/object',
'apis/proto/options',
],
collapsed: false,
},
{
type: 'category',
label: 'OpenID Connect & OAuth',
items: ['apis/openidoauth/endpoints', 'apis/openidoauth/scopes', 'apis/openidoauth/claims', 'apis/openidoauth/authn-methods', 'apis/openidoauth/grant-types'],
collapsed: false,
items: [
'apis/openidoauth/endpoints',
'apis/openidoauth/scopes',
'apis/openidoauth/claims',
'apis/openidoauth/authn-methods',
'apis/openidoauth/grant-types'
],
},
],
concepts: [
@@ -80,4 +120,4 @@ module.exports = {
'concepts/architecture',
'concepts/principles',
]
};
};

2
docs/src/pages/index.js
View File

@@ -107,7 +107,7 @@ export default function Home() {
'button button--outline button--lg get-started',
styles.getStarted,
)}
to={useBaseUrl('docs/guides/get-started')}>
to={useBaseUrl('docs/guides/usage/get-started')}>
Get Started
</Link>
</div>