mirror of
https://github.com/zitadel/zitadel.git
synced 2024-12-04 15:35:10 +00:00
docs: V2 alpha readme (#3669)
* docs: add actions dok from v1 * docs: change readme * remove billing which will be redone * fix search * use readme branch to test index * fix algolia * fine tune * tweak * test * Update netlify.toml * Update netlify.toml * Update docusaurus.config.js * Update docusaurus.config.js * Apply suggestions from code review Co-authored-by: mffap <mpa@zitadel.com> * tweak readme * Apply suggestions from code review Co-authored-by: Silvan <silvan.reusser@gmail.com> Co-authored-by: Fabi <38692350+hifabienne@users.noreply.github.com> * fix broken part of contrib guide Co-authored-by: mffap <mpa@zitadel.com> Co-authored-by: Silvan <silvan.reusser@gmail.com> Co-authored-by: Fabi <38692350+hifabienne@users.noreply.github.com>
This commit is contained in:
Florian Forster
GitHub
parent
40d7dba574
commit
220c8e4922
@ -1,18 +1,88 @@
|
||||
# How to contribute to ZITADEL
|
||||
# Contributing to ZITADEL
|
||||
|
||||
## Did you find a bug?
|
||||
## Introduction
|
||||
|
||||
Please file an issue [here](https://github.com/zitadel/zitadel/issues/new?assignees=&labels=bug&template=bug_report.md&title=).
|
||||
Thank you for your interest about how to contribute! As you might know there is more than code to contribute. You can find all information needed to start contributing here.
|
||||
|
||||
Bugs are evaluated every day as soon as possible.
|
||||
Please give us and our community the chance to get rid of security vularbilities by responsibly disclose this kind of issues by contacting [security@zitadel.com](mailto:security@zitadel.com).
|
||||
|
||||
## Enhancement
|
||||
The strongest part of a community is the possibility to share thoughts. That's why we try to react as soon as possible to your ideas, thoughts and feedback. We love to discuss as much as possible in an open space like in the [issues](https://github.com/zitadel/zitadel/issues) and [discussions](https://github.com/zitadel/zitadel/discussions) section here or in our [chat](https://zitadel.com/chat), but we understand your doubts and provide further contact options [here](https://zitadel.com/contact).
|
||||
|
||||
Do you miss a feature? Please file an issue [here](https://github.com/zitadel/zitadel/issues/new?assignees=&labels=enhancement&template=feature_request.md&title=)
|
||||
If you want to give an answer or be part of discussions please be kind. Treat others like you want to be treated. Read more about our code of conduct [here](CODE_OF_CONDUCT.md).
|
||||
|
||||
Enhancements are discussed and evaluated every Wednesday by the ZITADEL core team.
|
||||
## What can I contribute?
|
||||
|
||||
## Grab an Issues
|
||||
For people who are new to ZITADEL: We flag issues which are a good starting point to start contributing. You find them [here](https://github.com/zitadel/zitadel/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
|
||||
|
||||
Make ZITADEL more popular and give it a ⭐
|
||||
|
||||
Help shaping the future of ZITADEL by
|
||||
|
||||
- Join our [chat](https://zitadel.com/chat) and discuss with us or others.
|
||||
- Ask or answer questions in the [issues section](https://github.com/zitadel/zitadel/issues)
|
||||
- Share your thoughts and ideas in the [discussions section](https://github.com/zitadel/zitadel/discussions)
|
||||
|
||||
[Contribute](#how-to-contribute)
|
||||
|
||||
- [Code](#contribute-code)
|
||||
- If you found a mistake on our [docs page](https://docs.zitadel.com) or something is missing please read [the docs section](#contribute-docs)
|
||||
|
||||
Follow [@zitadel](https://twitter.com/zitadel) on twitter
|
||||
|
||||
## How to contribute
|
||||
|
||||
We strongly recomend to talk to us before you start contributing to streamline our and your work.
|
||||
|
||||
We accept contributions through pull requests. You need a github account for that. If you are unfamiliar with git have a look at Github's documentation on [creating forks](https://help.github.com/articles/fork-a-repo) and [creating pull requests](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork). Please draft the pull request as soon as possible. Go through the following checklist before you submit the final pull request:
|
||||
|
||||
1. Create a feature branch from the `main`-branch
|
||||
1. Make your changes on the new branch
|
||||
1. [Merge](https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging) the lastet commit of the `main`-branch
|
||||
1. Use [Semantic Release commit messages](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#type) to simplify creation of release notes. In the title of the pull request correct tagging is required and will be requested by the reviewers.
|
||||
1. Request a [review](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/requesting-a-pull-request-review) from one of the authors. The reviewers will provide you feedback and approve your changes as soon as they are satisfied.
|
||||
|
||||
## Contribute
|
||||
|
||||
The code consists of the following parts:
|
||||
|
||||
| name | description | language | where to find |
|
||||
|---|---|---|---|
|
||||
| backend | Service that serves the grpc(-web) and RESTful API | [go](https://go.dev) | [API implementation](./internal/api/grpc) |
|
||||
| console | Frontend the user inertacts with after he is logged in | [Angular](https://angular.io), [Typescript](https://www.typescriptlang.org) | [./console](./console) |
|
||||
| login | Server side rendered frontend the user interacts with during login | [go](https://go.dev), [go templates](https://pkg.go.dev/html/template) | [./internal/api/ui/login](./internal/api/ui/login) |
|
||||
| API definitions | Specifications of the API | [Protobuf](https://developers.google.com/protocol-buffers) | [./proto/zitadel](./proto/zitadel) |
|
||||
| docs | Project documentation made with docusaurus | [Docusaurus](https://docusaurus.io/) | [./docs](./docs) |
|
||||
|
||||
Please validate and test the code before you contribute.
|
||||
|
||||
### Backend / Login
|
||||
|
||||
To keep the code clean and understandable we use [golangci-lint](https://golangci-lint.run). We recommend to format the code with this linter while working on ZITADEL to simplify the review process. The configuration is locaed [here](./.golangci.yaml).
|
||||
|
||||
To start the backend with a debugger run the [`main.go`-file](./main.go) located in the root of ZITADEL and provide the arguments and env-variables from below. Ensure that the database is running by running `docker compose -f ./build/local/docker-compose.yml up db`. For additional information please use the documentation of your IDE.
|
||||
|
||||
Make sure to use the following configurations:
|
||||
|
||||
TODO document workflow
|
||||
|
||||
### Console
|
||||
|
||||
<!-- TODO: ask maxpe for infos -->
|
||||
|
||||
### API Definitions
|
||||
|
||||
Ensure the provided code meets the [offical style guide](https://developers.google.com/protocol-buffers/docs/style).
|
||||
|
||||
The following docker command builds the grpc stub into the correct folders:
|
||||
|
||||
```bash
|
||||
docker build -f build/grpc/Dockerfile -t zitadel-base:local . \
|
||||
&& docker build -f build/zitadel/Dockerfile . -t zitadel-go-base --target go-copy -o .
|
||||
```
|
||||
|
||||
## Contribute Docs
|
||||
|
||||
<!-- TODO: ask maxpe for infos -->
|
||||
|
||||
We add the label "good first issue" for problems we think are a good starting point to contribute to ZITADEL.
|
||||
|
||||
@ -31,16 +101,9 @@ Make sure you use semantic release:
|
||||
|
||||
## Want to start ZITADEL?
|
||||
|
||||
Checkout the following chapters to start ZITADEL locally.
|
||||
|
||||
### Build for local development
|
||||
|
||||
* Check out our [development guide](guides/development.md).
|
||||
|
||||
### Quick start
|
||||
|
||||
* Check out our [quick start guide](guides/quickstart.md).
|
||||
You can find an installation guide for all the different environments here:
|
||||
[https://docs.zitadel.com/docs/guides/installation](https://docs.zitadel.com/docs/guides/installation)
|
||||
|
||||
## **Did you find a security flaw?**
|
||||
|
||||
* Please read [Security Policy](SECURITY.md).
|
||||
* Please read [Security Policy](./SECURITY.md).
|
||||
|
||||
172
README.md
172
README.md
@ -1,112 +1,127 @@
|
||||
<img src="./docs/static/logos/zitadel-logo-dark@2x.png#gh-light-mode-only" alt="Zitadel Logo" height="100px" width="auto" />
|
||||
<img src="./docs/static/logos/zitadel-logo-light@2x.png#gh-dark-mode-only" alt="Zitadel Logo" height="100px" width="auto" />
|
||||
<p align="center">
|
||||
<img src="./docs/static/logos/zitadel-logo-dark@2x.png#gh-light-mode-only" alt="Zitadel Logo" height="200px" width="auto" />
|
||||
<img src="./docs/static/logos/zitadel-logo-light@2x.png#gh-dark-mode-only" alt="Zitadel Logo" height="200px" width="auto" />
|
||||
</p>
|
||||
|
||||
[](https://github.com/semantic-release/semantic-release)
|
||||
[](https://github.com/zitadel/zitadel/actions)
|
||||
[](https://github.com/zitadel/zitadel/blob/main/LICENSE)
|
||||
[](https://github.com/zitadel/zitadel/releases)
|
||||
[](https://goreportcard.com/report/github.com/zitadel/zitadel)
|
||||
[](https://codecov.io/gh/zitadel/zitadel)
|
||||
[](https://discord.gg/erh5Brh7jE)
|
||||
[](https://openid.net/certification/#OPs)
|
||||
<p align="center">
|
||||
<a href="https://github.com/zitadel/zitadel/graphs/contributors" alt="Release">
|
||||
<img src="https://badgen.net/github/contributors/zitadel/zitadel" /></a>
|
||||
<a href="https://github.com/semantic-release/semantic-release" alt="semantic-release">
|
||||
<img src="https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg" /></a>
|
||||
<a href="https://github.com/zitadel/zitadel/actions" alt="ZITADEL Release">
|
||||
<img src="https://github.com/zitadel/zitadel/actions/workflows/zitadel.yml/badge.svg" /></a>
|
||||
<a href="https://github.com/zitadel/zitadel/blob/main/LICENSE" alt="License">
|
||||
<img src="https://badgen.net/github/license/zitadel/zitadel/" /></a>
|
||||
<a href="https://github.com/zitadel/zitadel/releases" alt="Release">
|
||||
<img src="https://badgen.net/github/release/zitadel/zitadel/stable" /></a>
|
||||
<a href="https://goreportcard.com/report/github.com/zitadel/zitadel" alt="Go Report Card">
|
||||
<img src="https://goreportcard.com/badge/github.com/zitadel/zitadel" /></a>
|
||||
<a href="https://codecov.io/gh/zitadel/zitadel" alt="Code Coverage">
|
||||
<img src="https://codecov.io/gh/zitadel/zitadel/branch/main/graph/badge.svg" /></a>
|
||||
<a href="https://discord.gg/erh5Brh7jE" alt="Discord Chat">
|
||||
<img src="https://badgen.net/discord/online-members/erh5Brh7jE" /></a>
|
||||
</p>
|
||||
|
||||
## What Is ZITADEL
|
||||
<p align="center">
|
||||
<a href="https://openid.net/certification/#OPs" alt="OpenID Connect Certified">
|
||||
<img src="./docs/static/logos/oidc-cert.png" /></a>
|
||||
</p>
|
||||
|
||||
**ZITADEL** is a "Cloud Native Identity and Access Management" solution built for the cloud era. ZITADEL uses a modern software stack consisting of [**Golang**](https://golang.org/), [**Angular**](https://angular.io/) and [**CockroachDB**](https://www.cockroachlabs.com/) as sole storage and follows an event sourced pattern.
|
||||
You want auth that's quickly set up like Auth0 but open source like Keycloak? Look no further— ZITADEL combines the ease of Auth0 and the versatility of Keycloak.
|
||||
|
||||
We built **ZITADEL** not only with the vision of becoming a great open source project but also as a superb platform to support developers building their applications, without need to handle secure user login and account management themselves.
|
||||
|
||||
## How Does It Work
|
||||
We provide a wide range of out of the box features like secure login, self-service, OpenID Connect, OAuth2.x, SAML2, branding, Passwordless with FIDO2, OTP, U2F, and an unlimited audit trail to improve the life of developers. Especially noteworthy is that ZITADEL supports not only B2C and B2E scenarios but also B2B. This is super useful for people who build B2B Solutions, as ZITADEL can handle all the delegated user and access management.
|
||||
|
||||
We built **ZITADEL** around the idea that the IAM should be easy to deploy and scale. That's why we tried to reduce external systems as much as possible.
|
||||
For example, **ZITADEL** is event sourced but it does not rely on a pub/sub system to function. Instead we built all the functionality right into one binary.
|
||||
**ZITADEL** only needs [**Kubernetes**](https://kubernetes.io/) for orchestration and [**CockroachDB**](https://www.cockroachlabs.com/) as storage.
|
||||
With ZITADEL you rely on a battle tested, hardened and extensible turnkey solution to solve all of your authentication and authorization needs. With the unique way of how ZITADEL stores data it gives you an unlimited audit trail which provides a peace of mind for even the harshest audit and analytics requirements.
|
||||
|
||||
## Run ZITADEL anywhere
|
||||
<!-- TODO: Insert Video here-->
|
||||
|
||||
### Self-hosted
|
||||
---
|
||||
|
||||
You can run an automatically operated **ZITADEL** instance on a CNCF compliant Kubernetes cluster of your choice:
|
||||
**[🏡 Website](https://zitadel.com) [💬 Chat](https://zitadel.com/chat) [📋 Docs](https://docs.zitadel.ch/) [🧑💻 Blog](https://zitadel.com/blog) [📞 Contact](https://zitadel.com/contact/)**
|
||||
|
||||
* [CRD Mode on an existing k8s cluster](https://docs.zitadel.ch/docs/guides/installation/crd)
|
||||
* [GitOps Mode on an existing k8s cluster](https://docs.zitadel.ch/docs/guides/installation/gitops)
|
||||
* [GitOps Mode on VM/bare-metal](https://docs.zitadel.ch/docs/guides/installation/managed-dedicated-instance) using [ORBOS](https://docs.zitadel.ch/docs/guides/installation/orbos)
|
||||
## Get started
|
||||
|
||||
### Software-as-a-Service
|
||||
### ZITADEL Cloud
|
||||
|
||||
* **ZITADEL Cloud:** [**ZITADEL.ch**](https://zitadel.ch) is our shared cloud service hosted in Switzerland. [Get started](https://docs.zitadel.ch/docs/guides/basics/get-started) and try the free tier, including already unlimited users and all necessary security features.
|
||||
* **ZITADEL Dedicated:** We operate and support a dedicated instance of **ZITADEL** for you. [Get in touch!](https://zitadel.ch/contact/)
|
||||
The easiest way to get started with ZITADEL is to use our public cloud offering. [Subscribe to our newsletter](https://zitadel.com/v2) and we will be in touch with you as soon as the public release is live.
|
||||
|
||||
## Start using ZITADEL
|
||||
You can also discovery our new pay-as-you-go [pricing](https://zitadel.com/pricing/v2).
|
||||
|
||||
### Quickstarts
|
||||
### Install ZITADEL
|
||||
|
||||
See our [Documentation](https://docs.zitadel.ch/docs/quickstarts/introduction) to get started with ZITADEL quickly. Let us know, if you are missing a language or framework in the [Q&A](https://github.com/zitadel/zitadel/discussions/1717).
|
||||
- [We provide installation guides for multiple platforms here](https://docs.zitadel.com/docs/guides/installation)
|
||||
|
||||
### Quickstarts - Integrate your app
|
||||
|
||||
- [Multiple Quickstarts can be found here](https://docs.zitadel.com/docs/quickstarts/introduction)
|
||||
- [And even more examples are located under zitadel/zitadel-examples](https://github.com/zitadel/zitadel-examples)
|
||||
|
||||
> If you miss something please feel free to engage with us [here](https://github.com/zitadel/zitadel/discussions/1717)
|
||||
|
||||
## Why ZITADEL
|
||||
|
||||
- [API-first](https://docs.zitadel.com/docs/apis/introduction)
|
||||
- Strong audit trail thanks to [event sourcing](https://docs.zitadel.com/docs/concepts/eventstore)
|
||||
- [Actions](https://docs.zitadel.ch/docs/concepts/features/actions) to react on events with custom code
|
||||
- [Branding](https://docs.zitadel.com/docs/guides/customization/branding) for a uniform user experience
|
||||
- [Cockroach database](https://www.cockroachlabs.com/) is the only dependency
|
||||
|
||||
## Features
|
||||
|
||||
- Single Sign On (SSO)
|
||||
- Passwordless with FIDO2 support
|
||||
- Username / Password
|
||||
- Multifactor authentication with OTP, U2F
|
||||
- [Identity Brokering](https://docs.zitadel.com/docs/guides/authentication/identity-brokering)
|
||||
- [Machine-to-machine (JWT profile)](https://docs.zitadel.com/docs/guides/authentication/serviceusers)
|
||||
- Personal Access Tokens (PAT)
|
||||
- Role Based Access Control (RBAC)
|
||||
- [Delegate role management to third-parties](https://docs.zitadel.com/docs/guides/basics/projects#what-is-a-granted-project)
|
||||
- Self-registration including verification
|
||||
- User self service
|
||||
- [Service Accounts](https://docs.zitadel.com/docs/guides/authentication/serviceusers)
|
||||
|
||||
### Client libraries
|
||||
|
||||
* [Go](https://github.com/zitadel/zitadel-go) client library
|
||||
* [.NET](https://github.com/zitadel/zitadel-net) client library
|
||||
* [Dart](https://github.com/zitadel/zitadel-dart) client library
|
||||
* [Elixir](https://github.com/jshmrtn/zitadel_api) client library (maintained by [jshmrtn]([jshmrtn](https://github.com/jshmrtn)))
|
||||
<!-- TODO: check other libraries -->
|
||||
|
||||
## Help and Documentation
|
||||
| Language | Client | API | Machine auth (\*) | Auth check (\*\*) | Thanks to the maintainers |
|
||||
|----------|--------|--------------|----------|---------|---------------------------|
|
||||
| .NET | [zitadel-net](https://github.com/zitadel/zitadel-net) | GRPC | ✔️ | ✔️ | [buehler 👑](https://github.com/buehler) |
|
||||
| Dart | [zitadel-dart](https://github.com/zitadel/zitadel-dart) | GRPC | ✔️ | ❌ | [buehler 👑](https://github.com/buehler) |
|
||||
| Elixir | [zitadel_api](https://github.com/jshmrtn/zitadel_api) | GRPC | ✔️ | ✔️ | [jshmrtn 🙏🏻](https://github.com/jshmrtn) |
|
||||
| Go | [zitadel-go](https://github.com/zitadel/zitadel-go) | GRPC | ✔️ | ✔️ | ZITADEL |
|
||||
| Rust | [zitadel-rust](https://crates.io/crates/zitadel) | GRPC | ✔️ | ❌ | [buehler 👑](https://github.com/buehler) |
|
||||
| JVM | 🚧 [WIP](https://github.com/zitadel/zitadel/discussions/3650) | ❓ | ❓ | | TBD |
|
||||
| Python | 🚧 [WIP](https://github.com/zitadel/zitadel/issues/3675) | ❓ | ❓ | | TBD |
|
||||
| Javascript | ❓ | ❓ | ❓ | | Maybe you? |
|
||||
|
||||
* [Documentation](https://docs.zitadel.ch)
|
||||
* [Say hello](https://zitadel.ch/contact/)
|
||||
* [Join our Discord channel](https://discord.gg/erh5Brh7jE)
|
||||
(\*) Automatically authenticate service accounts with [JWT Profile](https://docs.zitadel.com/docs/apis/openidoauth/grant-types#json-web-token-jwt-profile).
|
||||
(\*\*) Automatically check if the access token is valid and claims match
|
||||
|
||||
## How To Contribute
|
||||
|
||||
Details about how to contribute you can find in the [Contribution Guide](CONTRIBUTING.md)
|
||||
|
||||
## Security
|
||||
|
||||
See the policy [here](./SECURITY.md)
|
||||
|
||||
## Features of ZITADEL platform
|
||||
|
||||
* Authentication
|
||||
* OpenID Connect 1.0 Protocol (OP)
|
||||
* Username / Password
|
||||
* Machine-to-machine (JWT profile)
|
||||
* Passwordless with FIDO2
|
||||
* Multifactor authentication with OTP, U2F
|
||||
* Federation with OpenID Connect 1.0 Protocol (RP), OAuth 2.0 Protocol (RP)
|
||||
* Identity Brokering
|
||||
* Identity & Access Management
|
||||
* B2C, B2B, B2E, M2M identities
|
||||
* Authorization via Role Based Access Control (RBAC)
|
||||
* Delegation of roles to other organizations for self-management
|
||||
* Management roles
|
||||
* User self-service workflows
|
||||
* User register workflow
|
||||
* Strong audit trail for all IAM resources
|
||||
* Privatelabeling
|
||||
* Custom branding
|
||||
* Custom texts
|
||||
* Hosted login
|
||||
* Personal profile
|
||||
* Integration
|
||||
* API-first
|
||||
* Actions for custom code execution
|
||||
Details about how to contribute you can find in the [Contribution Guide](./CONTRIBUTING.md)
|
||||
|
||||
## Showcase
|
||||
|
||||
<!-- TODO: Replace Images-->
|
||||
|
||||
### Passwordless Login
|
||||
|
||||
Use our login widget to allow easy and sucure access to your applications and enjoy all the benefits of passwordless (FIDO 2 / WebAuthN):
|
||||
Use our login widget to allow easy and secure access to your applications and enjoy all the benefits of passwordless (FIDO 2 / WebAuthN):
|
||||
|
||||
* works on all modern platforms, devices, and browsers
|
||||
* phishing resistant alternative
|
||||
* requires only one gesture by the user
|
||||
* easy [enrollment](https://docs.zitadel.ch/docs/manuals/user-factors) of the device during registration
|
||||
* easy [enrollment](https://docs.zitadel.com/docs/manuals/user-factors) of the device during registration
|
||||
|
||||
|
||||
|
||||
### Admin Console
|
||||
|
||||
Use [Console](https://docs.zitadel.ch/docs/manuals/introduction) or our [APIs](https://docs.zitadel.ch/docs/apis/introduction) to setup organizations, projects and applications.
|
||||
Use [Console](https://docs.zitadel.com/docs/manuals/introduction) or our [APIs](https://docs.zitadel.com/docs/apis/introduction) to setup organizations, projects and applications.
|
||||
|
||||
Register new applications
|
||||
|
||||
@ -117,16 +132,9 @@ Delegate the right to assign roles to another organization
|
||||
Customize login and console with your design
|
||||
|
||||
|
||||
|
||||
## Other CAOS Projects
|
||||
|
||||
* [**ORBOS**](https://github.com/caos/orbos/) - GitOps everything
|
||||
* [**OIDC for GO**](https://github.com/zitadel/oidc) - OpenID Connect SDK (client and server) for Go
|
||||
* [**ZITADEL Tools**](https://github.com/zitadel/zitadel-tools) - Go tool to convert key file to privately signed JWT
|
||||
|
||||
## Usage Data
|
||||
|
||||
ZITADEL components send errors and usage data to CAOS Ltd., so that we are able to identify code improvement potential. If you don't want to send this data or don't have an internet connection, pass the global flag `--disable-analytics` when using zitadelctl. For disabling ingestion for already-running components, execute the takeoff command again with the `--disable-analytics` flag.
|
||||
ZITADEL components send errors and usage data to CAOS Ltd., so that we are able to identify code improvement potential. If you don't want to send this data or don't have an internet connection, pass the global flag `--disable-analytics` when using zitadelctl. For disabling ingestion for already-running components, execute the takeoff command again with the `` flag.
|
||||
|
||||
We try to distinguishing the environments from which events come from. As environment identifier, we enrich the events by the domain you have configured in zitadel.yml, as soon as it's available. When it's not available and you passed the --gitops flag, we defer the environment identifier from your git repository URL.
|
||||
|
||||
@ -134,6 +142,10 @@ Besides from errors that don't clearly come from misconfiguration or cli misuage
|
||||
|
||||
We only ingest operational data. Your ZITADEL workload data from the IAM application itself is never sent anywhere unless you chose to integrate other systems yourself.
|
||||
|
||||
## Security
|
||||
|
||||
See the policy [here](./SECURITY.md)
|
||||
|
||||
## License
|
||||
|
||||
See the exact licensing terms [here](./LICENSE)
|
||||
|
||||
@ -1,11 +1,12 @@
|
||||
# Security Policy
|
||||
|
||||
At CAOS we are extremely grateful for security aware people who disclose vulnerabilities to us and the open source community. All reports will be investigated by our team.
|
||||
At ZITADEL we are extremely grateful for security aware people who disclose vulnerabilities to us and the open source community. All reports will be investigated by our team.
|
||||
|
||||
## Supported Versions
|
||||
|
||||
| Version | Supported |
|
||||
| ------- | ------------------ |
|
||||
| 2.x.x | :white_check_mark: as soon as officialy released |
|
||||
| 1.x.x | :white_check_mark: |
|
||||
| 0.x.x | :x: |
|
||||
|
||||
|
||||
106
docs/docs/apis/actions.md
Normal file
106
docs/docs/apis/actions.md
Normal file
@ -0,0 +1,106 @@
|
||||
---
|
||||
title: Actions
|
||||
---
|
||||
|
||||
This page describes the options you have when writing ZITADEL actions scripts.
|
||||
|
||||
## Language
|
||||
ZITADEL interpretes the scripts as JavaScript.
|
||||
Make sure your scripts are ECMAScript 5.1(+) compliant.
|
||||
Go to the [goja GitHub page](https://github.com/dop251/goja) for detailed reference about the underlying library features and limitations.
|
||||
|
||||
Actions do not have access to any libraries yet.
|
||||
Also, sending HTTP requests is not supported yet.
|
||||
[We plan to add such features in the future](https://zitadel.ch/roadmap).
|
||||
|
||||
## Flows
|
||||
|
||||
Each flow type supports its own set of:
|
||||
- Triggers
|
||||
- Readable information
|
||||
- Writable information
|
||||
|
||||
For reading and mutating state, the runtime executes the function that has the same name as the action.
|
||||
The function receives the JavaScript objects `ctx` and `api`.
|
||||
|
||||
The object `ctx` provides readable information as object properties and by callable functions.
|
||||
The object `api` provides mutable properties and state mutating functions.
|
||||
|
||||
The script of an action called **doSomething** should have a function called `doSomething` and look something like this:
|
||||
|
||||
```js
|
||||
function doSomething(ctx, api){
|
||||
// read from ctx and manipulate with api
|
||||
}
|
||||
```
|
||||
|
||||
ZITADEL supports only the external authentication flow at the moment.
|
||||
[More flows are coming soon](https://zitadel.ch/roadmap).
|
||||
|
||||
### External authentication flow triggers
|
||||
|
||||
- Post authentication: A user has authenticated externally. ZITADEL retrieved and mapped the external information.
|
||||
- Pre creation: A user selected **Register** on the overview page after external authentication. ZITADEL did not create the user yet.
|
||||
- Post creation: A user selected **Register** on the overview page after external authentication. ZITADEL created the user.
|
||||
|
||||
### External authentication flow context
|
||||
|
||||
- `ctx.accessToken string`
|
||||
This can be an opaque token or a JWT
|
||||
- `ctx.idToken string`
|
||||
- `ctx.getClaim(string) any`
|
||||
Returns the requested claim
|
||||
- `ctx.claimsJSON() object`
|
||||
Returns the complete payload of the `ctx.idToken`
|
||||
|
||||
### External authentication flow api
|
||||
|
||||
- `api.setFirstName(string)`
|
||||
- `api.setLastName(string)`
|
||||
- `api.setNickName(string)`
|
||||
- `api.setDisplayName(string)`
|
||||
- `api.setPreferredLanguage(string)`
|
||||
- `api.setGender(Gender)`
|
||||
- `api.setUsername(string)`
|
||||
This function is only available for the pre creation trigger
|
||||
- `api.setPreferredUsername(string)`
|
||||
This function is only available for the post authentication trigger
|
||||
- `api.setEmail(string)`
|
||||
- `api.setEmailVerified(bool)`
|
||||
- `api.setPhone(string)`
|
||||
- `api.setPhoneVerified(bool)`
|
||||
- `api.metadata array<Metadata>`
|
||||
Push entries.
|
||||
- `api.userGrants array<UserGrant>`
|
||||
Push entries.
|
||||
This field is only available for the post creation trigger
|
||||
|
||||
|
||||
### External authentication flow types <!-- TODO: Are these types correct? -->
|
||||
|
||||
- `Gender` is a code number
|
||||
|
||||
| code | gender |
|
||||
| ---- | ------ |
|
||||
| 0 | unspecified |
|
||||
| 1 | female |
|
||||
| 2 | male |
|
||||
| 3 | diverse |
|
||||
|
||||
- `UserGrant` is a JavaScript object
|
||||
|
||||
```ts
|
||||
{
|
||||
ProjectID: string,
|
||||
ProjectGrantID: string,
|
||||
Roles: Array<string>,
|
||||
}
|
||||
```
|
||||
|
||||
- `Metadata` is a JavaScript object with string values.
|
||||
The string values must be Base64 encoded
|
||||
|
||||
## Further reading
|
||||
|
||||
- [Actions concept](../concepts/features/actions)
|
||||
- [Actions guide](../guides/customization/behavior)
|
||||
38
docs/docs/concepts/features/actions.md
Normal file
38
docs/docs/concepts/features/actions.md
Normal file
@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Actions
|
||||
---
|
||||
|
||||
By using ZITADEL actions, you can manipulate ZITADELs behavior on specific Events.
|
||||
This is useful when you have special business requirements that ZITADEL doesn't support out-of-the-box.
|
||||
|
||||
:::caution
|
||||
ZITADEL actions is in an early development stage.
|
||||
In the [roadmap](https://zitadel.ch/roadmap), you see how we are planning to expand and improve it.
|
||||
Please tell us about your needs and help us prioritize further fixes and features.
|
||||
:::
|
||||
|
||||
## Why actions?
|
||||
ZITADEL can't anticipate and solve every possible business rule and integration requirements from all ZITADEL users. Here are some examples:
|
||||
- A business requires domain specific data validation before a user can be created or authenticated.
|
||||
- A business needs to automate tasks. Roles should be assigned to users based on their ADFS 2016+ groups.
|
||||
- A business needs to store metadata on a user that is used for integrating applications.
|
||||
- A business needs to restrict the users who are allowed to register to a certain organization by their email domains.
|
||||
|
||||
With actions, ZITADEL provides a way to solve such problems.
|
||||
|
||||
## How it works
|
||||
Using the actions feature, *ORG_OWNERs* create a flow for each supported flow type.
|
||||
Each flow type provides its own events.
|
||||
You can hook into these events by assigning them an action.
|
||||
An action is composed of
|
||||
* a name,
|
||||
* a custom JavaScript code snippet,
|
||||
* an execution timeout in seconds,
|
||||
* a switch that defines if its corresponding flow should fail if the action fails.
|
||||
|
||||
Within the JavaScript code, you can read and manipulate the state.
|
||||
|
||||
## Further reading
|
||||
|
||||
- [Assign users a role after they register using an external identity provider](../../guides/customization/behavior)
|
||||
- [Actions reference](../../apis/actions)
|
||||
@ -36,4 +36,7 @@ Please be reminded that ZITADEL is open source — and so is the documentation.
|
||||
<ListWrapper title="Use Cases">
|
||||
<ListElement link="./usecases/saas" type={ICONTYPE.START} title="SaaS" description="Product with Authentication and Authorization" />
|
||||
</ListWrapper>
|
||||
<ListWrapper title="Features">
|
||||
<ListElement link="./features/actions" type={ICONTYPE.FILE} title="Actions" description="Customizing ZITADELs behavior using the actions feature" />
|
||||
</ListWrapper>
|
||||
</Column>
|
||||
|
||||
58
docs/docs/guides/customization/behavior.md
Normal file
58
docs/docs/guides/customization/behavior.md
Normal file
@ -0,0 +1,58 @@
|
||||
---
|
||||
title: Behavior Customization
|
||||
---
|
||||
|
||||
In this guide, you will create a [ZITADEL action](../../concepts/features/actions).
|
||||
After users register using an external identity provider, the action assigns them a role.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before you start, make sure you have everything set up correctly.
|
||||
|
||||
- You need to be at least a ZITADEL *ORG_OWNER*
|
||||
- Your ZITADEL organization needs to have the actions feature enabled. <!-- TODO: How to enable it for SaaS ZITADEL? -->
|
||||
- [Your ZITADEL organization needs to have at least one external identity provider enabled](../authentication/identity-brokering)
|
||||
- [You need to have at least one role configured for a project](../basics/projects)
|
||||
|
||||
## Copy some information for the action
|
||||
|
||||
1. Select the **Projects** navigation item.
|
||||
1. Select a project that has a role configured.
|
||||
1. Copy the projects **Resource Id** on the screens top right.
|
||||
1. Scroll to the **ROLES** section and note some roles key.
|
||||
|
||||
## Create the action
|
||||
|
||||
1. Select the **Actions** navigation item.
|
||||
1. In the **Actions <i class="las la-code"></i>** section, select the **+ New** button.
|
||||
1. Give the new action the name `addGrant`.
|
||||
1. Paste this snippet into the multiline textfield.
|
||||
1. Replace the snippets placeholders and select **Save**.
|
||||
|
||||
```js
|
||||
function addGrant(ctx, api) {
|
||||
api.userGrants.push({
|
||||
ProjectID: '<the projects resource ID you copied above>',
|
||||
Roles: ['<the role key you copied above>']
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
## Run the action when a user registers
|
||||
|
||||
Now, make the action hook into the [external authentication flow](../../apis/actions#external-authentication-flow).
|
||||
|
||||
1. In the **Flows <i class="las la-exchange-alt"></i>** section, select the **+ New** button.
|
||||
1. Select the **Flow Type** *External Authentication*.
|
||||
1. Select the **Trigger Type** *Post Creation*.
|
||||
1. In the **Actions** dropdown, check *addGrant*.
|
||||
1. Select the **Save** button.
|
||||
|
||||
<!-- TODO: ## Test if your action works -->
|
||||
|
||||
New users automatically are assiged a role now if they register by authenticating with an external identity provider.
|
||||
|
||||
## What's next?
|
||||
|
||||
- [Read more about the concepts around actions](../../concepts/features/actions)
|
||||
- [Read more about all the options you have with actions](../../apis/actions)
|
||||
@ -76,6 +76,12 @@ When you are familiar with the ZITADEL usage, you can choose to stay on [zitadel
|
||||
title="Texts"
|
||||
description="Login interface texts and notification texts"
|
||||
/>
|
||||
<ListElement
|
||||
link="/docs/guides/customization/behavior"
|
||||
type={ICONTYPE.TEXTS}
|
||||
title="Behavior"
|
||||
description="Customize ZITADELs behavior"
|
||||
/>
|
||||
</ListWrapper>
|
||||
<ListWrapper title="Solution Scenarios">
|
||||
<ListElement
|
||||
|
||||
@ -132,13 +132,17 @@ module.exports = {
|
||||
],
|
||||
},
|
||||
],
|
||||
copyright: `Copyright © ${new Date().getFullYear()} ZITADEL - Built with Docusaurus.`,
|
||||
copyright: `Copyright © ${new Date().getFullYear()} ZITADEL Docs - Built with Docusaurus.`,
|
||||
},
|
||||
algolia: {
|
||||
appId: "8H6ZKXENLO",
|
||||
apiKey: "c3899716db098111f5e89c8987b9c427",
|
||||
indexName: "zitadel",
|
||||
},
|
||||
appId: "1FD5EU44EF",
|
||||
apiKey: "2ddc6c35930ec608baf832bf07b5e150",
|
||||
siteId: '13929a6d-0c07-4205-af9b-42121333ec5d',
|
||||
branch: 'v2-alpha-readme',
|
||||
indexName: 'netlify_13929a6d-0c07-4205-af9b-42121333ec5d_v2-alpha-readme_all',
|
||||
contextualSearch: false,
|
||||
selector: 'div#'
|
||||
},
|
||||
prism: {
|
||||
additionalLanguages: ["csharp", "dart", "groovy"],
|
||||
},
|
||||
@ -149,7 +153,7 @@ module.exports = {
|
||||
{
|
||||
docs: {
|
||||
sidebarPath: require.resolve("./sidebars.js"),
|
||||
editUrl: "https://github.com/zitadel/zitadel/edit/main/docs/",
|
||||
editUrl: "https://github.com/zitadel/zitadel/edit/v2-alpha/docs/",
|
||||
remarkPlugins: [require("mdx-mermaid")],
|
||||
},
|
||||
theme: {
|
||||
|
||||
@ -1,6 +1,13 @@
|
||||
[build]
|
||||
command = "npm run build"
|
||||
|
||||
[[plugins]]
|
||||
package = "@algolia/netlify-plugin-crawler"
|
||||
[plugins.inputs]
|
||||
branches = ['v2-alpha', 'v2', 'v2-alpha-readme']
|
||||
renderJavaScript = false
|
||||
template = "hierarchical"
|
||||
|
||||
[[redirects]]
|
||||
from = "/proxy/js/script.js"
|
||||
to = "https://plausible.io/js/plausible.js"
|
||||
|
||||
@ -92,7 +92,11 @@ module.exports = {
|
||||
type: "category",
|
||||
label: "Customization",
|
||||
collapsed: false,
|
||||
items: ["guides/customization/branding", "guides/customization/texts"],
|
||||
items: [
|
||||
"guides/customization/branding",
|
||||
"guides/customization/texts",
|
||||
"guides/customization/behavior"
|
||||
],
|
||||
},
|
||||
{
|
||||
type: "category",
|
||||
@ -153,6 +157,7 @@ module.exports = {
|
||||
collapsed: true,
|
||||
items: ["apis/assets/assets"],
|
||||
},
|
||||
"apis/actions"
|
||||
],
|
||||
},
|
||||
{
|
||||
@ -186,7 +191,7 @@ module.exports = {
|
||||
{
|
||||
type: "category",
|
||||
label: "Structure",
|
||||
collapsed: true,
|
||||
collapsed: false,
|
||||
items: [
|
||||
"concepts/structure/overview",
|
||||
"concepts/structure/instance",
|
||||
@ -205,6 +210,12 @@ module.exports = {
|
||||
collapsed: false,
|
||||
items: ["concepts/usecases/saas"],
|
||||
},
|
||||
{
|
||||
type: "category",
|
||||
label: "Features",
|
||||
collapsed: false,
|
||||
items: ["concepts/features/actions"],
|
||||
},
|
||||
],
|
||||
manuals: [
|
||||
"manuals/introduction",
|
||||
|
||||
Loading…
Reference in New Issue
Block a user