mirror of
https://github.com/andwati/zitadel.git
synced 2026-11-07 22:55:12 +00:00
docs: add tailwindcss for styles, oidc authorize endpoint playground (#4707)
* variable parser * rm plugin * set fcn * env * EnvCode component * cleanup env demo * env * rm remark plugin * auth request context * auth req component * authorize endpoint construction * rev react page * fix endpoint * styling * query params with anchor * desc * tailwind coexistence * fix styles * add login_hint, organizationId scope * auth request without prompt * show login_hint * sync displayed url with actual href * fix fcn * coloring * Update docs/src/components/authrequest.jsx Co-authored-by: mffap <[email protected]> * Update docs/src/components/authrequest.jsx Co-authored-by: mffap <[email protected]> * Update docs/src/components/authrequest.jsx Co-authored-by: mffap <[email protected]> * Update docs/src/components/authrequest.jsx Co-authored-by: mffap <[email protected]> * Update docs/src/components/authrequest.jsx Co-authored-by: mffap <[email protected]> * Update docs/src/components/authrequest.jsx Co-authored-by: mffap <[email protected]> * add plausible, header * add pkce * move * adds pkce code challenge * replace cboa * reaname and move to required * fall back to cboa due to webpack error * trailing slash * reorder org_id * remove resourceowner * texts * update references * buffer, fix some react dom components * Apply suggestions from code review Co-authored-by: Florian Forster <[email protected]> * standard scopes Co-authored-by: mffap <[email protected]> Co-authored-by: Florian Forster <[email protected]>
This commit is contained in:
Max Peintner
co-authored by
mffap
Florian Forster
mffap
Florian Forster
parent
add232d1dd
commit
97fe041a86
@@ -21,16 +21,7 @@ the authentication process. The latter is used to bind the client session with t
|
||||
|
||||
You don't need any additional parameter for this request. We're identifying the app by the `client_id` parameter.
|
||||
|
||||
So your request might look like this (linebreaks and whitespace for display reasons):
|
||||
|
||||
```curl
|
||||
curl --request GET \
|
||||
--url '{your-domain}/oauth/v2/authorize
|
||||
?client_id=${client_id}
|
||||
&redirect_uri=${redirect_uri}
|
||||
&response_type=code
|
||||
&scope=openid%20email%20profile'
|
||||
```
|
||||
Try out the request in our [OIDC Authentication Request Playground](/docs/apis/openidoauth/authrequest?auth_method=Client%20Secret%20Basic).
|
||||
|
||||
### Additional parameters and customization
|
||||
|
||||
|
||||
@@ -23,14 +23,7 @@ You don't need any additional parameter for this request. We're identifying the
|
||||
|
||||
So your request might look like this (linebreaks and whitespace for display reasons):
|
||||
|
||||
```curl
|
||||
curl --request GET \
|
||||
--url '{your-domain}/oauth/v2/authorize
|
||||
?client_id=${client_id}
|
||||
&redirect_uri=${redirect_uri}
|
||||
&response_type=code
|
||||
&scope=openid%20email%20profile'
|
||||
```
|
||||
Try out the request in our [OIDC Authentication Request Playground](/docs/apis/openidoauth/authrequest?auth_method=Client%20Secret%20Basic).
|
||||
|
||||
### Additional parameters and customization
|
||||
|
||||
|
||||
@@ -29,18 +29,7 @@ the hash as well and to verify it's correct. In order to do so you're required t
|
||||
|
||||
For example for `random-string` the code_challenge would be `9az09PjcfuENS7oDK7jUd2xAWRb-B3N7Sr3kDoWECOY`
|
||||
|
||||
The request would finally look like (linebreaks and whitespace for display reasons):
|
||||
|
||||
```curl
|
||||
curl --request GET \
|
||||
--url '{your-domain}/oauth/v2/authorize
|
||||
?client_id=${client_id}
|
||||
&redirect_uri=${redirect_uri}
|
||||
&response_type=code
|
||||
&scope=openid%20email%20profile
|
||||
&code_challenge=${code_challenge}
|
||||
&code_challenge_method=S256'
|
||||
```
|
||||
Try out the request in our [OIDC Authentication Request Playground](/docs/apis/openidoauth/authrequest).
|
||||
|
||||
### Additional parameters and customization
|
||||
|
||||
|
||||
@@ -2,7 +2,8 @@
|
||||
title: Recommended authorization flows
|
||||
---
|
||||
|
||||
<table class="table-wrapper">
|
||||
<table className="table-wrapper">
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>Description</td>
|
||||
<td>Learn about the different authentication flows and which flow we recommend you should use for your application.</td>
|
||||
@@ -24,9 +25,9 @@ title: Recommended authorization flows
|
||||
Basic knowledge about federated identities
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## Introduction
|
||||
|
||||
Before we get into setting up our first application within ZITADEL, we need to go through some basics on how to obtain an authorization with OpenID Connect 1.x and OAuth 2.x.
|
||||
@@ -43,21 +44,22 @@ Although Federated Identities are not a new concept ([RFC 6749](https://tools.ie
|
||||
|
||||
The aforementioned RFC provides us with some [problems and limitations](https://tools.ietf.org/html/rfc6749#section-1) of the client-server authentication, where a client requests a protected resource on the server by authenticating with the user’s credentials:
|
||||
|
||||
* Applications need to store users credentials (eg, password) for future use; compromise of any application results in compromise of the end-users credentials
|
||||
* Servers are required to support password authentication
|
||||
* Without means of limiting scope when providing the user’s credentials, the application gains overly broad access to protected resources
|
||||
* Users cannot revoke access for a single application, but only for all by changing credentials
|
||||
- Applications need to store users credentials (eg, password) for future use; compromise of any application results in compromise of the end-users credentials
|
||||
- Servers are required to support password authentication
|
||||
- Without means of limiting scope when providing the user’s credentials, the application gains overly broad access to protected resources
|
||||
- Users cannot revoke access for a single application, but only for all by changing credentials
|
||||
|
||||
So what do we want to achieve with delegated authentication?
|
||||
|
||||
* Instead of implementing authentication on each server and trusting each server
|
||||
* Users only **authenticate** with a trusted server (ie. ZITADEL), that validates the user’s identity through a challenge (eg, multiple authentication factors) and issues an **ID token** (OpenID Connect 1.x)
|
||||
* Applications have means of **validating the integrity** of presented access and ID tokens
|
||||
- Instead of implementing authentication on each server and trusting each server
|
||||
|
||||
* Instead of sending around the user’s 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**](../../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
|
||||
- Users only **authenticate** with a trusted server (ie. ZITADEL), that validates the user’s identity through a challenge (eg, multiple authentication factors) and issues an **ID token** (OpenID Connect 1.x)
|
||||
- Applications have means of **validating the integrity** of presented access and ID tokens
|
||||
|
||||
- Instead of sending around the user’s 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**](../../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
|
||||
|
||||
|
||||
|
||||
@@ -74,19 +76,20 @@ As mentioned in the beginning of this module, there are two main determinants fo
|
||||
|
||||
OAuth 2.x defines two [client types](https://tools.ietf.org/html/rfc6749#section-2.1) based on their ability to maintain the confidentiality of their client credentials:
|
||||
|
||||
* Confidential: Clients capable of maintaining the confidentiality of their credentials (e.g., client implemented on a secure server with restricted access to the client credentials), or capable of secure client authentication using other means.
|
||||
* Public: Clients incapable of maintaining the confidentiality of their credentials (e.g., clients executing on the device used by the resource owner, such as an installed native application or a web browser-based application), and incapable of secure client authentication via any other means.
|
||||
- Confidential: Clients capable of maintaining the confidentiality of their credentials (e.g., client implemented on a secure server with restricted access to the client credentials), or capable of secure client authentication using other means.
|
||||
- Public: Clients incapable of maintaining the confidentiality of their credentials (e.g., clients executing on the device used by the resource owner, such as an installed native application or a web browser-based application), and incapable of secure client authentication via any other means.
|
||||
|
||||
The following table gives you a brief overview of different client profiles.
|
||||
|
||||
<table class="table-wrapper">
|
||||
<table className="table-wrapper">
|
||||
<tbody>
|
||||
<tr>
|
||||
<th>Confidentiality of client credentials</th>
|
||||
<th>Client profile</th>
|
||||
<th>Examples of clients</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td rowspan="2">Public</td>
|
||||
<td rowSpan="2">Public</td>
|
||||
<td>User-Agent</td>
|
||||
<td>Single-page web applications (SPA), generally JavaScript executed in Browser</td>
|
||||
</tr>
|
||||
@@ -95,7 +98,7 @@ The following table gives you a brief overview of different client profiles.
|
||||
<td>Native, Mobile, or Desktop applications</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td rowspan="2">Confidential</td>
|
||||
<td rowSpan="2">Confidential</td>
|
||||
<td>Web</td>
|
||||
<td>Server-side web applications such as java, .net, …</td>
|
||||
</tr>
|
||||
@@ -103,6 +106,7 @@ The following table gives you a brief overview of different client profiles.
|
||||
<td>Machine-to-Machine</td>
|
||||
<td>APIs, generally services without direct user-interaction at the authorization server</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
## Our recommended authorization flows
|
||||
@@ -111,7 +115,7 @@ We recommend using the flow **“Authorization Code with Proof Key of Code Excha
|
||||
|
||||
If you don’t have any technical limitations, you should favor the flow Authorization Code with PKCE over other methods. The PKCE part makes the flow resistant against authorization code interception attack as described well in RFC7636.
|
||||
|
||||
*So what about APIs?*
|
||||
_So what about APIs?_
|
||||
|
||||
We recommend using **“JWT bearer token with private key”** ([RFC7523](https://tools.ietf.org/html/rfc7523)) for Machine-to-Machine clients.
|
||||
|
||||
@@ -125,13 +129,13 @@ In case you need alternative flows and their advantages and drawbacks, there wil
|
||||
|
||||
## Summary (3)
|
||||
|
||||
* Federated Identities solve key problems and challenges with traditional server-client architecture
|
||||
* Use “Authorization Code with Proof Key of Code Exchange (PKCE)” for User-Agent, Native, and Web clients
|
||||
* “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
|
||||
- Federated Identities solve key problems and challenges with traditional server-client architecture
|
||||
- Use “Authorization Code with Proof Key of Code Exchange (PKCE)” for User-Agent, Native, and Web clients
|
||||
- “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
|
||||
|
||||
* Applications
|
||||
* Service Accounts
|
||||
* Alternative authentication flows (aka. "The Zoo")
|
||||
- Applications
|
||||
- Service Accounts
|
||||
- Alternative authentication flows (aka. "The Zoo")
|
||||
|
||||
@@ -9,7 +9,7 @@ After users register using an external identity provider, the action assigns the
|
||||
|
||||
Before you start, make sure you have everything set up correctly.
|
||||
|
||||
- You need to be at least a ZITADEL *ORG_OWNER*
|
||||
- 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)
|
||||
@@ -24,12 +24,11 @@ Before you start, make sure you have everything set up correctly.
|
||||
## 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. In the **Actions <i className="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 reference
|
||||
https://github.com/zitadel/actions/blob/main/examples/add_user_grant.js
|
||||
```
|
||||
@@ -38,11 +37,11 @@ https://github.com/zitadel/actions/blob/main/examples/add_user_grant.js
|
||||
|
||||
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.
|
||||
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.
|
||||
1. In the **Flows <i className="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 -->
|
||||
|
||||
@@ -51,4 +50,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/introduction)
|
||||
- [Read more about all the options you have with actions](../../../apis/actions/introduction)
|
||||
|
||||
@@ -43,22 +43,10 @@ If you like to trigger your settings for your applications you have different po
|
||||
|
||||
### 1. Primary Domain Scope
|
||||
|
||||
Send a [primary domain scope](../../../apis/openidoauth/scopes) with your [authorization request](../../integrate/login-users#auth-request) to trigger your organization.
|
||||
Send a [reserved 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]../integrate/login-users#auth-request).
|
||||
:::
|
||||
You can use our [OpenID Authentication Request Playground](/docs/apis/openidoauth/authrequest) to learn more about how to trigger an [organization's policies and branding](/docs/apis/openidoauth/authrequest#organization-policies-and-branding).
|
||||
|
||||
### 2. Setting on your Project
|
||||
|
||||
|
||||
@@ -107,33 +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](../../../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>
|
||||
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) or try it out in our [OIDC Authrequest Playground](/docs/apis/openidoauth/authrequest?scope=openid%20email%20profile%20urn%3Azitadel%3Aiam%3Auser%3Ametadata).
|
||||
|
||||
Login with the user to which you have added the metadata. After the login you will be redirected.
|
||||
|
||||
|
||||
@@ -18,7 +18,7 @@ This guide attempts to explain real-world implementations and break them down in
|
||||
<ListElement
|
||||
link="./b2c"
|
||||
iconClasses="las la-paragraph"
|
||||
roundClasses="rounded rounded-split"
|
||||
roundClasses="custom-rounded rounded-split"
|
||||
label="B2C"
|
||||
title="Business to Consumer"
|
||||
description="Organizations with your SDLC, Domains, Authentication, Hosted Login"
|
||||
@@ -26,7 +26,7 @@ This guide attempts to explain real-world implementations and break them down in
|
||||
<ListElement
|
||||
link="./b2b"
|
||||
iconClasses="las la-paragraph"
|
||||
roundClasses="rounded rounded-split"
|
||||
roundClasses="custom-rounded rounded-split"
|
||||
label="B2B"
|
||||
title="Business to Business"
|
||||
description="Planning considerations, B2B Sample Case"
|
||||
|
||||
Reference in New Issue
Block a user