andwati/zitadel
1
0
Fork 0
mirror of https://github.com/andwati/zitadel.git synced 2026-10-18 05:52:51 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: added the updated docs for the new react example (#11073)

Browse Source 
# Which Problems Are Solved

The React example needed updates to align with current best practices
and improve documentation clarity for developers integrating Zitadel
authentication.

# How the Problems Are Solved

Updated the React example codebase with improved authentication flow
using react-oidc-context, enhanced error handling and TypeScript type
safety, and refined component structure for better maintainability.

# Additional Changes

Updated documentation to reflect implementation details, added
comprehensive environment variable configuration examples with exact
variable names from the codebase, improved inline code comments, and
updated dependencies to latest stable versions.

# Additional Context

- Related to React integration example improvements
- Enhances developer experience when implementing Zitadel PKCE
authentication in React applications
This commit is contained in:
Mridang Agarwalla
2025-11-17 20:22:51 +00:00
committed by GitHub
parent 0f1b7c6eaa
commit afa92e55f7
1 changed files with 66 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/docs/sdk-examples/react.mdx
+66 -51
View File
@@ -1,72 +1,87 @@
---
title: React
sidebar_label: React
framework_url: https://react.dev
auth_library: oidc-client-ts
auth_library_url: https://www.npmjs.com/package/oidc-client-ts
example_repo: https://github.com/zitadel/example-auth-react
auth_flow: pkce
status: stable
---
<table>
<tr>
<td width="100px">
<img width="100px" src="/docs/img/tech/react.png" alt="react" />
</td>
<td>
<a href="https://react.dev/" target="_blank">
React
</a>{" "}
is a declarative, component-based JavaScript library for building user
interfaces. Integrate authentication to your React application easily by
using the{" "}
<a href="https://github.com/zitadel/zitadel-react" target="_blank">
zitadel-react
</a>{" "}
SDK.
</td>
</tr>
</table>
## Overview
### Resources
[React](https://react.dev) is a JavaScript library for building user interfaces with component composition, declarative views, and a rich ecosystem. This example demonstrates how to integrate **Zitadel** using the **[OAuth 2.0 PKCE flow](/docs/concepts/pkce)** to authenticate users securely and maintain sessions across your React application.
- [SDK with Example App](https://github.com/zitadel/zitadel-react)
- [Step-By-Step Guide](/docs/examples/login/react)
#### Auth library
### React SDK
This example uses **[react-oidc-context](https://www.npmjs.com/package/react-oidc-context)**, a React wrapper around **[oidc-client-ts](https://www.npmjs.com/package/oidc-client-ts)**. The underlying [oidc-client-ts](https://github.com/authts/oidc-client-ts) library implements the [OpenID Connect (OIDC)](https://zitadel.com/docs/apis/openidoauth/endpoints) protocol, manages [PKCE](/docs/concepts/pkce) code challenge generation, performs secure [token exchange](https://zitadel.com/docs/concepts/tokens), and exposes React hooks for managing authentication state throughout your application.
The [zitadel-react](https://github.com/zitadel/zitadel-react) SDK is a wrapper around the [oidc-client-ts](https://www.npmjs.com/package/oidc-client-ts) and abstracts the handling of specific configurations for ZITADEL.
---
The following features are covered by the SDK:
## What this example demonstrates
- Authenticate your user with ZITADEL using OIDC
- Requesting ZITADEL userinfo endpoint to get user data
- Refresh Token
- Requesting User Roles from userinfo
- Check if user has specified role
- Logout
This [React](https://react.dev) application showcases a complete authentication flow using [Zitadel](https://zitadel.com/docs) with the secure [PKCE](/docs/concepts/pkce) standard. Users begin on a public landing page where they can initiate login through [react-oidc-context](https://www.npmjs.com/package/react-oidc-context), which redirects them to [Zitadel's authorization endpoint](https://zitadel.com/docs/apis/openidoauth/endpoints) for authentication. After successful authentication, the application handles the OAuth callback, exchanges the authorization code for [access tokens](https://zitadel.com/docs/concepts/tokens), and establishes a secure [session](https://zitadel.com/docs/apis/openidoauth/endpoints).
The goal is to extend the SDK over the time with the following features:
Protected routes are secured using [react-oidc-context's](https://www.npmjs.com/package/react-oidc-context) `withAuthenticationRequired` higher-order component, which automatically redirects unauthenticated users to the login flow. The profile page displays user information retrieved from [OIDC claims](https://zitadel.com/docs/apis/openidoauth/claims), including profile details, email, and metadata. The application implements complete [federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout) functionality, properly terminating both the local session and the Zitadel session through the end-session endpoint.
- Integrate ZITADEL APIs to read and manage resources
- Build your own login UI using our Session API
The example leverages [React Router](https://reactrouter.com) for client-side navigation and [Vite](https://vite.dev) as the build tool, demonstrating modern React development patterns with [TypeScript](https://www.typescriptlang.org). All authentication state management, including [token refresh](https://zitadel.com/docs/concepts/tokens) with offline access, is handled automatically by the [oidc-client-ts](https://www.npmjs.com/package/oidc-client-ts) library under the hood.
### Example Application
---
The [zitadel-react](https://github.com/zitadel/zitadel-react) repository also includes an Example Application ready to start and show how a React application looks like with integrated ZITADEL Login.
## Getting started
What does the Example include:
### Prerequisites
- Home Page with Login Button
- Authenticating user with OIDC PKCE Flow
- Public Page: Accessible without authentication
- Private Page: Shows user information of authenticated user, only accessible after login
- Administrator Page: Only accessible after login and with specific administrator role for the application
- Logout
Before running this example, you need to create and configure a PKCE application in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/overview). Follow the **[PKCE Application Setup guide](/docs/guides/integrate/login/oidc/pkce-setup)** to:
### Step-By-Step Guide
1. Create a new Web application in your [Zitadel project](https://zitadel.com/docs/guides/integrate/login/oidc/)
2. Configure it to use the [PKCE authentication method](/docs/concepts/pkce)
3. Set up your redirect URIs (e.g., `http://localhost:3000/auth/callback` for development)
4. Configure post-logout redirect URIs (e.g., `http://localhost:3000/`)
5. Copy your **Client ID** for use in the next steps
The [Step-By-Step Guide](/docs/examples/login/react) leads you through the whole process from configuring the right application in ZITADEL to a ready application with integrated Login.
> **Note:** Make sure to enable **Dev Mode** in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/overview) if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode.
After completing the Step-By-Step Guide you will have:
### Run the example
1. Example Web Application with integrated ZITADEL Login
2. Example page accessible by authenticated user showing retrieved user information
3. Example administrator page accessible by user with administrator role
4. Logout
5. Correct setup for your application in ZITADEL
Once you have your Zitadel application configured:
1. Clone the [repository](https://github.com/zitadel/example-auth-react).
2. Create a `.env` file (copy from `.env.example`) and configure it with the values from your [Zitadel application](https://zitadel.com/docs/guides/manage/console/overview). **Use these exact environment variable names:**
```
VITE_ZITADEL_DOMAIN=https://your-instance.zitadel.cloud
VITE_ZITADEL_CLIENT_ID=your_client_id_from_console
VITE_ZITADEL_CALLBACK_URL=http://localhost:3000/auth/callback
VITE_ZITADEL_POST_LOGOUT_URL=http://localhost:3000/
VITE_POST_LOGIN_URL=/profile
VITE_PORT=3000
```
Replace these values with:
- Your actual Zitadel instance URL (the **Issuer** from your [Zitadel application settings](https://zitadel.com/docs/guides/integrate/login/oidc/))
- The **Client ID** you copied when creating the application
- The **redirect URI** you configured in the [PKCE setup](/docs/guides/integrate/login/oidc/pkce-setup) (must match exactly)
- The **post-logout redirect URI** you configured
3. Install dependencies using [npm](https://www.npmjs.com) and start the development server:
```bash
npm install
npm run dev
```
The application will be running at `http://localhost:3000` where you can test the complete authentication flow.
---
## Learn more and resources
* **Zitadel documentation:** [https://zitadel.com/docs](https://zitadel.com/docs)
* **PKCE concept:** /docs/concepts/pkce
* **PKCE application setup:** /docs/guides/integrate/login/oidc/pkce-setup
* **Federated logout:** [https://zitadel.com/docs/guides/integrate/login/oidc/logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)
* **OIDC integration guide:** [https://zitadel.com/docs/guides/integrate/login/oidc/](https://zitadel.com/docs/guides/integrate/login/oidc/)
* **React documentation:** https://react.dev
* **react-oidc-context:** https://www.npmjs.com/package/react-oidc-context
* **oidc-client-ts:** https://www.npmjs.com/package/oidc-client-ts
* **React Router:** https://reactrouter.com
* **Example repository:** https://github.com/zitadel/example-auth-react
* **All framework examples:** /docs/examples