mirror of
https://github.com/zitadel/zitadel.git
synced 2024-12-12 02:54:20 +00:00
docs(action): specify docs (#4709)
* docs: add actions section * docs(actions): add modules * docs: actions * docs(actions): start with register flows * add calls * docs: all actions documented * docs(actions): unify * docs(actions): unify texts * docs: apply suggestions from code review Co-authored-by: mffap <mpa@zitadel.com> * docs(actions): clarifications * docs: return values italic * docs: fix broken links * docs: fix broken links * docs: fix broken links * docs: fix broken links * Update docs/docs/apis/actions/introduction.md Co-authored-by: mffap <mpa@zitadel.com> * docs(actions): link actions examples * docs: remove unused section Co-authored-by: mffap <mpa@zitadel.com> Co-authored-by: Florian Forster <florian@zitadel.com>
This commit is contained in:
Silvan
GitHub
parent
789faa8ce8
commit
5a1f4c387c
@ -1,107 +0,0 @@
|
||||
---
|
||||
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.com/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.com/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/manage/customize/behavior)
|
||||
- [Actions Marketplace: Find example actions to use in ZITADEL](https://github.com/zitadel/actions)
|
||||
54
docs/docs/apis/actions/introduction.md
Normal file
54
docs/docs/apis/actions/introduction.md
Normal file
@ -0,0 +1,54 @@
|
||||
---
|
||||
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.
|
||||
|
||||
You can find great snippets and examples which show how you can use actions in [this repository](https://github.com/zitadel/actions).
|
||||
|
||||
Actions are a key feature to extend the functionality of ZITADEL and continuously improve the feature and expand the use cases. Check out our [roadmap](https://zitadel.com/roadmap) for more details.
|
||||
|
||||
## Action
|
||||
|
||||
The action object describes the logic defined by the user. Actions can be linked to multiple [triggers](#flows).
|
||||
|
||||
The name of the action must corelate with the javascript function in the code section. This function will be called by ZITADEL.
|
||||
|
||||
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
|
||||
}
|
||||
```
|
||||
|
||||
## Flows
|
||||
|
||||
Flows are the links between an [action](#action) and a specific point during a user interaction with ZITADEL. These specific point are called [Trigger Types](#trigger-types).
|
||||
|
||||
## Trigger Types
|
||||
|
||||
Trigger types define the point during execution of request. Each trigger defines which readable information (`ctx`) and mutual properties (`api`) are passed into the called function as well as which libraries are available for the function. Each trigger type is described in the [available flow types section](#available-flow-types)
|
||||
|
||||
## Available Flow Types
|
||||
|
||||
Currently ZITADEL provides the following flows:
|
||||
|
||||
- [Login](./login-flow.md)
|
||||
- [Register](./register-flow.md)
|
||||
|
||||
## Available Modules inside Javascript
|
||||
|
||||
- [HTTP module](./modules#http) to call API's
|
||||
51
docs/docs/apis/actions/login-flow.md
Normal file
51
docs/docs/apis/actions/login-flow.md
Normal file
@ -0,0 +1,51 @@
|
||||
---
|
||||
title: Login flows
|
||||
---
|
||||
|
||||
## Complement Token
|
||||
|
||||
This flow is executed during the creation of tokens and token introspection.
|
||||
|
||||
### Pre Userinfo creation
|
||||
|
||||
This trigger is called before userinfo are set in the token or response.
|
||||
|
||||
#### Parameters of Pre Userinfo creation
|
||||
|
||||
- `ctx`
|
||||
The first parameter contains the following fields:
|
||||
- `v1`
|
||||
- `user`
|
||||
- `getMetadata()` [*metadataResult*](./objects#metadata-result)
|
||||
- `api`
|
||||
The second parameter contains the following fields:
|
||||
- `v1`
|
||||
- `userinfo`
|
||||
- `setClaim(string, Any)`
|
||||
Key of the claim and any value
|
||||
- `user`
|
||||
- `setMetadata(string, Any)`
|
||||
Key of the metadata and any value
|
||||
|
||||
### Pre access token creation
|
||||
|
||||
This trigger is called before the claims are set in the access token and the token type is `jwt`.
|
||||
|
||||
#### Parameters of Pre access token creation
|
||||
|
||||
- `ctx`
|
||||
The first parameter contains the following fields:
|
||||
- `v1`
|
||||
- `user`
|
||||
- `getMetadata()` [*metadataResult*](./objects#metadata-result)
|
||||
- `api`
|
||||
The second parameter contains the following fields:
|
||||
- `v1`
|
||||
- `claims`
|
||||
- `setClaim(string, Any)`
|
||||
Sets any value if the key is not already present
|
||||
- `appendLogIntoClaims(string)`
|
||||
Appends the entry into the claim `urn:zitadel:action:{action.name}:log` the value of the claim is an Array of *string*
|
||||
- `user`
|
||||
- `setMetadata(string, Any)`
|
||||
Key of the metadata and any value
|
||||
53
docs/docs/apis/actions/modules.md
Normal file
53
docs/docs/apis/actions/modules.md
Normal file
@ -0,0 +1,53 @@
|
||||
---
|
||||
title: Modules
|
||||
---
|
||||
|
||||
ZITADEL provides the following modules.
|
||||
|
||||
## HTTP
|
||||
|
||||
This module provides functionality to call REST APIs.
|
||||
|
||||
### Import
|
||||
|
||||
```js
|
||||
let http = require('zitadel/http')
|
||||
```
|
||||
|
||||
### `fetch()` function
|
||||
|
||||
This function allows to call HTTP servers. The function does NOT fulfil the [Fetch API specification](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API).
|
||||
|
||||
#### Parameters
|
||||
|
||||
- `url` *string*
|
||||
- `options`
|
||||
**Optional**, containing custom settings that you want to apply to the request.
|
||||
- `headers`
|
||||
Overwrites the default headers. One of the following types
|
||||
- *map[string] string*
|
||||
The value is split into separate values after each comma `,`.
|
||||
- *map[string] Array of string*
|
||||
The value is a string array
|
||||
- default:
|
||||
- `Content-Type`: `application/json`
|
||||
- `Accept`: `application/json`
|
||||
- `method`
|
||||
The request method. Allowed values are `GET`, `POST`, `PUT`, `DELETE`
|
||||
- `body` *Object*
|
||||
JSON representation
|
||||
|
||||
#### Response
|
||||
|
||||
If the request was valid, an error will be thrown, otherwise a Response object will be returned.
|
||||
|
||||
The object has the following fields and methods:
|
||||
|
||||
- `status` *number*
|
||||
Status code of response
|
||||
- `body` *string*
|
||||
Return value
|
||||
- `json()` *Object*
|
||||
Returns the body as JSON object, or throws an error if the body is not a json object.
|
||||
- `text()` *string*
|
||||
Returns the body
|
||||
110
docs/docs/apis/actions/objects.md
Normal file
110
docs/docs/apis/actions/objects.md
Normal file
@ -0,0 +1,110 @@
|
||||
---
|
||||
title: Objects
|
||||
---
|
||||
|
||||
## External User
|
||||
|
||||
- `externalId` *string*
|
||||
User id from the identity provider
|
||||
- `externalIdpId` *string*
|
||||
Id of the identity provider
|
||||
- `human`
|
||||
- `firstName` *string*
|
||||
- `lastName` *string*
|
||||
- `nickName` *string*
|
||||
- `displayName` *string*
|
||||
- `preferredLanguage` *string*
|
||||
In [RFC 5646](https://www.rfc-editor.org/rfc/rfc5646) fromat
|
||||
- `email` *string*
|
||||
- `isEmailVerified` *boolean*
|
||||
- `phone` *string*
|
||||
- `isPhoneVerified` *boolean*
|
||||
|
||||
## metadata with value as bytes
|
||||
|
||||
- `key` *string*
|
||||
- `value` Array of *byte*
|
||||
|
||||
## metadata result
|
||||
|
||||
- `count` *number*
|
||||
- `sequence` *number*
|
||||
- `timestamp` *Date*
|
||||
- `metadata` Array of [*metadata*](#metadata)
|
||||
|
||||
## metadata
|
||||
|
||||
- `creationDate` *Date*
|
||||
- `changeDate` *Date*
|
||||
- `resourceOwner` *string*
|
||||
- `sequence` *number*
|
||||
- `key` *string*
|
||||
- `value` `Any`
|
||||
|
||||
## user grant
|
||||
|
||||
- `projectId` *string*
|
||||
Required. Id of the project to be granted
|
||||
- `projectGrantId` *string*
|
||||
If the grant is for a project grant
|
||||
- `roles` Array of *string*
|
||||
Containing the roles
|
||||
|
||||
## user
|
||||
|
||||
- `id` *string*
|
||||
- `creationDate` *Date*
|
||||
- `changeDate` *Date*
|
||||
- `resourceOwner` *string*
|
||||
- `sequence` *number*
|
||||
Unsigned 64 bit integer
|
||||
- `state` *number*
|
||||
<ul><li>0: unspecified</li><li>1: active</li><li>2: inactive</li><li>3: deleted</li><li>4: locked</li><li>5: suspended</li><li>6: initial</li></ul>
|
||||
- `username` *string*
|
||||
- `loginNames` Array of *string*
|
||||
- `preferredLoginName` *string*
|
||||
- `human`
|
||||
Set if the user is human
|
||||
- `firstName` *string*
|
||||
- `lastName` *string*
|
||||
- `nickName` *string*
|
||||
- `displayName` *string*
|
||||
- `avatarKey` *string*
|
||||
- `preferredLanguage` *string*
|
||||
In [RFC 5646](https://www.rfc-editor.org/rfc/rfc5646) fromat
|
||||
- `gender` *number*
|
||||
<ul><li>0: unspecified</li><li>1: female</li><li>2: male</li><li>3: diverse</li></ul>
|
||||
- `email` *string*
|
||||
- `isEmailVerified` *boolean*
|
||||
- `phone` *string*
|
||||
- `isPhoneVerified` *boolean*
|
||||
- `machine`
|
||||
Set if the user is a machine
|
||||
- `name` *string*
|
||||
- `description` *string*
|
||||
|
||||
## human user
|
||||
|
||||
- `id` *string*
|
||||
- `creationDate` *Date*
|
||||
- `changeDate` *Date*
|
||||
- `resourceOwner` *string*
|
||||
- `sequence` *number*
|
||||
- `state` *number*
|
||||
<ul><li>0: unspecified</li><li>1: active</li><li>2: inactive</li><li>3: deleted</li><li>4: locked</li><li>5: suspended</li><li>6: initial</li></ul>
|
||||
- `username` *string*
|
||||
- `loginNames` Array of *string*
|
||||
- `preferredLoginName` *string*
|
||||
- `profile`
|
||||
- `firstName` *string*
|
||||
- `lastName` *string*
|
||||
- `nickName` *string*
|
||||
- `displayName` *string*
|
||||
- `preferredLanguage` *string*
|
||||
In [RFC 5646](https://www.rfc-editor.org/rfc/rfc5646) fromat
|
||||
- `email`
|
||||
- `email` *string*
|
||||
- `isEmailVerified` *boolean*
|
||||
- `phone`
|
||||
- `phone` *string*
|
||||
- `isPhoneVerified` *boolean*
|
||||
112
docs/docs/apis/actions/register-flow.md
Normal file
112
docs/docs/apis/actions/register-flow.md
Normal file
@ -0,0 +1,112 @@
|
||||
---
|
||||
title: Register flows
|
||||
---
|
||||
|
||||
## External Authentication
|
||||
|
||||
This flow is executed if the user logs in using an [identity provider](../../guides/integrate/identity-brokering) or using a [jwt token](../../concepts/structure/jwt_idp).
|
||||
|
||||
### Post Authentication
|
||||
|
||||
A user has authenticated externally. ZITADEL retrieved and mapped the external information.
|
||||
|
||||
#### Parameters of post authentication action
|
||||
|
||||
- `ctx`
|
||||
The first parameter contains the following fields
|
||||
- `accessToken` *string*
|
||||
The access token which will be returned to the user. This can be an opaque token or a JWT
|
||||
- `claimsJSON()` [*idTokenClaims*](../openidoauth/claims)
|
||||
Returns all claims of the id token
|
||||
- `getClaim(key)` *Any*
|
||||
Returns the requested [id token claim](../openidoauth/claims)
|
||||
- `idToken` *string*
|
||||
The id token which will be returned to the user
|
||||
- `v1`
|
||||
- `externalUser()` [*externalUser*](./objects#external-user)
|
||||
- `api`
|
||||
The second parameter contains the following fields
|
||||
- `v1`
|
||||
- `user`
|
||||
- `appendMetadata(string, Any)`
|
||||
The first parameter represents the key and the second a value which will be stored
|
||||
- `setFirstName(string)`
|
||||
Sets the first name
|
||||
- `setLastName(string)`
|
||||
Sets the last name
|
||||
- `setNickName(string)`
|
||||
Sets the nickname
|
||||
- `setDisplayName(string)`
|
||||
Sets the display name
|
||||
- `setPreferredLanguage(string)`
|
||||
Sets the preferred language. Please use the format defined in [RFC 5646](https://www.rfc-editor.org/rfc/rfc5646)
|
||||
- `setPreferredUsername(string)`
|
||||
Sets the preferred username
|
||||
- `setEmail(string)`
|
||||
Sets the email address of the user
|
||||
- `setEmailVerified(boolean)`
|
||||
Sets the email address verified or unverified
|
||||
- `setPhone(string)`
|
||||
Sets the phone number of the user
|
||||
- `setPhoneVerified(boolean)`
|
||||
Sets the phone number verified or unverified
|
||||
- `metadata`
|
||||
Array of [*metadata*](./objects#metadata-with-value-as-bytes). This function is deprecated, please use `api.v1.user.appendMetadata`
|
||||
|
||||
### Pre Creation
|
||||
|
||||
A user selected **Register** on the overview page after external authentication. ZITADEL did not create the user yet.
|
||||
|
||||
#### Parameters of Pre Creation
|
||||
|
||||
- `ctx`
|
||||
The first parameter contains the following fields
|
||||
- `v1`
|
||||
- `user` [*human*](./objects#human-user)
|
||||
- `api`
|
||||
The second parameter contains the following fields
|
||||
- `metadata`
|
||||
Array of [*metadata*](./objects#metadata-with-value-as-bytes). This function is deprecated, please use `api.v1.user.appendMetadata`
|
||||
- `setFirstName(string)`
|
||||
Sets the first name
|
||||
- `setLastName(string)`
|
||||
Sets the last name
|
||||
- `setNickName(string)`
|
||||
Sets the nick name
|
||||
- `setDisplayName(string)`
|
||||
Sets the display name
|
||||
- `setPreferredLanguage(string)`
|
||||
Sets the preferred language, the string has to be a valid language tag as defined in [RFC 5646](https://www.rfc-editor.org/rfc/rfc5646)
|
||||
- `setGender(int)`
|
||||
Sets the gender.
|
||||
<ul><li>0: unspecified</li><li>1: female</li><li>2: male</li><li>3: diverse</li></ul>
|
||||
- `setUsername(string)`
|
||||
Sets the username
|
||||
- `setEmail(string)`
|
||||
Sets the email
|
||||
- `setEmailVerified(bool)`
|
||||
If true the email set is verified without user interaction
|
||||
- `setPhone(string)`
|
||||
Sets the phone number
|
||||
- `setPhoneVerified(bool)`
|
||||
If true the phone number set is verified without user interaction
|
||||
- `v1`
|
||||
- `user`
|
||||
- `appendMetadata(string, Any)`
|
||||
The first parameter represents the key and the second a value which will be stored
|
||||
|
||||
### Post Creation
|
||||
|
||||
A user selected **Register** on the overview page after external authentication and ZITADEL successfully created the user.
|
||||
|
||||
#### Parameters of Post Creation
|
||||
|
||||
- `ctx`
|
||||
The first parameter contains the following fields
|
||||
- `v1`
|
||||
- `getUser()` [*user*](./objects#user)
|
||||
- `api`
|
||||
The second parameter contains the following fields
|
||||
- `userGrants` Array of [*userGrant*](./objects#user-grant)'s
|
||||
- `v1`
|
||||
- `appendUserGrant(`[`userGrant`](./objects#user-grant)`)`
|
||||
@ -35,5 +35,5 @@ 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/manage/customize/behavior)
|
||||
- [Actions reference](../../apis/actions)
|
||||
- [Actions Marketplace: Find example actions to use in ZITADEL](https://github.com/zitadel/actions)
|
||||
- [Actions reference](../../apis/actions/introduction#action)
|
||||
- [Actions Marketplace: Find example actions to use in ZITADEL](https://github.com/zitadel/actions)
|
||||
|
||||
@ -36,13 +36,13 @@ https://github.com/zitadel/actions/blob/main/examples/add_user_grant.js
|
||||
|
||||
## Run the action when a user registers
|
||||
|
||||
Now, make the action hook into the [external authentication flow](../../../apis/actions#external-authentication-flow).
|
||||
Now, make the action hook into the [external authentication flow](../../../apis/actions/register-flow#external-authentication).
|
||||
|
||||
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.
|
||||
2. Select the **Flow Type** *External Authentication*.
|
||||
3. Select the **Trigger Type** *Post Creation*.
|
||||
4. In the **Actions** dropdown, check *addGrant*.
|
||||
5. Select the **Save** button.
|
||||
|
||||
<!-- TODO: ## Test if your action works -->
|
||||
|
||||
@ -51,4 +51,4 @@ New users automatically are assiged a role now if they register by authenticatin
|
||||
## 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)
|
||||
- [Read more about all the options you have with actions](../../../apis/actions/introduction)
|
||||
@ -228,7 +228,6 @@ module.exports = {
|
||||
collapsed: true,
|
||||
items: ["apis/assets/assets"],
|
||||
},
|
||||
"apis/actions",
|
||||
],
|
||||
},
|
||||
{
|
||||
@ -249,6 +248,18 @@ module.exports = {
|
||||
collapsed: false,
|
||||
items: ["apis/saml/endpoints"],
|
||||
},
|
||||
{
|
||||
type: "category",
|
||||
label: "Actions",
|
||||
collapsed: false,
|
||||
items: [
|
||||
"apis/actions/introduction",
|
||||
"apis/actions/modules",
|
||||
"apis/actions/login-flow",
|
||||
"apis/actions/register-flow",
|
||||
"apis/actions/objects",
|
||||
]
|
||||
},
|
||||
{
|
||||
type: "category",
|
||||
label: "Observability",
|
||||
|
||||
Loading…
Reference in New Issue
Block a user