mirror of
https://github.com/andwati/zitadel.git
synced 2026-10-24 16:22:16 +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 <[email protected]> * tweak readme * Apply suggestions from code review Co-authored-by: Silvan <[email protected]> Co-authored-by: Fabi <[email protected]> * fix broken part of contrib guide Co-authored-by: mffap <[email protected]> Co-authored-by: Silvan <[email protected]> Co-authored-by: Fabi <[email protected]>
This commit is contained in:
Florian Forster
co-authored by
mffap
Silvan
Fabi
mffap
Silvan
Fabi
parent
40d7dba574
commit
220c8e4922
@@ -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)
|
||||
@@ -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>
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user