docs: general fixes to links who where broken and some lint and typos (#4144)

This commit is contained in:
Florian Forster 2022-08-08 16:02:47 +02:00 committed by GitHub
parent 2746b4f3a7
commit d6cb1e521d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
14 changed files with 44 additions and 209 deletions

View File

@ -227,7 +227,7 @@ Send a client assertion as JWT for us to validate the signature against the regi
| ---------- | ----------------------------------------------------------------------------------------------------------------------------- |
| grant_type | Must be `urn:ietf:params:oauth:grant-type:jwt-bearer` |
| assertion | JWT built and signed according to [Using JWTs for Authorization Grants](grant-types#using-jwts-as-authorization-grants) |
| scope | [Scopes](Scopes) you would like to request from ZITADEL. Scopes are space delimited, e.g. `openid email profile` |
| scope | [Scopes](scopes) you would like to request from ZITADEL. Scopes are space delimited, e.g. `openid email profile` |
```BASH
curl --request POST \
@ -250,7 +250,7 @@ curl --request POST \
### Refresh Token Grant
To request a new `access_token` without user interaction, you can use the `refresh_token` grant.
See [offline_access Scope](Scopes#standard-scopes) for how to request a `refresh_token` in the authorization request.
See [offline_access Scope](scopes#standard-scopes) for how to request a `refresh_token` in the authorization request.
#### Required request Parameters
@ -258,7 +258,7 @@ See [offline_access Scope](Scopes#standard-scopes) for how to request a `refresh
| ------------- | -------------------------------------------------------------------------------------------- |
| grant_type | Must be `refresh_token` |
| refresh_token | The refresh_token previously issued in the last authorization_code or refresh_token request. |
| scope | [Scopes](Scopes) you would like to request from ZITADEL for the new access_token. Must be a subset of the scope originally requested by the corresponding auth request. When omitted, the scopes requested by the original auth request will be reused. Scopes are space delimited, e.g. `openid email profile` |
| scope | [Scopes](scopes) you would like to request from ZITADEL for the new access_token. Must be a subset of the scope originally requested by the corresponding auth request. When omitted, the scopes requested by the original auth request will be reused. Scopes are space delimited, e.g. `openid email profile` |
Depending on your authorization method you will have to provide additional parameters or headers:

View File

@ -2994,7 +2994,7 @@ This is an empty request
| Field | Type | Description | Validation |
| ----- | ---- | ----------- | ----------- |
| primary_color | string | - | string.max_len: 50<br /> |
| hide_login_name_suffix | bool | hides the org suffix on the login form if the scope \"urn:zitadel:iam:org:domain:primary:{domainname}\" is set. Details about this scope in https://docs.zitadel.com/concepts#Reserved_Scopes | |
| hide_login_name_suffix | bool | hides the org suffix on the login form if the scope \"urn:zitadel:iam:org:domain:primary:{domainname}\" is set. Details about this [scope in](../openidoauth/scopes) | |
| warn_color | string | - | string.max_len: 50<br /> |
| background_color | string | - | string.max_len: 50<br /> |
| font_color | string | - | string.max_len: 50<br /> |

View File

@ -33,7 +33,7 @@ title: zitadel/policy.proto
| details | zitadel.v1.ObjectDetails | - | |
| primary_color | string | hex value for primary color | |
| is_default | bool | defines if the organisation's admin changed the policy | |
| hide_login_name_suffix | bool | hides the org suffix on the login form if the scope \"urn:zitadel:iam:org:domain:primary:{domainname}\" is set. Details about this scope in https://docs.zitadel.com/concepts#Reserved_Scopes | |
| hide_login_name_suffix | bool | hides the org suffix on the login form if the scope \"urn:zitadel:iam:org:domain:primary:{domainname}\" is set. Details about this [scope in](../openidoauth/scopes) | |
| warn_color | string | hex value for secondary color | |
| background_color | string | hex value for background color | |
| font_color | string | hex value for font color | |

View File

@ -11,7 +11,7 @@ At the end of the guide you should have an application able to login a user and
Before we can start building our application we have to do a few configuration steps in ZITADEL Console.
You will need to provide some information about your app. We recommend creating a new app to start from scratch. Navigate to your Project and add a new application at the top of the page.
Select User Agent and continue. More about the different app types can you find [here](https://docs.zitadel.com/docs/guides/authorization/oauth-recommended-flows#different-client-profiles).
Select User Agent and continue. More about the different app types can you find [here](../../guides/integrate/oauth-recommended-flows#different-client-profiles).
We recommend that you use [Authorization Code](../../apis/openidoauth/grant-types#authorization-code) in combination with [Proof Key for Code Exchange](../../apis/openidoauth/grant-types#proof-key-for-code-exchange) for all web applications.
### Redirect URLs

View File

@ -2,32 +2,6 @@
title: Access ZITADEL APIs
---
<table class="table-wrapper">
<tr>
<td>Description</td>
<td>Learn how to authorize Service Users to access ZITADEL APIs.</td>
</tr>
<tr>
<td>Learning Outcomes</td>
<td>
In this module you will:
<ul>
<li>Grant a Service User for ZITADEL</li>
<li>Authorize a Service User with JWT signed with your private key</li>
</ul>
</td>
</tr>
<tr>
<td>Prerequisites</td>
<td>
<ul>
<li>Knowledge of <a href="/docs/guides/integrate/oauth-recommended-flows">Recommended Authorization Flows</a></li>
<li>Knowledge of <a href="/docs/guides/integrate/serviceusers">Service Users</a></li>
</ul>
</td>
</tr>
</table>
:::note
This guide focuses on the Admin, Auth and Management APIs. To access the ZITADEL System API, please checkout [this guide](./access-zitadel-system-api).
:::
@ -44,7 +18,7 @@ ZITADEL Managers are Users who have permission to manage ZITADEL itself. There a
On each level we have some different Roles. Here you can find more about the different roles: [ZITADEL Manager Roles](../../concepts/structure/managers.md)
## Exercise: Add ORG_OWNER to Service User
## Add ORG_OWNER to Service User
Make sure you have a Service User with a Key. (For more detailed informations about creating a service user go to [Service User](serviceusers.md))
@ -96,31 +70,6 @@ Content-Type: application/json
```
With this token you are allowed to access the [ZITADEL APIs](../../apis/introduction) .
## Knowledge Check
* Managers are used for all users to get authorizations for all projects?
- [ ] yes
- [ ] no
* You need the ZITADEL Project Id in your audience and can access this with a custom scope?
- [ ] yes
- [ ] no
<details>
<summary>
Solutions
</summary>
* Managers are used for all users to get authorizations for all projects?
- [ ] yes
- [x] no (Managers are only used to grant users for ZITADEL)
* You need the ZITADEL Project Id in your audience and can access this with a custom scope?
- [x] yes
- [ ] no
</details>
## Summary
@ -128,7 +77,6 @@ With this token you are allowed to access the [ZITADEL APIs](../../apis/introduc
* Because there is no interactive logon, you need to use a JWT signed with your private key to authorize the user
* With a custom scope (`urn:zitadel:iam:org:project:id:{projectid}:aud`) you can access ZITADEL APIs
Where to go from here:
* [ZITADEL API Documentation](../../apis/introduction)

View File

@ -2,32 +2,6 @@
title: Identity Brokering
---
<table class="table-wrapper">
<tr>
<td>Description</td>
<td>Learn about identity brokering/federation and how to add an external identity provider to authenticate your users.</td>
</tr>
<tr>
<td>Learning Outcomes</td>
<td>
In this module you will:
<ul>
<li>Learn about Identity Providers</li>
<li>Add a new identity provider</li>
<li>Example with Google Login</li>
</ul>
</td>
</tr>
<tr>
<td>Prerequisites</td>
<td>
<ul>
<li>Knowledge of <a href="/docs/guides/manage/console/organizations">Organizations</a></li>
</ul>
</td>
</tr>
</table>
## What is Identity Brokering and Federated Identities?
Federated identity management is an arrangement built upon the trust between two or more domains. Users of these domains are allowed to access applications and services using the same identity.
@ -43,9 +17,9 @@ Because Google is registered as trusted identity provider the user will be able
![Identity Brokering](/img/guides/identity_brokering.png)
## Exercise: Register an external identity provider
## Register an external identity provider
In this exercise we will add a new Google identity provider to federate identities with ZITADEL.
In this step we will add a new Google identity provider to federate identities with ZITADEL.
### 1. Create new OIDC Client
@ -58,7 +32,7 @@ In this exercise we will add a new Google identity provider to federate identiti
Google Example:
1. Go to the Google Gloud Platform and choose youre project: <https://console.cloud.google.com/apis/credentials>
1. Go to the Google Cloud Platform and choose your project: <https://console.cloud.google.com/apis/credentials>
2. Click on "+ CREATE CREDENTIALS" and choose "OAuth client ID"
3. Choose Web application as Application type and give a name
4. Add the redirect uris
@ -74,7 +48,7 @@ The login policy can be configured on two levels. Once as default on the instanc
This case describes how to change it on the organization.
1. Go to your organization settings by clicking on "Organization" in the menu
2. Modify your login policy in the menu "Login Behaviour and Security"
2. Modify your login policy in the menu "Login Behavior and Security"
![Add custom login policy](/img/console_org_custom_login_policy.gif)
@ -93,7 +67,7 @@ This case describes how to change it on the organization.
![Configure identity provider](/img/console_org_identity_provider.gif)
### 4. Send the primary domain scope on the authorization request
ZITADEL will show a set of identity providers by default. This configuration can be changed by users with the [manager role] (https://docs.zitadel.com/docs/concepts/zitadel/objects/managers) `IAM_OWNER`.
ZITADEL will show a set of identity providers by default. This configuration can be changed by users with the [manager role](../../concepts/structure/managers) `IAM_OWNER`.
An organization's login settings will be shown
@ -103,9 +77,7 @@ To get your own configuration you will have to send the [primary domain scope](.
The primary domain scope will restrict the login to your organization, so only users of your own organization will be able to login, also your branding and policies will trigger.
:::note
You need to create your own auth request with your applications parameters. Please see the docs to construct an [Auth Request](../../guides/integrate/login-users#auth-request).
:::
Your user will now be able to choose Google for login instead of username/password or mfa.

View File

@ -56,7 +56,7 @@ So what do we want to achieve with delegated authentication?
* Instead of sending around the users credentials
* Clients may access protected resources with an **access token** that is only valid for specific scope and limited lifetime (OAuth 2.x)
* Users have to **authorize** applications to access certain [**scopes**](https://docs.zitadel.com/architecture#Scopes) (eg, email address or custom roles). Applications can request [**claims**](https://docs.zitadel.com/architecture#Claims) (key:value pairs, eg email address) for the authorized scopes with the access token or ID token from ZITADEL
* Users have to **authorize** applications to access certain [**scopes**](../../apis/openidoauth/scopes) (eg, email address or custom roles). Applications can request [**claims**](../../apis/openidoauth/claims) (key:value pairs, eg email address) for the authorized scopes with the access token or ID token from ZITADEL
* Access tokens are bearer tokens, meaning that possession of the token provides access to a resource. But the tokens expire frequently and the application must request a new access token via **refresh token** or the user must reauthenticate
![Overview federated identities](/img/guides/consulting_federated_identities_basics.png)
@ -115,7 +115,7 @@ If you dont have any technical limitations, you should favor the flow Authori
We recommend using **“JWT bearer token with private key”** ([RFC7523](https://tools.ietf.org/html/rfc7523)) for Machine-to-Machine clients.
What this means is that you have to send an JWT token, containing the [standard claims for access tokens](https://docs.zitadel.com/architecture#Claims) and that is signed with your private key, to the token endpoint to request the access token. We will see how this works in another module about Service Accounts.
What this means is that you have to send an JWT token, containing the [standard claims for access tokens](../../apis/openidoauth/claims) and that is signed with your private key, to the token endpoint to request the access token. We will see how this works in another module about Service Accounts.
If you dont have any technical limitations, you should prefer this method over other methods.
@ -123,35 +123,6 @@ A JWT with a private key can also be used with client profile web to further enh
In case you need alternative flows and their advantages and drawbacks, there will be a module to outline more methods and our recommended fallback strategy per client profile that are available in ZITADEL.
## Knowledge Check (3)
* With federated identities the user sends credentials to the server holding the protected resource
- [ ] yes
- [ ] no
* ZITADEL will discover your client profile automatically and set the correct flow
- [ ] yes
- [ ] no
* When working with APIs / machine-to-machine communication its recommended to exchange a JWT that is singed with your private key for an access token
- [ ] yes
- [ ] no
<details>
<summary>
Solutions
</summary>
* With federated identities the user sends credentials to the server holding the protected resource
- [ ] yes
- [x] no (Users are authenticated against a centralized IDP, only access tokens are send to the requested resources)
* ZITADEL will discover your client profile automatically and set the correct flow
- [ ] yes
- [x] no (ZITADEL does not make any assumptions about your applications requirements)
* When working with APIs / machine-to-machine communication its recommended to exchange a JWT that is singed with your private key for an access token
- [x] yes
- [ ] no
</details>
## Summary (3)
* Federated Identities solve key problems and challenges with traditional server-client architecture
@ -159,7 +130,7 @@ In case you need alternative flows and their advantages and drawbacks, there wil
* “JWT bearer token with private key” for Machine-to-Machine clients
* There are alternative flows and fallback strategies supported by ZITADEL, if these flows are technically not possible
Where to go from here
### Where to go from here
* Applications
* Service Accounts

View File

@ -2,38 +2,11 @@
title: Service Users
---
<table class="table-wrapper">
<tr>
<td>Description</td>
<td>Learn the basics about ZITADEL Service Users, how to set them up and authorize with ZITADEL.</td>
</tr>
<tr>
<td>Learning Outcomes</td>
<td>
In this module you will:
<ul>
<li>Learn about Service Users</li>
<li>Create a Service User in ZITADEL Console</li>
<li>Authorize a Service User with JWT signed with your private key</li>
</ul>
</td>
</tr>
<tr>
<td>Prerequisites</td>
<td>
<ul>
<li>Knowledge of <a href="/docs/guides/integrate/oauth-recommended-flows">Recommended Authorization Flows</a></li>
</ul>
</td>
</tr>
</table>
import UserDescription from '../../concepts/structure/_user_description.mdx';
<UserDescription name="UserDescription" />
## Exercise: Create a Service User
## Create a Service User
1. Navigate to Service Users
2. Click on **New**
@ -53,9 +26,9 @@ You need to follow these steps to authenticate a service user and receive a acce
With this token you can make subsequent requests, just like a human user.
## Exercise: Get an access token
## Get an access token
In this exercise we will authenticate a service user and receive an access_token to use against a API.
In this step we will authenticate a service user and receive an access_token to use against a API.
> **Information:** Are you stuck? Don't hesitate to reach out to us on [Github Discussions](https://github.com/zitadel/zitadel/discussions) or [contact us](https://zitadel.com/contact/) privately.
@ -145,7 +118,7 @@ Content-Type: application/json
### 4. Verify that you have a valid access token
For this example let's call the userinfo endpoint to verfiy that our access token works.
For this example let's call the userinfo endpoint to verify that our access token works.
```bash
curl --request POST \
@ -167,35 +140,6 @@ Content-Type: application/json
}
```
## Knowledge Check
* To secure backend APIs you can request an API key via ZITADEL's console
- [ ] yes
- [ ] no
* The JWT header must contain a property `kid` with the value of the key ID
- [ ] yes
- [ ] no
* After generating a key for your service user, you must download the public key and sign your JWT with the public key
- [ ] yes
- [ ] no
<details>
<summary>
Solutions
</summary>
* To secure backend APIs you can request an API key via ZITADEL's console
- [ ] yes
- [x] no (We use **“JWT bearer token with private key”**, [RFC7523](https://tools.ietf.org/html/rfc7523))
* The JWT header must contain a property `kid` with the value of the key ID
- [x] yes
- [ ] no
* After generating a key for your service user, you must download the public key and sign your JWT with the public key
- [ ] yes
- [x] no (The json file contains the private key. Handle with care.)
</details>
## Summary
* With service users you can secure machine-to-machine communication

View File

@ -11,7 +11,7 @@ import Column from '../../../../src/components/column';
There are several more modules in our documentation to go into more detail regarding organization management, projects, clients, and users. But first lets create a new organization and verify your domain name.
## Exercise - Create a new organization
## Create a new organization
To create a new organization login to your ZITADEL instance ({your-domain}-{random string}.zitadel.cloud or your custom domain).
Click the organization drop down in the name in the upper left corner in the header, and then select “New organization”.

View File

@ -8,6 +8,7 @@ The second possibility is to configure it on each organization. This guide will
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.
@ -18,49 +19,52 @@ After this your settings will trigger in your system. The login and the emails w
![Private Labeling](/img/console_private_labeling.png)
### 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.
Send a [primary domain scope](../../../apis/openidoauth/scopes) with your [authorization request](../../integrate/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).
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]../integrate/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.

View File

@ -17,14 +17,14 @@ Typical examples for user metadata include:
### Create a new client
- Create a new [web application](https://docs.zitadel.com/docs/guides/start/applications#web)
- Create a new [web application](../console/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
- [Add metadata](../../../manuals/user-profile#metadata) to a user
- Make sure you will use this user to login during later steps
## Requesting a token
@ -47,7 +47,7 @@ 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:
Grab zitadel-tools to create the [required string](../../../apis/openidoauth/authn-methods#client-secret-basic) for Basic authentication:
```bash
git clone git@github.com:zitadel/zitadel-tools.git
@ -93,7 +93,7 @@ Export the result to the environment variable `BASIC_AUTH`.
<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).
You need to create a string as described [here](../../../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:
@ -107,7 +107,7 @@ Export the result to the environment variable `BASIC_AUTH`.
### 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).
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](../../../apis/openidoauth/scopes#reserved-scopes).
<Tabs>

View File

@ -103,6 +103,6 @@ Read more about Authorization in our [Guide](../integrate/oauth-recommended-flow
## Learn more
- [Creating an organization](../manage/console/organizations#exercise---create-a-new-organization)
- [Creating an organization](../manage/console/organizations#create-a-new-organization)
- [Organization Branding](../manage/customize/branding)
- [Authorization](../integrate/oauth-recommended-flows)

View File

@ -20,7 +20,6 @@ All documents will be provided in English language.
</ListWrapper>
<ListWrapper title="Annexes">
<ListElement link="/docs/legal/support-services" type={ICONTYPE.POLICY} title="Support Services" description="Support services offered by ZITADEL and CAOS Ltd." />
<ListElement link="/docs/legal/dedicated-instance-annex" type={ICONTYPE.POLICY} title="Dedicated Instance Annex" description="Services and Guarantees for dedicated instances" />
<ListElement link="/docs/legal/acceptable-use-policy" type={ICONTYPE.POLICY} title="Acceptable Use Policy" description="Obligations while using ZITADEL Services" />
<ListElement link="/docs/legal/rate-limit-policy" type={ICONTYPE.POLICY} title="Rate Limit Policy" description="How ZITADEL will use rate limiting" />
</ListWrapper>

View File

@ -4,23 +4,23 @@ title: User Register
## Organization and user registration
Zitadel allows users to register a organization and/or user with just a few steps.
ZITADEL allows users to register a organization and/or user with just a few steps.
A. Register an organization
1. Create an organization
2. Verify your email
3. Login to Zitadel and manage the organization
3. Login to ZITADEL and manage the organization
B. Create User
1. An administrator can create and manage users within console.
C. Enable selfregistration for User
C. Enable Self Registration for User
1. Create an organization as above
2. Create custom policy
3. Enable the "Register allowed" flag in the Login Policy
4. Connect your application and add the applications [scope](https://docs.zitadel.com/architecture/#Custom_Scopes) to the redirect URL.
4. Connect your application and add the applications [scope](../apis/openidoauth/scopes) to the redirect URL.
This will enable the register option in the login dialog and will register the user within your organization if he does not already have an account.
@ -32,16 +32,13 @@ Create User
![Create User](/img/create-user.gif)
Enable Selfregister
Enable Self Register
![Enable Selfregister](/img/enable-selfregister.gif)
## Self Register
When self registration is enabled, users can register themselfes in the organanization without any administrative effort.
When self registration is enabled, users can register themselves in the organization without any administrative effort.
Self Register
![Self Register](/img/self-register.gif)