mirror of
https://github.com/zitadel/zitadel.git
synced 2025-01-06 13:57:41 +00:00
docs: fix broken docs pipeline (#2936)
* refactor user login guide (#2921) * docs: fix docusaurus issues * update yarn dep Co-authored-by: Max Peintner <max@caos.ch>
This commit is contained in:
Florian Forster
GitHub
parent
d7cb4cb055
commit
5f2b88be51
@ -2,8 +2,8 @@
|
||||
title: Overview
|
||||
---
|
||||
|
||||
import {ApiCard} from '../../src/components/apicard';
|
||||
import Column from '../../src/components/column';
|
||||
import { ApiCard } from "../../src/components/apicard";
|
||||
import Column from "../../src/components/column";
|
||||
|
||||
## APIs
|
||||
|
||||
@ -29,12 +29,14 @@ The easiest way to have a look at them is, to import them in the [Swagger Editor
|
||||
<div>
|
||||
|
||||
## Authentication
|
||||
|
||||
The authentication API (aka Auth API) is used for all operations on the currently logged in user. The user id is taken from the sub claim in the token.
|
||||
|
||||
</div>
|
||||
<div class="apicard-right">
|
||||
|
||||
### GRPC
|
||||
|
||||
Endpoint:
|
||||
[https://api.zitadel.ch/caos.zitadel.auth.api.v1.AuthService/](https://api.zitadel.ch/caos.zitadel.auth.api.v1.AuthService)
|
||||
|
||||
@ -42,6 +44,7 @@ Definition:
|
||||
[Auth Proto](/docs/apis/proto/auth)
|
||||
|
||||
### REST
|
||||
|
||||
Endpoint:
|
||||
[https://api.zitadel.ch/auth/v1/](https://api.zitadel.ch/auth/v1/)
|
||||
|
||||
@ -51,7 +54,6 @@ Swagger Editor:
|
||||
Definition:
|
||||
[Swagger Definition](https://api.zitadel.ch/openapi/v2/swagger/auth.swagger.json)
|
||||
|
||||
|
||||
</div>
|
||||
</Column>
|
||||
</ApiCard>
|
||||
@ -70,6 +72,7 @@ To identify the current organization you can send a header `x-zitadel-orgid` or
|
||||
<div class="apicard-right">
|
||||
|
||||
### GRPC
|
||||
|
||||
Endpoint:
|
||||
[https://api.zitadel.ch/caos.zitadel.auth.api.v1.AuthService/](https://api.zitadel.ch/caos.zitadel.auth.api.v1.AuthService)
|
||||
|
||||
@ -77,6 +80,7 @@ Definition:
|
||||
[Management Proto](/docs/apis/proto/management)
|
||||
|
||||
### REST
|
||||
|
||||
Endpoint:
|
||||
[https://api.zitadel.ch/management/v1/](https://api.zitadel.ch/management/v1/)
|
||||
|
||||
@ -102,6 +106,7 @@ This API is intended to configure and manage the IAM itself.
|
||||
<div class="apicard-right">
|
||||
|
||||
### GRPC
|
||||
|
||||
Endpoint:
|
||||
[https://api.zitadel.ch/caos.zitadel.auth.api.v1.AuthService/](https://api.zitadel.ch/caos.zitadel.auth.api.v1.AuthService)
|
||||
|
||||
@ -109,6 +114,7 @@ Definition:
|
||||
[Admin Proto](/docs/apis/proto/auth)
|
||||
|
||||
### REST
|
||||
|
||||
Endpoint:
|
||||
[https://api.zitadel.ch/admin/v1/](https://api.zitadel.ch/admin/v1/)
|
||||
|
||||
@ -134,18 +140,18 @@ The Assets API allows you to up- and download all kinds of assets. This can be f
|
||||
<div>
|
||||
|
||||
### REST
|
||||
|
||||
Endpoint:
|
||||
[https://api.zitadel.ch/assets/v1/](https://api.zitadel.ch/assets/v1/)
|
||||
|
||||
Definition:
|
||||
[/docs/apis/assets/assets](/docs/apis/assets/assets)
|
||||
|
||||
[Assets](./assets/assets.md)
|
||||
|
||||
</div>
|
||||
</Column>
|
||||
</ApiCard>
|
||||
|
||||
## Example
|
||||
## Example
|
||||
|
||||
See below for an example with the call **GetMyUser**.
|
||||
|
||||
@ -167,15 +173,15 @@ As you can see the `GetMyUser` function is also available as a REST service unde
|
||||
In the table below you can see the URI of those calls.
|
||||
|
||||
| Service | URI |
|
||||
|:--------|:-----------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| :------ | :--------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| REST | [https://api.zitadel.ch/auth/v1/users/me](https://api.zitadel.ch/auth/v1/users/me) |
|
||||
| GRPC | [https://api.zitadel.ch/caos.zitadel.auth.api.v1.AuthService/GetMyUser](https://api.zitadel.ch/caos.zitadel.auth.api.v1.AuthService/GetMyUser) |
|
||||
|
||||
## Domains
|
||||
|
||||
| Domain Name | Example | Description |
|
||||
| :---------- | :-------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| issuer | `issuer.zitadel.ch` | Provides the [OpenID Connect 1.0 Discovery Endpoint](openidoauth/endpoints#openid-connect-10-discovery) |
|
||||
| api | `api.zitadel.ch` | All ZITADEL API's are located under this domain. |
|
||||
| login | `accounts.zitadel.ch` | The accounts.* page provides server renderer pages like login and register and as well the authorization_endpoint for OpenID Connect |
|
||||
| console | `console.zitadel.ch` | With the console.* domain we serve the assets for the management gui |
|
||||
| Domain Name | Example | Description |
|
||||
| :---------- | :-------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| issuer | `issuer.zitadel.ch` | Provides the [OpenID Connect 1.0 Discovery Endpoint](openidoauth/endpoints#openid-connect-10-discovery) |
|
||||
| api | `api.zitadel.ch` | All ZITADEL API's are located under this domain. |
|
||||
| login | `accounts.zitadel.ch` | The accounts.\* page provides server renderer pages like login and register and as well the authorization_endpoint for OpenID Connect |
|
||||
| console | `console.zitadel.ch` | With the console.\* domain we serve the assets for the management gui |
|
||||
|
||||
59
docs/docs/guides/authentication/authmethods.mdx
Normal file
59
docs/docs/guides/authentication/authmethods.mdx
Normal file
@ -0,0 +1,59 @@
|
||||
import TabItem from "@theme/TabItem";
|
||||
import Tabs from "@theme/Tabs";
|
||||
import PKCE from "./authmethods/pkce.mdx";
|
||||
|
||||
import Basic from "./authmethods/basic.mdx";
|
||||
import Implicit from "./authmethods/implicit.mdx";
|
||||
import PKCENative from "./authmethods/pkcenative.mdx";
|
||||
|
||||
export default function AuthMethods(props) {
|
||||
return props.selected == "web" ? (
|
||||
<div>
|
||||
<Tabs
|
||||
groupId="auth-type"
|
||||
default="pkce"
|
||||
values={[
|
||||
{ label: "PKCE", value: "pkce" },
|
||||
{ label: "Basic Auth", value: "basic" },
|
||||
{ label: "JWT with Private Key", value: "jwt" },
|
||||
]}
|
||||
>
|
||||
<TabItem value="pkce">
|
||||
<PKCE />
|
||||
</TabItem>
|
||||
<TabItem value="basic">
|
||||
<Basic />
|
||||
</TabItem>
|
||||
<TabItem value="implicit">
|
||||
<Implicit />
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
</div>
|
||||
) : props.selected == "native" ? (
|
||||
<Tabs
|
||||
groupId="auth-type"
|
||||
default="pkce"
|
||||
values={[{ label: "PKCE", value: "pkce" }]}
|
||||
>
|
||||
<TabItem value="pkce">
|
||||
<PKCENative />
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
) : props.selected == "spa" ? (
|
||||
<Tabs
|
||||
groupId="auth-type"
|
||||
default="pkce"
|
||||
values={[
|
||||
{ label: "PKCE", value: "pkce" },
|
||||
{ label: "Implicit", value: "implicit" },
|
||||
]}
|
||||
>
|
||||
<TabItem value="pkce">
|
||||
<PKCE />
|
||||
</TabItem>
|
||||
<TabItem value="implicit">
|
||||
<Implicit />
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
) : null;
|
||||
}
|
||||
10
docs/docs/guides/authentication/authmethods/implicit.mdx
Normal file
10
docs/docs/guides/authentication/authmethods/implicit.mdx
Normal file
@ -0,0 +1,10 @@
|
||||
:::caution Security Notice
|
||||
In contrast to the Code Flow, where you'll receive a code for token exchange, with the implicit flow you'll receive
|
||||
the tokens directly from the authorization endpoint. This is unsecure and might lead to token leakage and replay attacks.
|
||||
It will further be removed in OAuth 2.1 for the exact same reason.
|
||||
|
||||
We therefore discourage the use of Implicit Flow and do not cover the flow in this guide.
|
||||
:::
|
||||
|
||||
If you still need to rely on the implicit flow, simply keep in mind that the response on the authorization_endpoint is
|
||||
the same you would be given on the token_endpoint and check the [OAuth / OIDC endpoint documentation](../../../apis/openidoauth/endpoints.md) for more information.
|
||||
7
docs/docs/guides/authentication/authmethods/pkce.mdx
Normal file
7
docs/docs/guides/authentication/authmethods/pkce.mdx
Normal file
@ -0,0 +1,7 @@
|
||||
#### redirect_uri
|
||||
|
||||
After selecting the authentication method, you can register a redirect_uri and post_logout_redirect_uri.
|
||||
The redirect_uri will be called after user authentication for code exchange.
|
||||
|
||||
You can even register multiple, but typically one will be enough. If you need to distinguish between different scenarios
|
||||
or environments we recommend using the `state` parameter for the former and multiple projects for the latter.
|
||||
18
docs/docs/guides/authentication/authmethods/pkcenative.mdx
Normal file
18
docs/docs/guides/authentication/authmethods/pkcenative.mdx
Normal file
@ -0,0 +1,18 @@
|
||||
#### redirect_uri
|
||||
|
||||
Native clients might have to register multiple redirect_uris as operating system have different requirements.
|
||||
Typically, you register a redirect_uri starting with a custom protocol, e.g. `ch.zitadel.app://callback`.
|
||||
You're also allowed to use http://localhost, http://127.0.0.1 and http:[::1] without specifying a port: `http://locahost/callback`.
|
||||
|
||||
#### post creation actions
|
||||
|
||||
After the application creation, you might want to set additional options like `refresh_token` and `additional origins`.
|
||||
|
||||
If you want to request refresh_tokens and use them to renew the user's access_tokens without their interaction,
|
||||
enable them in the OIDC Configuration section by ticking the checkbox.
|
||||
|
||||
When calling the userinfo_endpoint or any ZITADEL API, we will check if an origin header is sent. This is automatically done
|
||||
by the user agent. If one is sent we will check if the origin is allowed for your application. By default, all computed
|
||||
origins of the redirect_uri list are allowed.
|
||||
So if your native app is built with a JavaScript base framework like ReactNative and you only specified redirect_uris
|
||||
with a custom protocol, you will need to add the origin where the app is served from, e.g. `http://localhost:8100`.
|
||||
@ -2,8 +2,9 @@
|
||||
title: Login Users into your Application
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
import Tabs from "@theme/Tabs";
|
||||
import TabItem from "@theme/TabItem";
|
||||
import AuthMethods from "./authmethods.mdx";
|
||||
|
||||
## Overview
|
||||
|
||||
@ -13,6 +14,7 @@ It will guide you step-by-step through the basics and point out on how to custom
|
||||
## OIDC / OAuth Flow
|
||||
|
||||
OAuth and therefore OIDC know three different application types:
|
||||
|
||||
- Web (Server-side web applications such as java, .net, ...)
|
||||
- Native (native, mobile or desktop applications)
|
||||
- User Agent (single page applications / SPA, generally JavaScript executed in the browser)
|
||||
@ -68,59 +70,17 @@ recommend using POST and will not cover it in this guide.
|
||||
|
||||
Please change the authentication method here as well, if you did so in the wizard, so we can better guide you through the process:
|
||||
|
||||
<Tabs
|
||||
groupId="auth-type"
|
||||
default="pkce"
|
||||
values={[
|
||||
{'label': 'PKCE', 'value': 'pkce'},
|
||||
{'label': 'Basic Auth', 'value': 'basic'},
|
||||
{'label': 'JWT with Private Key', 'value': 'jwt'},
|
||||
]}
|
||||
>
|
||||
</Tabs>
|
||||
|
||||
#### redirect_uri
|
||||
|
||||
After selecting the authentication method, you can register a redirect_uri and post_logout_redirect_uri.
|
||||
The redirect_uri will be called after user authentication for code exchange.
|
||||
|
||||
You can even register multiple, but typically one will be enough. If you need to distinguish between different scenarios
|
||||
or environments we recommend using the `state` parameter for the former and multiple projects for the latter.
|
||||
<AuthMethods selected="web" />
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="native">
|
||||
|
||||
#### Authentication method
|
||||
|
||||
When selecting Native the authentication method always needs to be PKCE.
|
||||
|
||||
<Tabs
|
||||
groupId="auth-type"
|
||||
default="pkce"
|
||||
values={[
|
||||
{'label': 'PKCE', 'value': 'pkce'},
|
||||
]}
|
||||
>
|
||||
</Tabs>
|
||||
|
||||
#### redirect_uri
|
||||
|
||||
Native clients might have to register multiple redirect_uris as operating system have different requirements.
|
||||
Typically, you register a redirect_uri starting with a custom protocol, e.g. `ch.zitadel.app://callback`.
|
||||
You're also allowed to use http://localhost, http://127.0.0.1 and http:[::1] without specifying a port: `http://locahost/callback`.
|
||||
|
||||
#### post creation actions
|
||||
|
||||
After the application creation, you might want to set additional options like `refresh_token` and `additional origins`.
|
||||
|
||||
If you want to request refresh_tokens and use them to renew the user's access_tokens without their interaction,
|
||||
enable them in the OIDC Configuration section by ticking the checkbox.
|
||||
|
||||
When calling the userinfo_endpoint or any ZITADEL API, we will check if an origin header is sent. This is automatically done
|
||||
by the user agent. If one is sent we will check if the origin is allowed for your application. By default, all computed
|
||||
origins of the redirect_uri list are allowed.
|
||||
So if your native app is built with a JavaScript base framework like ReactNative and you only specified redirect_uris
|
||||
with a custom protocol, you will need to add the origin where the app is served from, e.g. `http://localhost:8100`.
|
||||
<AuthMethods selected="native" />
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="spa">
|
||||
@ -130,46 +90,15 @@ with a custom protocol, you will need to add the origin where the app is served
|
||||
When selecting SPA the recommended authentication method is again PKCE. All common Frameworks like Angular, React, Vue.js and so on
|
||||
are able to successfully authenticate with PKCE. Our Managament UI Console for instance uses PKCE as well.
|
||||
|
||||
<Tabs
|
||||
groupId="auth-type"
|
||||
default="pkce"
|
||||
values={[
|
||||
{'label': 'PKCE', 'value': 'pkce'},
|
||||
{'label': 'Implicit', 'value': 'implicit'},
|
||||
]}
|
||||
>
|
||||
<TabItem value="pkce"></TabItem>
|
||||
<TabItem value="implicit">
|
||||
|
||||
:::caution Security Notice
|
||||
In contrast to the Code Flow, where you'll receive a code for token exchange, with the implicit flow you'll receive
|
||||
the tokens directly from the authorization endpoint. This is unsecure and might lead to token leakage and replay attacks.
|
||||
It will further be removed in OAuth 2.1 for the exact same reason.
|
||||
|
||||
We therefore discourage the use of Implicit Flow and do not cover the flow in this guide.
|
||||
:::
|
||||
|
||||
If you still need to rely on the implicit flow, simply keep in mind that the response on the authorization_endpoint is
|
||||
the same you would be given on the token_endpoint and check the [OAuth / OIDC endpoint documentation](../../apis/openidoauth/endpoints.md) for more information.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
#### redirect_uri
|
||||
|
||||
After selecting the authentication method, you can register a redirect_uri and post_logout_redirect_uri.
|
||||
The redirect_uri will be called after user authentication for code exchange.
|
||||
|
||||
You can even register multiple, but typically one will be enough. If you need to distinguish between different scenarios
|
||||
or environments we recommend using the `state` parameter for the former and multiple projects for the latter.
|
||||
|
||||
<AuthMethods selected="spa" />
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Auth Request
|
||||
|
||||
To initialize the user authentication, you will have to create an authorization request using HTTP GET in the user agent (browser)
|
||||
To initialize the user authentication, you will have to create an authorization request using HTTP GET in the user agent (browser)
|
||||
on /authorize with at least the following parameters:
|
||||
|
||||
- `client_id`: this tells the authorization server which application it is, copy from Console
|
||||
- `redirect_uri`: where the authorization code is sent to after the user authentication, must be one of the registered in the previous step
|
||||
- `response_type`: if you want to have a code (authorization code flow) or directly a token (implicit flow), so when ever possible use `code`
|
||||
@ -195,6 +124,7 @@ PKCE stands for Proof Key for Code Exchange. So other than "normal" code exchang
|
||||
client_id and client_secret but an additional code. You will have to generate a random string, hash it and send this hash
|
||||
on the authorization_endpoint. On the token_endpoint you will then send the plain string for the authorization to compute
|
||||
the hash as well and to verify it's correct. In order to do so you're required to send the following two parameters as well:
|
||||
|
||||
- `code_challenge`: the base64url representation of the (sha256) hash of your random string
|
||||
- `code_challenge_method`: must always be `S256` standing for sha256, this is the only algorithm we support
|
||||
|
||||
@ -251,7 +181,7 @@ curl --request GET \
|
||||
### Additional parameters and customization
|
||||
|
||||
There are additional parameters and values you can provide to satisfy your use case and to customize the user's authentication flow.
|
||||
Please check the [authorization_endpoint reference](../../apis/openidoauth/endpoints.md#authorization_endpoint) in the OAuth / OIDC documentation.
|
||||
Please check the [authorization_endpoint reference](../../apis/openidoauth/endpoints#authorization_endpoint) in the OAuth / OIDC documentation.
|
||||
|
||||
## Callback
|
||||
|
||||
@ -273,6 +203,7 @@ Check the [error response section](../../apis/openidoauth/endpoints#error-respon
|
||||
## Token request
|
||||
|
||||
Next you will have to exchange the given `code` for the tokens. For this HTTP POST request (form-urlencoded) you will need to provide the following:
|
||||
|
||||
- code: the code that was issued from the authorization request
|
||||
- grant_type: must be `authorization_code`
|
||||
- redirect_uri: callback uri where the code was sent to. Must match exactly the redirect_uri of the authorization request
|
||||
@ -306,7 +237,7 @@ curl --request POST \
|
||||
</TabItem>
|
||||
<TabItem value="basic">
|
||||
|
||||
Send your `client_id` and `client_secret` as Basic Auth Header. Note that OAuth2 requires client_id and client_secret to be form url encoded.
|
||||
Send your `client_id` and `client_secret` as Basic Auth Header. Note that OAuth2 requires client_id and client_secret to be form url encoded.
|
||||
So check [Client Secret Basic Auth Method](../../apis/openidoauth/authn-methods#client-secret-basic) on how to build it correctly.
|
||||
|
||||
```curl
|
||||
@ -2,7 +2,7 @@
|
||||
title: Get started
|
||||
---
|
||||
|
||||
import Column from '../../../src/components/column';
|
||||
import Column from "../../../src/components/column";
|
||||
|
||||
Most applications need to know the identity of a user allowing to securely store user data in the cloud and provide the same personalised experience across all of the user's devices.
|
||||
|
||||
|
||||
@ -14,8 +14,8 @@
|
||||
"write-heading-ids": "docusaurus write-heading-ids"
|
||||
},
|
||||
"dependencies": {
|
||||
"@docusaurus/core": "^2.0.0-beta.6",
|
||||
"@docusaurus/preset-classic": "^2.0.0-beta.6",
|
||||
"@docusaurus/core": "^2.0.0-beta.14",
|
||||
"@docusaurus/preset-classic": "^2.0.0-beta.14",
|
||||
"@mdx-js/react": "^1.6.22",
|
||||
"clsx": "^1.1.1",
|
||||
"docusaurus-plugin-plausible": "^0.0.5",
|
||||
|
||||
7510
docs/yarn.lock
7510
docs/yarn.lock
File diff suppressed because it is too large
Load Diff
Loading…
x
Reference in New Issue
Block a user