mirror of
https://github.com/zitadel/zitadel.git
synced 2026-08-17 16:35:14 -05:00
docs: Overhauled Quickstart guide to improve developer experience (#11366)
# Which Problems Are Solved - Outdated Quickstart, with old screenshots - Quickstart was too long - Quickstart had lots of prose text, which wasn't really developer focused # How the Problems Are Solved - Replaced outdated screenshots with the latest UI. - Streamlined long-form prose into actionable, developer-focused steps. - Shortened the overall length to help developers reach "Success" faster. --------- Co-authored-by: Florian Forster <florian@zitadel.com> Co-authored-by: Livio Spring <livio.a@gmail.com>
This commit is contained in:
Fabienne Bühler
co-authored by
Florian Forster
Livio Spring
Florian Forster
Livio Spring
parent
d7cec1d3bd
commit
09f67a931a
@@ -25,7 +25,7 @@ Make sure you have Node.js and npm installed on your machine.
|
||||
|
||||
### ZITADEL Configuration for the API
|
||||
|
||||
1. Create a ZITADEL instance and a project by following the steps [here](/docs/guides/start/quickstart#3-create-your-first-instance).
|
||||
1. Create a ZITADEL instance and a project by following the steps [here](/docs/guides/start/quickstart#3-create-your-zitadel-instance).
|
||||
|
||||
2. Set up an API application within your project:
|
||||
- Create a new application of type "API" with authentication method "Private Key".
|
||||
|
||||
@@ -31,7 +31,7 @@ In order to run the example you need to have `python3` and `pip3` installed.
|
||||
|
||||
You need to setup a couple of things in ZITADEL.
|
||||
|
||||
1. If you don't have an instance yet, please go ahead and create an instance as explained [here](/docs/guides/start/quickstart#3-create-your-first-instance). Also, create a new project by following the steps [here](/docs/guides/start/quickstart#4-create-your-first-project-and-app).
|
||||
1. If you don't have an instance yet, please go ahead and create an instance as explained [here](/docs/guides/start/quickstart#3-create-your-zitadel-instance). Also, create a new project by following the steps [here](/docs/guides/start/quickstart#4-create-your-project-and-application).
|
||||
|
||||
2. You must create an API application in your project. Follow [this guide](/docs/guides/manage/console/applications-overview) to create a new application of type "API" with authentication method "Basic". Save both the ClientID and ClientSecret after you create the application.
|
||||
|
||||
@@ -180,7 +180,7 @@ class ZitadelIntrospectTokenValidator(IntrospectTokenValidator):
|
||||
return res
|
||||
```
|
||||
|
||||
3. Create a new file named ".env" in the directory. Copy the configuration in the [".env.example"](https://github.com/zitadel/example-api-python3-flask/blob/main/.env.example) file to the newly created .env file. Set the values with your Custom Domain/Issuer URL, Client ID, and Client Secret from the previous steps. Obtain your Issuer URL by following [these steps](/docs/guides/start/quickstart#referred1).
|
||||
3. Create a new file named ".env" in the directory. Copy the configuration in the [".env.example"](https://github.com/zitadel/example-api-python3-flask/blob/main/.env.example) file to the newly created .env file. Set the values with your Custom Domain/Issuer URL, Client ID, and Client Secret from the previous steps. Obtain your Issuer URL by following [these steps](/docs/guides/start/quickstart#5-collect-your-integration-keys).
|
||||
|
||||
```python
|
||||
ZITADEL_DOMAIN = "https://custom-domain-abcdef.zitadel.cloud"
|
||||
|
||||
@@ -1,389 +1,162 @@
|
||||
---
|
||||
title: The ZITADEL Quick Start Guide
|
||||
description: Learn how to integrate OIDC PKCE authentication in React using ZITADEL in under 5 minutes.
|
||||
sidebar_label: Quick Start Guide
|
||||
keywords: [ZITADEL, React, OIDC, PKCE, Authentication, Identity Management]
|
||||
framework: React
|
||||
stack: Node.js
|
||||
---
|
||||
|
||||
import { ResponsivePlayer } from "../../../src/components/player";
|
||||
This sample app implements the [OIDC PKCE](/docs/guides/integrate/login/oidc/login-users) flow for secure authentication.
|
||||
- Login: Exchanges a code challenge for an access token via ZITADEL.
|
||||
- Authorize: Uses the token to retrieve profile data from the userinfo endpoint.
|
||||
- Logout: Clears the local session and revokes the token.
|
||||
|
||||
In this quick start guide, we will be learning some fundamentals on how to set up ZITADEL for user management and application security. Thereafter, we will secure a React-based Single Page Application (SPA) using ZITADEL.
|
||||
## Get Started with ZITADEL Cloud
|
||||
|
||||
<ResponsivePlayer controls url='https://www.youtube.com/watch?v=5THbQljoPKg' />
|
||||
Set up your ZITADEL account and organization to begin managing identities for your applications.
|
||||
|
||||
The sample application allows users to securely log in to ZITADEL using the OIDC Proof Key for Code Exchange (PKCE) flow. This flow ensures that the authentication process is secure by using a code verifier and a code challenge, which are sent to ZITADEL to obtain an access token. The access token is then used by the app to access the userinfo endpoint to retrieve and display information about the logged-in user. The app also has a logout feature that allows users to end their session and clear their access token. Overall, the app provides a simple and secure way for users to authenticate and access protected resources within ZITADEL.
|
||||
### 1. Create your Account and Organization
|
||||
|
||||
## ZITADEL terminology: instances, organizations, projects, users, roles, authorizations and apps
|
||||
You first need access to the ZITADEL Cloud Customer Portal.
|
||||
This is the administrative hub for managing your billing, teams, and instances.
|
||||
1. **Sign Up**: Go to [zitadel.com](http://zitadel.com) and select Sign Up.
|
||||
2. **Onboarding**: Follow the prompts to verify your email and set up your Portal Team.
|
||||
- Tip: We recommend using Passkeys for a secure, passwordless login experience.
|
||||
3. **Access**: Once authenticated, you will be redirected to the Customer Portal dashboard.
|
||||
|
||||
In ZITADEL, instances, organizations, projects, users, roles, and apps are the main components that make up the platform.
|
||||
|
||||
|
||||
|
||||
The order of creation for the above components would typically be as follows:
|
||||
### 2. Quick Onboarding
|
||||
|
||||
<ul>
|
||||
<li>
|
||||
<b>Instance</b>: An instance is a top-level entity in ZITADEL that
|
||||
represents a deployment of ZITADEL for a registered account. An instance can
|
||||
have one or more organizations.
|
||||
</li>
|
||||
<li>
|
||||
<b>Organization</b>: An organization is a logical separation within an
|
||||
instance that represents a company/organization and can have one or more
|
||||
projects. The default organization is the one that is provided at the start
|
||||
of the account registration process. Typically, an instance would have one
|
||||
organization, but in B2B scenarios, an instance would have more than one.
|
||||
</li>
|
||||
<li>
|
||||
<b>Project</b>: A project is a logical separation within an organization and
|
||||
is a container for apps, roles and authorization policies for the resources
|
||||
it contains.
|
||||
</li>
|
||||
<li>
|
||||
<b>Users</b>: Users are created at the organizational level and are granted
|
||||
access to the resources within projects. They can be assigned different
|
||||
roles, which define the permissions and privileges they have within the
|
||||
project.
|
||||
</li>
|
||||
<li>
|
||||
<b>Roles</b>: Roles are the sets of permissions and privileges that are
|
||||
assigned to users within a project.
|
||||
</li>
|
||||
<li>
|
||||
<b>Authorizations</b>: Authorization policies in ZITADEL are defined at the
|
||||
project level, which means that they apply to all the resources within the
|
||||
project. These policies are based on the roles that are assigned to users,
|
||||
and they determine the actions that users are allowed to perform within the
|
||||
project.
|
||||
</li>
|
||||
<li>
|
||||
<b>Apps</b>: Apps are the applications that are developed and managed within
|
||||
a project. They can be client apps that use the resources within the
|
||||
project, or they can be backend apps that provide the resources for other
|
||||
apps to use. The apps can use the OIDC or SAML protocol to authenticate
|
||||
users to access protected resources.
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
The order of creation for the above components may vary depending on the specific needs and requirements of the organization.
|
||||
|
||||
## Set up and manage ZITADEL for your identity projects
|
||||
|
||||
### 1. Sign up for the ZITADEL Cloud customer portal and register your organization
|
||||
|
||||
1. Go to [zitadel.com](http://zitadel.com) and click “Start for FREE”.
|
||||
|
||||
|
||||
|
||||
2. You can sign up by entering your email address or via social login, e.g., Google. Let's sign up using an email address. Enter your email address and click "Sign in with Email".
|
||||
|
||||
|
||||
|
||||
3. Next, complete your details and click "Continue".
|
||||
|
||||
|
||||
|
||||
4. Add a password as shown below. Adhere to the password requirements, agree to the terms of service and privacy policy by selecting the checkbox, and click the "Get started" button.
|
||||
|
||||
|
||||
|
||||
5. Enter your login data. Provide the password you just created. Click "next".
|
||||
|
||||
|
||||
|
||||
6. You will now have to verify your email address.
|
||||
|
||||
|
||||
|
||||
6. Go to your inbox and open the email from ZITADEL and click the "Verify email" button.
|
||||
|
||||
|
||||
|
||||
7. The user is now activated. Click the "login" button.
|
||||
|
||||
|
||||
|
||||
8. Now you will have to log in with the username and password that you provided. Click “Sign in with Email”, then provide a name for your team or organization and continue.
|
||||
|
||||
|
||||
|
||||
### 2. Complete onboarding questions
|
||||
|
||||
To begin, we'll ask you a few questions.
|
||||
These will help us understand your needs and personalize your ZITADEL experience, ensuring you get the most out of it.
|
||||
Complete the brief onboarding questions.
|
||||
This data helps us prioritize the development of new features, SDKs, and integrations that matter most to our community.
|
||||
|
||||
|
||||
|
||||
### 3. Create your first instance
|
||||
### 3. Create your ZITADEL instance
|
||||
|
||||
As a user of the ZITADEL Cloud Customer Portal, you now can create multiple instances to suit your specific needs.
|
||||
This includes instances for development, production, or user acceptance testing, as well as instances for different clients or applications.
|
||||
The possibilities are endless. You can create your first instance for free.
|
||||
An [Instance](/docs/concepts/structure/instance) is a fully isolated identity environment with its own users, policies, and data.
|
||||
Most developers use separate instances to isolate Development, Test, and Production workflows.
|
||||
|
||||
1. Create an instance.
|
||||
by clicking on “Create Instance”.
|
||||
Follow these steps to deploy your first instance:
|
||||
1. **Start**: Click Create Instance on your dashboard.
|
||||
2. **Identity**: Provide an Instance Name (e.g., dev-environment). This will be used to generate your default domain (e.g., dev-environment-xxxx.zitadel.cloud).
|
||||
3. **Locality**: Select your Region.
|
||||
- Note: Choosing a region close to your users minimizes latency and helps with data residency compliance.
|
||||
4. **Admin Setup**: Create your Instance Administrator. This user has "root" permissions to manage all organizations, policies, and settings within this specific instance.
|
||||
5. **Deploy**: Review your configuration and click Create Instance.
|
||||
|
||||
|
||||
|
||||
|
||||
2. Provide a name for your instance and click on the “Continue” button at the bottom of this screen.
|
||||
### 4. Create your Project and Application
|
||||
|
||||
|
||||
In ZITADEL, [**Applications**](/docs/guides/manage/console/applications-overview) are grouped into [**Projects**](/docs/guides/manage/console/projects-overview).
|
||||
This allows multiple apps (like a React frontend and a Go backend) to share the same roles and authorizations.
|
||||
|
||||
3. Next, you should see the following screen. Add a username and password for the instance administrator and click "Create".
|
||||
#### Launch the Management Console
|
||||
|
||||
|
||||
Click **Create your app**. This opens the Management Console for your instance in a new tab.
|
||||
Log in using the Admin credentials you just created.
|
||||
|
||||
|
||||
3. After creating your first instance, you're ready to configure user authentication. To access the management console, click the 'Sign in to your instance' button.
|
||||
|
||||
|
||||
|
||||
6. To log in to your instance, provide the username and password you set in the instance creation, and click “next”.
|
||||
|
||||
7. Skip the 2-factor authentication for now by clicking “skip”.
|
||||
|
||||
8. And there you go! You now have access to your instance.
|
||||
|
||||
|
||||
|
||||
### 4. Create your first project and app
|
||||
|
||||
Because applications are always associated with a project, we'll guide you through setting up both in the following steps.
|
||||
|
||||
1. Click the "Create Application" button or the Framework/Language of your choice on the right side
|
||||
|
||||
2. Insert “Project1” (or any name of your choice) as the project’s name and select the framework/language of your choice in our case "React" and click the “Continue” button. (If you can't find your framework/languages select "Other")
|
||||
#### Step 1: Define your Project
|
||||
- **Name**: Enter a name (e.g., Project1).
|
||||
- **Framework**: Select React (or choose Other if your stack isn't listed).
|
||||
- **Continue**: Click the Continue button.
|
||||
|
||||
|
||||
|
||||
3. An overview of the configuration for the framework you have selected is shown
|
||||
#### Step 2: Review Default Configuration
|
||||
ZITADEL automatically configures the best security settings for your selected framework.
|
||||
- **Auth Strategy**: [Authorization Code Flow](/docs/apis/openidoauth/grant-types#authorization-code) with [PKCE](/docs/apis/openidoauth/grant-types#authorization-code). This modern standard ensures tokens are exchanged securely without needing a client secret in your frontend.
|
||||
- **Redirect URIs**: These define where users return after authentication:
|
||||
- Redirect URI: http://localhost:3000/callback (Landing page after login)
|
||||
- Post Logout URI: http://localhost:3000/ (Landing page after logout)
|
||||
|
||||
|
||||
|
||||
What the configuration does:
|
||||
- We recommend using the [Authentication Code Flow](/docs/apis/openidoauth/grant-types#authorization-code) with [Proof Key for Code Exchange (PKCE)](/docs/apis/openidoauth/grant-types#authorization-code) for secure OIDC configuration. This setup includes specific App, Grant, and Response Types, as well as an Authentication Method. More about the different app types can be found [here](/docs/guides/integrate/login/oidc/oauth-recommended-flows#different-client-profiles).
|
||||
- The redirect URI is where the ZITADEL authorization server redirects the user after they have been authenticated. The "Redirect URI" is preconfigured to [http://localhost:3000/callback](http://localhost:3000/callback) and the “Post Logout URI” to [http://localhost:3000/](http://localhost:3000/) for the React example
|
||||
### 5. Collect your Integration Keys
|
||||
|
||||
4. The detailed configuration of your app will be shown
|
||||
To connect your React application to ZITADEL, you need two primary configuration values.
|
||||
These are typically stored as environment variables in your project.
|
||||
|
||||
|
||||
1. **Client ID** Navigate to Configurations in the left sidebar. This is the unique public identifier for your React application.
|
||||
|
||||
2. **Issuer URL** Click on URLs in the left sidebar to find your **Discovery Endpoint**.
|
||||
- The Value: Copy the issuer URL (e.g., https://your-instance.zitadel.cloud).
|
||||
- Why it matters: ZITADEL supports OIDC Discovery. By providing just the Issuer URL to your SDK, the library automatically finds the login, logout, and token endpoints for you.
|
||||
|
||||
### 5. Add users (optional)
|
||||
|
||||
|
||||
[Skip optional steps](quickstart/#7-create-an-application-in-your-project) and jump directly to the obtain ClientId and OIDC endpoints.
|
||||
## Integrate ZITADEL into your React App
|
||||
|
||||
1. To add users, click on “Users” at the top menu. You will see that the user you already created is listed as a user here. Click on the “New” button to create a new user.
|
||||
### How the Authentication Flow Works
|
||||
ZITADEL handles the complexity of the OIDC handshake so your app stays secure without manual token management.
|
||||
1. **Login**: App redirects the user to ZITADEL with a PKCE challenge.
|
||||
2. **Auth**: User authenticates on the ZITADEL hosted login page.
|
||||
3. **Exchange**: ZITADEL returns an Auth Code, which the app exchanges for an Access Token.
|
||||
4. **Tokens**: The app shows the Access and ID Token
|
||||
5. **Logout**: The app clears local tokens and terminates the ZITADEL session.
|
||||
|
||||
|
||||
### 1. Prerequisites
|
||||
|
||||
2. Let’s add another user as shown below. Fill in the user details as shown below and click on the “Create” button when you are done.
|
||||
- [Node.js](https://nodejs.org/): v16 or later.
|
||||
- Code Editor: [VS Code](https://code.visualstudio.com/) or similar
|
||||
- [Yarn](https://yarnpkg.com/): This project uses Yarn for dependency management.
|
||||
|
||||
|
||||
### 2. Get the Example Project
|
||||
|
||||
3. The newly created user details will be displayed as shown below.
|
||||
|
||||
|
||||
|
||||
4. Once you navigate back to the "Users" view, you will see a list of all the users that have been added to your instance. If you need to add more users, you can do so.
|
||||
|
||||
|
||||
|
||||
### 6. Add roles to your project (optional)
|
||||
|
||||
1. To add roles to your project, click on “Roles” on the left as shown below. Next, click on the “New” button.
|
||||
|
||||
|
||||
|
||||
2. Let’s create the role “manager” as shown below. Add “Manager” and “Group1” as display name and group respectively.
|
||||
|
||||
|
||||
|
||||
3. You can also add other roles in this step by clicking on “Add additional role”. Let’s go ahead and add two more as shown below. Click “Save” when you are done.
|
||||
|
||||
|
||||
|
||||
4. Now you can view a list of all the roles you just created.
|
||||
|
||||
|
||||
|
||||
### 7. Add authorizations to your project (optional)
|
||||
|
||||
1. Click on “Authorizations” on the top menu.
|
||||
|
||||
|
||||
|
||||
2. Select users for the authorization. You can select 1 or more users for a single authorization grant. Let’s select all the users for this grant.
|
||||
|
||||
|
||||
|
||||
3. Next, select a project. Since we created only “Project1” so far, you will see just that. Go ahead and select it.
|
||||
|
||||
|
||||
|
||||
4. Let’s select the role “sales”. Click on “Save”.
|
||||
|
||||
|
||||
|
||||
5. Now you will see the users with their designated roles.
|
||||
|
||||
|
||||
|
||||
6. To assign additional roles to a user, you can click on the user's name and select the desired roles from the list. This will grant the user additional permissions within the project. Click on “Change”.
|
||||
|
||||
|
||||
|
||||
7. You can see that additional roles have been assigned to the users in this updated authorization list and this should now give you an indication of how authorizations work in ZITADEL.
|
||||
|
||||
|
||||
|
||||
### 8. Obtain ClientId and OIDC endpoints for your application {#referred1}
|
||||
|
||||
You will need the ClientId and the OIDC endpoints (issuer and userinfo) when building your React application. The issuer URL is the base URL for the OIDC provider and includes the path to the OIDC discovery document, which contains information about the OIDC provider, including the authorization and token endpoints. By providing the issuer URL, you can use the OIDC library to automatically determine the endpoints for these requests.
|
||||
|
||||
The authorization endpoint is used to initiate the authorization process, the token endpoint is used to exchange authorization codes for access tokens, and the userinfo endpoint is used to retrieve information about the user. You need an access token to access the userinfo endpoint and other protected resources.
|
||||
|
||||
1. Click on “Configurations” to access the Client ID as shown below:
|
||||
|
||||
|
||||
|
||||
2. The issuer URL and userinfo endpoint can be accessed by clicking on “URLs” on the left. Make note of the corresponding values for “issuer” and “userinfo_endpoint”.
|
||||
|
||||
|
||||
|
||||
And with that, configuring ZITADEL for our application is complete. Now we can move on to building our React application. Let's get coding!
|
||||
|
||||
## Create your React application with ZITADEL OIDC PKCE authentication
|
||||
|
||||
### 1. Functional requirements of the application
|
||||
|
||||
1. The user navigates to the React app (client) and clicks the "login" button.
|
||||
2. The app initiates the authorization process by redirecting the user’s browser to the authorization endpoint of the ZITADEL instance, along with the PKCE parameters (code challenge, and code challenge method).
|
||||
3. The user will see the ZITADEL login page, where the user can enter their credentials.
|
||||
4. After successful authentication, ZITADEL generates an authorization code and redirects the user back to the React app.
|
||||
5. The React app sends a request to the ZITADEL token endpoint, along with the authorization code and code verifier.
|
||||
6. ZITADEL verifies the code verifier to ensure that the authorization request is coming from the same client that initiated it. If it is valid, ZITADEL returns an access token to the React app.
|
||||
7. The React app uses the access token to make a request to the userinfo endpoint, which is protected by the OIDC protocol.
|
||||
8. The userinfo endpoint returns information about the logged-in user, such as their name and email address.
|
||||
9. The React app displays this information to the user.
|
||||
10. When the user wants to log out, the React app sends a request to the ZITADEL logout endpoint, which clears the access token and ends the user's session.
|
||||
11. The user will be redirected to the login page of the app.
|
||||
|
||||
**_The scope of this application for this quick start guide is limited to user authentication and doesn't include role-based authentication, even though we previously discussed adding roles and users._**
|
||||
|
||||
### 2. Prerequisites
|
||||
|
||||
To follow along with this tutorial, you will need to have both Node.js and Visual Studio Code (VSCode) installed on your machine.
|
||||
|
||||
To install React, you will need to have Node.js installed on your system. You can download and install Node.js from [here](https://nodejs.org/).
|
||||
|
||||
To install Visual Studio Code, go to their [website](https://code.visualstudio.com/) and download and install the version for your operating system.
|
||||
|
||||
### 3. Development
|
||||
|
||||
#### 1. Create project
|
||||
|
||||
1. Open a new terminal window in Visual Studio Code.
|
||||
2. Navigate to the folder where you want to create the React app.
|
||||
3. Run the following command to create a new React app named "react-oidc-zitadel":
|
||||
|
||||
`yarn create react-app react-oidc-zitadel --template typescript`
|
||||
|
||||
4. Navigate to the "react-oidc-zitadel" folder:
|
||||
|
||||
`cd react-oidc-zitadel`
|
||||
|
||||
5. The dependencies for this project include @zitadel/react and react-router-dom. To include them in your React application, you will need to run the following command in your terminal:
|
||||
|
||||
`yarn add @zitadel/react react-router-dom`
|
||||
|
||||
#### 2. Add source files
|
||||
|
||||
The code needed to run this project can be found [here](https://github.com/zitadel/zitadel-react).
|
||||
|
||||
1. Replace the content in your App.js file with the one provided below:
|
||||
|
||||
[src/App.tsx](https://github.com/zitadel/zitadel-react/blob/main/src/App.tsx):
|
||||
|
||||
```
|
||||
const config: ZitadelConfig = {
|
||||
authority: "[YOUR-INSTANCE-URL]",
|
||||
client_id: "[YOUR-CLIENT-ID]",
|
||||
redirect_uri: "[YOUR-REDIRECT-URI]",
|
||||
post_logout_redirect_uri: "[YOUR-POST-LOGOUT-REDIRECT-URI]",
|
||||
};
|
||||
|
||||
const zitadel = createZitadelAuth(config);
|
||||
...
|
||||
Clone the repository and move into the project directory:
|
||||
```bash
|
||||
git clone https://github.com/zitadel/zitadel-react.git
|
||||
cd zitadel-react
|
||||
```
|
||||
|
||||
The App.tsx file is the root component of the React app that initializes the OIDC flow and manages the user's session. It does this by:
|
||||
### 3. Build and Install
|
||||
|
||||
- Importing the necessary libraries and components from the dependencies, including the `@zitadel/react` library and the Login and Callback components.
|
||||
- Initializing a new `zitadel` instance with the OIDC configuration values. The `zitadel` instance manages the OIDC flow and stores the user's session information.
|
||||
- Defining two functions: `authorize` and `signout`. The `authorize` function initiates the OIDC flow when the user clicks the `login` button, while the `signout` function ends the user's session when the user clicks the `logout` button.
|
||||
- Defining state variable: `authenticated`. The authenticated variable is a boolean that indicates whether the user is authenticated or not.
|
||||
- Using the `useEffect` hook to retrieve the user's session information from the `UserManager` instance and updating the `authenticated` state variable accordingly.
|
||||
- Defining the routes for the app using the `react-router-dom` library, including the `/` and `/callback` routes for the login and callback pages, respectively. The `Login` and `Callback` components handle the login and callback processes, respectively.
|
||||
Since this repo contains the SDK source, you need to build the library before running the example:
|
||||
```bash
|
||||
# Build the SDK library
|
||||
cd lib && yarn install && yarn build
|
||||
|
||||
The provided config extends the `UserManagerSettings` of the `oidc-client-ts` library. Take a look at some of the available configuration options:
|
||||
|
||||
- authority (the URL of your instance ending with /).
|
||||
- client\*id (the unique identifier for the client application).
|
||||
- redirect_uri (the URL to redirect to after the authorization flow is complete)
|
||||
- post_logout_redirect_uri (the URL to redirect to after the user logs out)
|
||||
- scope (the permissions requested from the user)
|
||||
- project_resource_id (To add a ZITADEL project scope. `urn:zitadel:iam:org:project:id:[projectId]:aud` and `urn:zitadel:iam:org:projects:roles` [scopes](/docs/apis/openidoauth/scopes#reserved-scopes).)
|
||||
- prompt ([the OIDC prompt parameter](/apis/openidoauth/endpoints#additional-parameters))
|
||||
|
||||
2. Create a folder named components in the src directory. Create two files named Login.js and Callback.js.
|
||||
|
||||
3. Paste the following code to Login.tsx.
|
||||
|
||||
```ts reference
|
||||
https://github.com/zitadel/zitadel-react/blob/main/src/components/Login.tsx
|
||||
# Install example app dependencies
|
||||
cd .. && yarn install
|
||||
```
|
||||
|
||||
The `/` route corresponds to the login page, which is rendered by the Login component. The Login(Login.tsx) component is a functional component that displays the login button and calls the `handleLogin` function (which corresponds to the `authorize` function defined in the App component) when the button is clicked. This initiates the OIDC flow by redirecting the user to the authorization endpoint.
|
||||
### 4. Configure your Credentials
|
||||
|
||||
4. Paste the following code to Callback.js.
|
||||
Open src/App.tsx and update the config object with the **Issuer** and **Client ID** you collected in Step 5.
|
||||
|
||||
```ts reference
|
||||
https://github.com/zitadel/zitadel-react/blob/main/src/components/Callback.tsx
|
||||
```typescript
|
||||
const config: ZitadelConfig = {
|
||||
authority: "https://your-instance.zitadel.cloud", // Your Issuer URL
|
||||
client_id: "YOUR_CLIENT_ID", // Your Client ID
|
||||
redirect_uri: "http://localhost:3000/callback",
|
||||
post_logout_redirect_uri: "http://localhost:3000",
|
||||
response_type: 'code',
|
||||
scope: 'openid profile email'
|
||||
};
|
||||
```
|
||||
|
||||
The `/callback` route corresponds to the callback page, which is rendered by the Callback (Callback.tsx) component.
|
||||
The Callback component is also a functional component that handles the callback from the authorization server after the user logs in.
|
||||
It retrieves the authorization code from the URL, exchanges it for an access token and id token, and retrieves the user's information from the userinfo endpoint.
|
||||
It also sets the `authenticated` state variable in the App (App.tsx) component and displays the `logout` button.
|
||||
When the `logout` button is clicked, the `clearAuth` function is called and the user's session is ended. The `clearAuth` function is defined in the App component and is called with no arguments. It initiates the end session flow by redirecting the user to the end session endpoint.
|
||||
### 5. Run the Application
|
||||
|
||||
Note that the @zitadel/react library automatically handles the generation of the code verifier and code challenge when the user clicks on the login button, eliminating the need for the application to manually generate and include these values in the requests.
|
||||
Start your development server:
|
||||
```bash
|
||||
yarn start
|
||||
```
|
||||
|
||||
In the PKCE flow, the code verifier is a random string generated by the client application, and the code challenge is a transformed version of the code verifier using the SHA-256 hashing algorithm.
|
||||
Your app will be live at `http://localhost:3000`. Click Login to test the full PKCE flow!
|
||||
|
||||
5. Now you can think about styling your application. Edit the `index.css` and `App.css` to apply CSS styling to the pages.
|
||||
|
||||
|
||||
### 3. Running the application
|
||||
## Success! 🚀
|
||||
You’ve successfully integrated ZITADEL into a React application.
|
||||
|
||||
1. Run `yarn start` to start the development server.
|
||||
2. Open your browser and navigate to `http://localhost:3000/` to view the app.
|
||||
3. You will see the login page, which is the landing page of the app, when you run the application. Click on the “Please log in” button.
|
||||
### What’s next?
|
||||
- [**SSO**](/docs/guides/integrate/services): Learn how to add SSO to your services
|
||||
- [**Customize the UI**](/docs/guides/manage/customize/branding): Make the login page your own with Branding.
|
||||
- [**Explore the API**](/docs/apis/introduction): Check out the ZITADEL API Reference for advanced integrations.
|
||||
|
||||
|
||||
|
||||
4. You will be redirected to the ZITADEL login page. Add your username/email and click on “next”.
|
||||
|
||||
|
||||
|
||||
5. Enter your password and click on “next”.
|
||||
|
||||
|
||||
|
||||
6. If you entered the correct login credentials (and if the PKCE parameters generated by the application match), you will be redirected to the callback page, which displays your user information.
|
||||
|
||||
|
||||
|
||||
7. You can click on “Log out” to log out of the application and you will be taken to the landing page.
|
||||
|
||||
|
||||
|
||||
And this brings us to the end of this quick start guide!
|
||||
|
||||
This tutorial covered how to configure ZITADEL and how to use React to build an app that communicates with ZITADEL to access secured resources.
|
||||
|
||||
We hope you enjoyed the tutorial and encourage you to check out the ZITADEL [documentation](/docs) for more information on how to use the ZITADEL platform to its full potential. Thanks for joining us!
|
||||
Need help? Join our [Discord community](https://zitadel.com/chat) or explore the full Documentation. Happy coding!
|
||||
BIN
Binary file not shown.
|
Before Width: | Height: | Size: 350 KiB |
BIN
Binary file not shown.
|
Before Width: | Height: | Size: 250 KiB |
BIN
Binary file not shown.
|
Before Width: | Height: | Size: 264 KiB |
BIN
Binary file not shown.
|
Before Width: | Height: | Size: 436 KiB |
BIN
Binary file not shown.
|
Before Width: | Height: | Size: 277 KiB |
BIN
Binary file not shown.
|
Before Width: | Height: | Size: 313 KiB |
BIN
Binary file not shown.
|
Before Width: | Height: | Size: 935 KiB |
BIN
Binary file not shown.
|
Before Width: | Height: | Size: 337 KiB |
BIN
Binary file not shown.
|
Before Width: | Height: | Size: 265 KiB |
BIN
Binary file not shown.
|
Before Width: | Height: | Size: 293 KiB |
BIN
Binary file not shown.
|
Before Width: | Height: | Size: 314 KiB |
BIN
Binary file not shown.
|
Before Width: | Height: | Size: 311 KiB |
BIN
Binary file not shown.
|
Before Width: | Height: | Size: 325 KiB |
BIN
Binary file not shown.
|
Before Width: | Height: | Size: 144 KiB |
BIN
Binary file not shown.
|
Before Width: | Height: | Size: 822 KiB |
BIN
Binary file not shown.
|
Before Width: | Height: | Size: 350 KiB |
BIN
Binary file not shown.
|
Before Width: | Height: | Size: 545 KiB |
BIN
Binary file not shown.
|
Before Width: | Height: | Size: 449 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 445 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 465 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 212 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 675 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 607 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 637 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 636 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 294 KiB After Width: | Height: | Size: 253 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 486 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 418 KiB After Width: | Height: | Size: 388 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 474 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 222 KiB |
BIN
Binary file not shown.
|
Before Width: | Height: | Size: 827 KiB |
BIN
Binary file not shown.
|
Before Width: | Height: | Size: 439 KiB |
BIN
Binary file not shown.
|
Before Width: | Height: | Size: 464 KiB |
BIN
Binary file not shown.
|
Before Width: | Height: | Size: 575 KiB |
BIN
Binary file not shown.
|
Before Width: | Height: | Size: 211 KiB |
Generated
+644
-451
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user