mirror of
https://github.com/andwati/zitadel.git
synced 2026-11-06 22:32:16 +00:00
docs: improve documentation for v2 release (#4046)
* WIP: docs(proxy): describe proxy settings * fix nginx * refactor (docs): deploy and operate sections * chore: ignore package-lock since we use yarn * chore: update to rc1 * chore: broken links * chore: update yarn * docs: move disclaimer to bottom * chore: fix broken links * Update docs/docs/guides/operate/tls_modes.mdx Co-authored-by: Fabi <[email protected]> * test caddy files * syntax highlight * traefik example * refactor: docs * refactor * working state * got a working state * remove bar * mark rate limits for update * remove zitadel.ch * fix cases * docs: zitadel quickstart * docs: zitadel quickstart * docs: create app and project * docs: move customer portal docs to guides manage cloud * docs: move customer portal docs to guides manage cloud * docs: move customer portal docs to guides manage cloud * docs: add help me choose in the quickstart * docs: broken links * fix broken links * Update knative guide * styling * docs: support customer portal * update to main instead v2-alpha * use version 2 tag * docs: images * docs: move authentication and authorization guides to integrate * docs: quickstart use examples * docs: lb example * fix broken link * docs: update userinfo endpoints * docs: update userinfo endpoints * fix oidc endpoint * docs: remove unused endpoints in app.module Co-authored-by: Fabi <[email protected]> Co-authored-by: Fabienne <[email protected]> Co-authored-by: Livio Amstutz <[email protected]>
This commit is contained in:
Florian Forster
co-authored by
Fabi
Fabienne
Livio Amstutz
Fabi
Fabienne
Livio Amstutz
parent
fb52575f79
commit
3c3bce1a6b
@@ -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](../../integrate/identity-brokering)
|
||||
- [You need to have at least one role configured for a project](../console/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)
|
||||
@@ -0,0 +1,66 @@
|
||||
---
|
||||
title: Brand Customization
|
||||
---
|
||||
|
||||
ZITADEL offers various customization options for your projects brand design. The branding can be configured on two different levels.
|
||||
The configuration on the instance level will set the default settings, which are triggered for all users if not overwritten on an organization specifically.
|
||||
The second possibility is to configure it on each organization. This guide will describe the second possibility.
|
||||
For this head over to the Branding Setting on your Organization Page.
|
||||
|
||||
## How it works
|
||||
You are able to customize the light and a dark mode separately.
|
||||
All your changes will be shown in the preview window on the right side.
|
||||
As soon as you are happy with your configuration click the "Apply configuration" button.
|
||||
After this your settings will trigger in your system. The login and the emails will be sent with your branding.
|
||||
|
||||
## Settings
|
||||
|
||||
|
||||
|
||||
### Logo
|
||||
Upload your logo for the chosen theme, as soon as it is uploaded the preview on the right side of the screen should show it.
|
||||
|
||||
### Colors
|
||||
In the next part you can configure your colors.
|
||||
Background colour is self-explanatory, the primary color will be used for buttons, links and some highlights.
|
||||
The warn color is used for all the error messages and warnings and the font colour for texts.
|
||||
|
||||
### Font
|
||||
Last step to apply to your branding is the font upload.
|
||||
The best way is to upload a ttf file after a successful upload you will see it in the font part, but not in the preview.
|
||||
|
||||
### Advanced Settings
|
||||
In the advanced behavior you can choose if the loginname suffix (domain e.g road.runner@acme.caos.ch) should be shown in the loginname screen or not and if the “ZITADEL watermark” should be hidden.
|
||||
|
||||
## Trigger the private labeling for the login
|
||||
If you like to trigger your settings for your applications you have different possibilities.
|
||||
|
||||
### 1. Primary Domain Scope
|
||||
Send a [primary domain scope](https://docs.zitadel.com/docs/apis/openidoauth/scopes#reserved-scopes) with your [authorization request](https://docs.zitadel.com/docs/guides/authentication/login-users/#auth-request) to trigger your organization.
|
||||
The primary domain scope will restrict the login to your organization, so only users of your own organization will be able to login.
|
||||
|
||||
See the following link as an example. Users will be able to register and login to the organization that verified the @caos.ch domain only.
|
||||
```
|
||||
https://{your_domain.zitadel.cloud}/oauth/v2/authorize?client_id=69234247558357051%40zitadel&scope=openid%20profile%20urn%3Azitadel%3Aiam%3Aorg%3Adomain%3Aprimary%3Acaos.ch&redirect_uri=https%3A%2F%2Fconsole.zitadel.cloud%2Fauth%2Fcallback&state=testd&response_type=code&nonce=test&code_challenge=UY30LKMy4bZFwF7Oyk6BpJemzVblLRf0qmFT8rskUW0
|
||||
```
|
||||
|
||||
:::info
|
||||
|
||||
Make sure to replace the domain `caos.ch` with your own domain to trigger the correct branding.
|
||||
|
||||
:::
|
||||
|
||||
:::caution
|
||||
|
||||
This example uses the ZITADEL Cloud Application for demonstration. You need to create your own auth request with your applications parameters. Please see the docs to construct an [Auth Request](https://docs.zitadel.com/docs/guides/authentication/login-users/#auth-request).
|
||||
|
||||
:::
|
||||
|
||||
|
||||
|
||||
### 2. Setting on your Project
|
||||
Set the private labeling setting on your project to define which branding should trigger.
|
||||
|
||||
## Reset to default
|
||||
If you don't like your customization anymore click the "reset policy" button.
|
||||
All your settings will be removed and the default settings of the system will trigger.
|
||||
@@ -0,0 +1,43 @@
|
||||
---
|
||||
title: Customized Texts
|
||||
---
|
||||
|
||||
You are able to customize the texts used from ZITADEL. This is possibly on the instance or organization level.
|
||||
|
||||
## Message Texts
|
||||
Sometimes the users will get an email or phone message from ZITADEL (e.g Password Reset Request).
|
||||
ZITADEL already has some good standard texts, but maybe you would like to customize it for your organization.
|
||||
|
||||
Go to the message text policy on your organization and you will find the different kinds of messages that are sent from ZITADEL.
|
||||
Choose the template and the language you like to edit.
|
||||
You can now change all the texts from a message.
|
||||
As soon as you click into a input field you will see some attribute chips below the field.
|
||||
These are the parameters you can include on this specific message.
|
||||
|
||||
|
||||
|
||||
## Login Texts
|
||||
|
||||
Like the message texts you are also able to change the texts on the login interface.
|
||||
First choose the screen and the language you like to edit.
|
||||
You will see the default texts in the input field and you can overwrite them by typing into the box.
|
||||
|
||||
|
||||
|
||||
## Reset to default
|
||||
|
||||
If you don't like your customization anymore click the "reset policy" button.
|
||||
All your settings will be removed and the default settings of the system will trigger.
|
||||
|
||||
## Internationalization
|
||||
|
||||
ZITADEL is available in the following languages
|
||||
|
||||
- English (en)
|
||||
- German (de)
|
||||
- Italian (it)
|
||||
- French (fr)
|
||||
|
||||
A language is displayed based on your agent's language header. The default language is English.
|
||||
|
||||
If you need support for a specific language we highly encourage you to [contribute translation files](https://github.com/zitadel/zitadel/blob/main/CONTRIBUTING.md) for the missing language.
|
||||
@@ -0,0 +1,228 @@
|
||||
---
|
||||
title: User Metadata
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
In this guide you will learn how to manually create the necessary requests to authenticate and request a user's metadata from ZITADEL.
|
||||
|
||||
Typical examples for user metadata include:
|
||||
|
||||
- Link the user to an internal identifier (eg, userId, contract number, etc.)
|
||||
- Save custom user data when registering a user
|
||||
- Route upstream traffic based on user attributes
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Create a new client
|
||||
|
||||
- Create a new [web application](https://docs.zitadel.com/docs/guides/start/applications#web)
|
||||
- Use Code-Flow
|
||||
- In this example we will use `http://localhost` as redirect url
|
||||
- Make sure to note the client secret
|
||||
|
||||
### Add metadata to a user
|
||||
|
||||
- [Add metadata](https://docs.zitadel.com/docs/manuals/user-profile#metadata) to a user
|
||||
- Make sure you will use this user to login during later steps
|
||||
|
||||
## Requesting a token
|
||||
|
||||
:::info
|
||||
In this guide we will manually request a token from ZITADEL for demonstration purposes. You will likely use a client library for the OpenID Authentication.
|
||||
:::
|
||||
|
||||
### Set environment variables
|
||||
|
||||
We will use some information throughout this guide. Set the required environment variables as follows. Make sure to replace the values with your information.
|
||||
|
||||
```bash
|
||||
export CLIENT_SECRET=QCiMffalakI...zpT0vuOsSkVk1ne \
|
||||
export CLIENT_ID="16604...@docs-claims" \
|
||||
export REDIRECT_URI="http://localhost" \
|
||||
export ZITADEL_DOMAIN="https://...asd.zitadel.cloud"
|
||||
```
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="go" label="Go" default>
|
||||
|
||||
Grab zitadel-tools to create the [required string](https://docs.zitadel.com/docs/apis/openidoauth/authn-methods#client-secret-basic) for Basic authentication:
|
||||
|
||||
```bash
|
||||
git clone [email protected]:zitadel/zitadel-tools.git
|
||||
cd zitadel-tools/cmd/basicauth
|
||||
export BASIC_AUTH="$(go run basicauth.go -id $CLIENT_ID -secret $CLIENT_SECRET)"
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="python" label="Python">
|
||||
|
||||
```python
|
||||
import base64
|
||||
import urllib.parse
|
||||
import os
|
||||
|
||||
clientId = os.environ.get("CLIENT_ID")
|
||||
clientSecret = os.environ.get("CLIENT_SECRET")
|
||||
|
||||
escaped = safe_string = urllib.parse.quote_plus(clientId) + ":" + urllib.parse.quote_plus(clientSecret)
|
||||
message_bytes = escaped.encode('ascii')
|
||||
base64_bytes = base64.b64encode(message_bytes)
|
||||
base64_message = base64_bytes.decode('ascii')
|
||||
|
||||
print(base64_message)
|
||||
```
|
||||
|
||||
Export the result to the environment variable `BASIC_AUTH`.
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="js" label="Javascript" default>
|
||||
|
||||
```javascript
|
||||
esc = encodeURIComponent(process.env.CLIENT_ID) + ":" + encodeURIComponent(process.env.CLIENT_SECRET)
|
||||
enc = btoa(esc)
|
||||
console.log(enc)
|
||||
```
|
||||
|
||||
Export the result to the environment variable `BASIC_AUTH`.
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="manually" label="Manually">
|
||||
|
||||
You need to create a string as described [here](https://docs.zitadel.com/docs/apis/openidoauth/authn-methods#client-secret-basic).
|
||||
|
||||
Use a programming language of your choice or manually create the strings with online tools (don't use these secrets for production) like:
|
||||
|
||||
- https://www.urlencoder.org/
|
||||
- https://www.base64encode.org/
|
||||
|
||||
Export the result to the environment variable `BASIC_AUTH`.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
### Create Auth Request
|
||||
|
||||
You need to create a valid auth request, including the reserved scope `urn:zitadel:iam:user:metadata`. Please refer to our API documentation for more information about [reserved scopes](https://docs.zitadel.com/docs/apis/openidoauth/scopes#reserved-scopes).
|
||||
|
||||
<Tabs>
|
||||
|
||||
<TabItem value="default" label="Default" default>
|
||||
|
||||
```bash
|
||||
echo "${ZITADEL_DOMAIN}/oauth/v2/authorize?client_id=${CLIENT_ID}&redirect_uri=${REDIRECT_URI}&response_type=code&scope=openid email profile urn:zitadel:iam:user:metadata"
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="macos" label="MacOS">
|
||||
|
||||
```zsh
|
||||
open "${ZITADEL_DOMAIN}/oauth/v2/authorize?client_id=${CLIENT_ID}&redirect_uri=${REDIRECT_URI}&response_type=code&scope=openid email profile urn:zitadel:iam:user:metadata"
|
||||
```
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="WSL" label="WSL">
|
||||
|
||||
```bash
|
||||
wslview "${ZITADEL_DOMAIN}/oauth/v2/authorize?client_id=${CLIENT_ID}&redirect_uri=${REDIRECT_URI}&response_type=code&scope=openid email profile urn:zitadel:iam:user:metadata"
|
||||
```
|
||||
</TabItem>
|
||||
|
||||
</Tabs>
|
||||
|
||||
Login with the user to which you have added the metadata. After the login you will be redirected.
|
||||
|
||||
Grab the code paramter from the url (disregard the &code= parameter) and export the code as environment variable:
|
||||
|
||||
```bash
|
||||
export AUTH_CODE="Y6nWsgR5WB...zUtFqSp5Xw"
|
||||
```
|
||||
|
||||
### Token Request
|
||||
|
||||
```bash
|
||||
curl --request POST \
|
||||
--url "${ZITADEL_DOMAIN}/oauth/v2/token" \
|
||||
--header "Accept: application/json" \
|
||||
--header "Authorization: Basic ${BASIC_AUTH}" \
|
||||
--header 'Content-Type: application/x-www-form-urlencoded' \
|
||||
--data grant_type=authorization_code \
|
||||
--data-urlencode "code=$AUTH_CODE" \
|
||||
--data-urlencode "redirect_uri=$REDIRECT_URI"
|
||||
```
|
||||
|
||||
The result will give you something like:
|
||||
|
||||
```json
|
||||
{
|
||||
"access_token":"jZuRixKQTVecEjKqw...kc3G4",
|
||||
"token_type":"Bearer",
|
||||
"expires_in":43199,
|
||||
"id_token":"ey...Ww"
|
||||
}
|
||||
```
|
||||
|
||||
Grab the access_token value and export as an environment variable:
|
||||
|
||||
```bash
|
||||
export ACCESS_TOKEN="jZuRixKQTVecEjKqw...kc3G4"
|
||||
```
|
||||
|
||||
### Request metadata from userinfo endpoint
|
||||
|
||||
With the access token we can make a request to the userinfo endpoint to get the user's metadata. This method is the preferred method to retrieve a user's information in combination with opaque tokens, to insure that the token is valid.
|
||||
|
||||
```bash
|
||||
curl --request GET \
|
||||
--url "${ZITADEL_DOMAIN}/oidc/v1/userinfo" \
|
||||
--header "Authorization: Bearer $ACCESS_TOKEN"
|
||||
```
|
||||
|
||||
The response will look something like this
|
||||
|
||||
```json
|
||||
{
|
||||
"email":"[email protected]",
|
||||
"email_verified":true,
|
||||
"family_name":"Runner",
|
||||
"given_name":"Road",
|
||||
"locale":"en",
|
||||
"name":"Road Runner",
|
||||
"preferred_username":"[email protected]",
|
||||
"sub":"166.....729",
|
||||
"updated_at":1655467738,
|
||||
//highlight-start
|
||||
"urn:zitadel:iam:user:metadata":{
|
||||
"ContractNumber":"MTIzNA",
|
||||
}
|
||||
//highlight-end
|
||||
}
|
||||
```
|
||||
|
||||
You can grab the metadata from the reserved claim `"urn:zitadel:iam:user:metadata"` as key-value pairs. Note that the values are base64 encoded. So the value `MTIzNA` decodes to `1234`.
|
||||
|
||||
### Send metadata inside the ID token (optional)
|
||||
|
||||
Check "User Info inside ID Token" in the configuration of your application.
|
||||
|
||||
|
||||
|
||||
Now request a new token from ZITADEL.
|
||||
|
||||
The result will give you something like:
|
||||
|
||||
```json
|
||||
{
|
||||
"access_token":"jZuRixKQTVecEjKqw...kc3G4",
|
||||
"token_type":"Bearer",
|
||||
"expires_in":43199,
|
||||
"id_token":"ey...Ww"
|
||||
}
|
||||
```
|
||||
|
||||
Grab the id_token and inspect the contents of the token at [jwt.io](https://jwt.io/). You should get the same info in the ID token as when requested from the user endpoint.
|
||||
Reference in New Issue
Block a user