mirror of
https://github.com/zitadel/zitadel.git
synced 2025-08-12 04:07:31 +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
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",
|
||||
|
||||
Reference in New Issue
Block a user