mirror of
https://github.com/zitadel/zitadel.git
synced 2026-07-25 18:28:00 +00:00
86 lines
9.0 KiB
Plaintext
86 lines
9.0 KiB
Plaintext
---
|
|
title: React
|
|
description: "Integrate ZITADEL authentication into React applications using the OAuth 2.0 PKCE flow."
|
|
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
|
|
---
|
|
|
|
## Overview
|
|
|
|
[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](https://oauth.net/2/pkce/)** to authenticate users securely and maintain sessions across your React application.
|
|
|
|
#### Auth library
|
|
|
|
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/react-oidc-context)**, a React wrapper around **[oidc-client-ts](https://www.npmjs.com/package/oidc-client-ts)**. The underlying [oidc-client-ts](https://www.npmjs.com/package/react-oidc-context)**, a React wrapper around **[oidc-client-ts](https://www.npmjs.com/package/oidc-client-ts) library implements the [OpenID Connect (OIDC)](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](https://www.npmjs.com/package/react-oidc-context) code challenge generation, performs secure [token exchange](https://zitadel.com/docs/apis/openidoauth/endpoints#token_endpoint), and exposes React hooks for managing authentication state throughout your application.
|
|
|
|
---
|
|
|
|
## What this example demonstrates
|
|
|
|
This [React](https://react.dev) application showcases a complete authentication flow using [Zitadel](https://react.dev) application showcases a complete authentication flow using [Zitadel](https://zitadel.com/docs) with the secure [PKCE](https://react.dev) standard. Users begin on a public landing page where they can initiate login through [react-oidc-context](https://react.dev) application showcases a complete authentication flow using [Zitadel](https://zitadel.com/docs) with the secure [PKCE](https://oauth.net/2/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://react.dev) application showcases a complete authentication flow using [Zitadel](https://zitadel.com/docs) with the secure [PKCE](https://oauth.net/2/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/apis/openidoauth/endpoints#token_endpoint), and establishes a secure [session](https://react.dev) application showcases a complete authentication flow using [Zitadel](https://zitadel.com/docs) with the secure [PKCE](https://oauth.net/2/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).
|
|
|
|
Protected routes are secured using [react-oidc-context's](https://react.dev) application showcases a complete authentication flow using [Zitadel](https://zitadel.com/docs) with the secure [PKCE](https://oauth.net/2/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) `withAuthenticationRequired` higher-order component, which automatically redirects unauthenticated users to the login flow. The profile page displays user information retrieved from [OIDC claims](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://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.
|
|
|
|
The example leverages [React Router](https://reactrouter.com) for client-side navigation and [Vite](https://reactrouter.com) for client-side navigation and [Vite](https://vite.dev) as the build tool, demonstrating modern React development patterns with [TypeScript](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/apis/openidoauth/endpoints#token_endpoint) with offline access, is handled automatically by the [oidc-client-ts](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/apis/openidoauth/endpoints#token-endpoint) with offline access, is handled automatically by the [oidc-client-ts](https://www.npmjs.com/package/oidc-client-ts) library under the hood.
|
|
|
|
---
|
|
|
|
## Getting started
|
|
|
|
### Prerequisites
|
|
|
|
Before running this example, you need to create and configure a PKCE application in the [ZITADEL Management Console](https://zitadel.com/docs/guides/manage/console/console-overview). Follow the PKCE application setup guide to:
|
|
|
|
1. Create a new Web application in your [Zitadel project](https://zitadel.com/docs/guides/manage/console/projects-overview)
|
|
2. Configure it to use the PKCE authentication method
|
|
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
|
|
|
|
> **Note:** Make sure to enable **Dev Mode** in the [ZITADEL Management Console](https://zitadel.com/docs/guides/manage/console/console-overview) if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode.
|
|
|
|
### Run the example
|
|
|
|
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/applications-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/login-users))
|
|
- The **Client ID** you copied when creating the application
|
|
- The **redirect URI** you configured in the 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
|
|
|
|
* [PKCE concept](https://oauth.net/2/pkce/)
|
|
* [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)
|
|
* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/login-users)
|
|
* [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)
|