mirror of
https://github.com/zitadel/zitadel.git
synced 2025-07-11 01:48:32 +00:00

* Modified quick start guide to reflect the new onboarding changes. * Modified titles to optimize indexing. Left thet titles in title case for now. * Added side bar labels and also made minor changes to titles. * Update docs/docs/apis/openidoauth/endpoints.mdx Co-authored-by: Fabi <fabienne@zitadel.com> --------- Co-authored-by: Fabi <fabienne@zitadel.com>
129 lines
5.7 KiB
Plaintext
129 lines
5.7 KiB
Plaintext
---
|
|
title: ZITADEL OIDC Authentication Request Playground
|
|
sidebar_label: OIDC Playground
|
|
---
|
|
|
|
import { SetAuthRequest } from "../../../src/components/authrequest";
|
|
|
|
The OIDC Playground is for testing OpenID Authentication Requests, giving you more insight how OpenID Connect works and how you can customize ZITADEL behavior with different parameters.
|
|
|
|
An OpenID Connect (OIDC) [authentication request](https://openid.net/specs/openid-connect-core-1_0.html) is an OAuth 2.0 Authorization Request using additional parameters and scopes to request that the end-user be authenticated by ZITADEL.
|
|
|
|
<SetAuthRequest />
|
|
|
|
## Why this OIDC playground?
|
|
|
|
Currently ZITADEL requires human users to authenticate trough the hosted login page.
|
|
Your application should initiate a login by issuing an authentication request and redirecting the user to the login page. You can customize the behavior of ZITADEL by providing additional parameters and scopes in the request.
|
|
|
|
This playground should help you to initially craft an authentication request and to explore the behavior of ZITADEL in more depth.
|
|
|
|
## Request parameters explained
|
|
|
|
Not all request parameters are available in the playground. Please refer to the full documentation of the [authorization endpoint](/apis/openidoauth/endpoints#authorization_endpoint).
|
|
|
|
### Your Domain
|
|
|
|
The <span className="text-yellow-500">Instance Domain</span> to your ZITADEL instance. Use the base-path, the playground will add the required path to the request.
|
|
|
|
### Required Parameters
|
|
|
|
<p>
|
|
<span className="text-green-500">Client ID</span> is the resource id of an
|
|
application. It's the application where you want your users to login. You can
|
|
find the resource id in the Console. When using organization grants, use the
|
|
client id from the origin organization.
|
|
</p>
|
|
|
|
<p>
|
|
<span className="text-blue-500">Redirect URI</span> be one of the
|
|
pre-configured redirect uris for your application. You must add the redirect
|
|
uri for your application, else you will receive an error.
|
|
</p>
|
|
|
|
<p>
|
|
<span className="text-orange-500">Response Type</span> defines whether a code,
|
|
id_token token or just id_token will be returned. Most use cases will need
|
|
code.
|
|
</p>
|
|
|
|
More in the <a href="/apis/openidoauth/endpoints#required-request-parameters">documentation</a> about required Parameters.
|
|
|
|
### Authentication methods
|
|
|
|
Depending on the authentication and authorization flow of your application you might need to append some information to the authentication request.
|
|
|
|
<span className="text-teal-600">Authentication method</span> "(none) PKCE" is recommended
|
|
for most application types. The playground appends automatically a code challenge
|
|
for PKCE flows.
|
|
|
|
You need to append a "Code Challenge" by providing a random <span className="text-teal-600">Code Verifier</span> that is being hashed and encoded in the request to the token endpoint, please see our [guide](/guides/integrate/login-users#token-request) for more details.
|
|
|
|
More in the [documentation](/apis/openidoauth/authn-methods) about authentication methods.
|
|
|
|
### Additional Parameters
|
|
|
|
<div>
|
|
<span className="text-cyan-500">Prompt</span> defines if and how the user
|
|
should be prompted on login. For example:
|
|
<ul>
|
|
<li>
|
|
<code>select_account</code>: user is prompted to select one of the
|
|
existing sessions or create a new one
|
|
</li>
|
|
<li>
|
|
<code>create</code>: present the register form
|
|
</li>
|
|
<li>
|
|
<code>login</code>: requires the user to re-authenticate
|
|
</li>
|
|
<li>
|
|
<code>none</code>: user must be authenticated without interaction, an
|
|
error is returned otherwise; use for silent-refresh
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
|
|
<p>
|
|
<span className="text-rose-500">Login hint</span> must be a valid logon name
|
|
of a user. You can skip the account picker by providing the Login hint.
|
|
</p>
|
|
|
|
There are many more additional parameters. Please refer to the [documentation](/apis/openidoauth/endpoints#additional-parameters) about additional parameters.
|
|
|
|
## Standard Scopes
|
|
|
|
Used to request additional information from ZITADEL.
|
|
These scopes are defined in the OpenID Connect specification.
|
|
The `openid` scope is mandatory.
|
|
|
|
Not all scopes are available in the playground. Please refer to the full [documentation](/apis/openidoauth/scopes) for the exhaustive list of available standard and reserved scopes.
|
|
|
|
## Reserved Scopes
|
|
|
|
You can request additional information that is specific to ZITADEL or customize the behavior of ZITADEL by including reserved scopes.
|
|
Please refer to the [documentation](/apis/openidoauth/scopes#reserved-scopes) for a full list of available reserved scopes.
|
|
|
|
### Organization policies and branding
|
|
|
|
Enforce an organization's policies and branding as well as membership of the user by passing the scope `urn:zitadel:iam:org:id:{id}` with the required <span className="text-purple-500">Organization ID</span>.
|
|
|
|
Please refer to the full [guide on branding](/guides/manage/customize/branding).
|
|
|
|
### Get user metadata
|
|
|
|
Pass the scope `urn:zitadel:iam:user:metadata` to request a user's metadata.
|
|
Please refer to the full [guide on user-metadata](/guides/manage/customize/user-metadata) for further details.
|
|
|
|
### Access core apis
|
|
|
|
Calling the [core API](/apis/introduction) with the authenticated user, requires that the projectID of ZITADEL is included in the audience claim.
|
|
|
|
This can be achieved by adding the scope `urn:zitadel:iam:org:project:id:zitadel:aud` to your applications authorization request.
|
|
|
|
## How to use ZITADEL in your project
|
|
|
|
Please refer to our [guide](/guides/integrate/login-users) on how to login users.
|
|
|
|
OpenID Connect certified libraries should allow you to customize the parameters and define scopes for the authorization request. You can also continue by using one of our [example applications](/examples/introduction).
|