diff --git a/docs/docs/sdk-examples/react.mdx b/docs/docs/sdk-examples/react.mdx index edbd20bc9..9ae4b0bfd 100644 --- a/docs/docs/sdk-examples/react.mdx +++ b/docs/docs/sdk-examples/react.mdx @@ -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 --- - - - - - -
- react - - - React - {" "} - is a declarative, component-based JavaScript library for building user - interfaces. Integrate authentication to your React application easily by - using the{" "} - - zitadel-react - {" "} - SDK. -
+## 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