diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index dc794e9..a146840 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -104,6 +104,12 @@ on: type: boolean default: false + sample_b2b_manage: + description: 'b2b/manage' + required: false + type: boolean + default: false + permissions: contents: write @@ -141,6 +147,7 @@ jobs: sample_better_auth_nextjs: ${{ github.event.inputs.sample_better_auth_nextjs }} sample_flutter_app_auth: ${{ github.event.inputs.sample_flutter_app_auth }} sample_self_care_account: ${{ github.event.inputs.sample_self_care_account }} + sample_b2b_manage: ${{ github.event.inputs.sample_b2b_manage }} run: | samples='[]' add() { @@ -161,6 +168,7 @@ jobs: add sample_better_auth_nextjs '{"path":"integrations/better-auth-nextjs","emoji":"๐Ÿ”","title":"ThunderID Better Auth Next.js Sample"}' add sample_flutter_app_auth '{"path":"integrations/flutter-app-auth","emoji":"๐Ÿฆ‹","title":"ThunderID Flutter AppAuth Sample"}' add sample_self_care_account '{"path":"self-care/account","emoji":"๐Ÿ‘ค","title":"ThunderID Self-Care Account Sample"}' + add sample_b2b_manage '{"path":"b2b/manage","emoji":"๐Ÿข","title":"ThunderID B2B Manage Sample"}' if [ "$samples" = "[]" ]; then echo "โŒ No sample selected. Check at least one sample_* input." exit 1 diff --git a/AGENTS.md b/AGENTS.md index 6eaf2f6..5198070 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -26,14 +26,52 @@ on a pull request. ## Adding a sample -- Put it under the area it belongs to and give it a `README.md` that starts with its banner. - Follow the sample-banner skill to render the banner and reference it. +- Put it under the area it belongs to and give it a `README.md` that follows the structure + below. Follow the sample-banner skill to render its banner. - Depend on the published SDK release, never a workspace or local path. - Add a row to the table in the root `README.md`. +- Add it to `.github/workflows/release.yml`, in the same pull request, so it can be released. + The workflow has no automatic discovery, so a sample left out of it never gets a release or + a download. Add all three, in the same order as the other samples: + - a `sample_` boolean input under `workflow_dispatch.inputs`, described by its path; + - the matching `sample_: ${{ github.event.inputs.sample_ }}` line in the + **Plan Releases** step's `env`; + - an `add sample_ '{"path":"/","emoji":"โ€ฆ","title":"ThunderID โ€ฆ Sample"}'` + line in that step's script. + + `workflow_dispatch` allows at most 25 inputs. Count them before adding one. - Keep its manifest (`package.json`, `pubspec.yaml`, `settings.gradle.kts`, or `Package.swift`) at the sample root. The pull request builder finds samples by that file at exactly `//`. +## Sample README structure + +Every sample README uses the same sections, in this order. Copy an existing README of the same +kind (for example `quickstarts/react/README.md` for a web app, `quickstarts/android/README.md` +for a mobile app) and adapt it rather than starting from scratch. + +1. The banner image, then a blank line. See the sample-banner skill. +2. `# `, matching the banner's alt text, such as `ThunderID React Quickstart` or + `ThunderID Manage Sample`. +3. An intro of one or two paragraphs: what the app does, and the SDK or package it uses, linked. + A short list or table of what it shows can follow. +4. `## Prerequisites`: the runtime and tools with minimum versions, then a running ThunderID + server, with `https://localhost:8090` as the default. +5. `## Get the sample`: the releases link filtered to the sample + (`https://github.com/thunder-id/samples/releases?q=sample%2F<area>%2F<sample>&expanded=true`) + and `npx degit thunder-id/samples/<area>/<sample> my-app`. +6. `## Configure`: creating the application in the Console, named by its Console template + (**React**, **Next.js**, **JavaScript**, and so on), then copying the config template and a + table of every variable it holds. +7. `## Run`: the commands, then the URL to open or what to expect. +8. Optional sections specific to the sample, such as `## How it works`, `## Where things are`, + or a feature walkthrough. +9. `## Learn more`: the docs quickstart guide and the SDK reference on thunderid.dev. +10. `## License`: `Apache License 2.0. See [LICENSE](https://github.com/thunder-id/samples/blob/main/LICENSE).` + +Write in plain, direct sentences. Link only to pages that exist; check thunderid.dev links +before adding them. + ## Package manager JavaScript samples use npm, so that a developer who copies one out needs nothing beyond Node.js. diff --git a/b2b/manage/README.md b/b2b/manage/README.md index fb179d6..7c5fb38 100644 --- a/b2b/manage/README.md +++ b/b2b/manage/README.md @@ -1,75 +1,78 @@ ![ThunderID Manage Sample](https://raw.githubusercontent.com/thunder-id/samples/main/.github/assets/banners/b2b-manage.png) -# ThunderID Manage +# ThunderID Manage Sample -ThunderID Manage is a sample app for trying out the ThunderID React SDK on B2B management services. An administrator signs in and manages the resources of a ThunderID server from one place. It is a React (Vite + TypeScript) app built with the [ThunderID React SDK](https://www.npmjs.com/package/@thunderid/react). - -## What's included +A React (Vite and TypeScript) app where an administrator signs in and manages the resources of a ThunderID server from one place, built with the [ThunderID React SDK](https://www.npmjs.com/package/@thunderid/react) (`@thunderid/react`). It has two sections: - **Home**: a short page that explains what the app is for. -- **Agents**: the agent onboarding experience, built with the SDK's React components. You can see the agents on your server, create one through the ThunderID agent onboarding flow, and delete one. - -When you create an agent, the app starts the onboarding flow that lives on your ThunderID server. The SDK draws each step the flow sends back: who owns the agent, the agent's details, and the new credentials. The client secret is shown once, hidden behind dots until you choose to show it. +- **Agents**: lists the agents on your server, creates one through the ThunderID agent onboarding flow, and deletes one. -These SDK components are used: +Creating an agent starts the onboarding flow that lives on your ThunderID server. The SDK draws each step the flow sends back: who owns the agent, the agent's details, and the new credentials. The client secret is shown once, hidden until you choose to show it. -| Where | SDK component | -| -------------------------- | ----------------------------------------------------- | -| App setup | `ThunderIDProvider` | -| Top bar and home page | `SignInButton`, `SignedIn`, `SignedOut`, `Loading` | -| Signed-in user | `UserDropdown`, `User` | -| Agents pages | `ProtectedRoute` (from `@thunderid/react-router`) | -| Create agent | `BaseInviteUser`, which runs the flow and draws steps | -| Owner step | The user picker (`BaseUserSelect`) | -| Details and dropdown steps | `TextField`, `Select` | -| Credentials step | `CopyableText`, with the secret hidden until shown | -| Buttons | `Button` | +| Where | SDK component | +| -------------------------- | --------------------------------------------------------- | +| App setup | `ThunderIDProvider` | +| Top bar and home page | `SignInButton`, `SignedIn`, `SignedOut`, `Loading` | +| Signed-in user | `UserDropdown`, `User` | +| Agents pages | `ProtectedRoute` (from `@thunderid/react-router`) | +| Create agent | `BaseInviteUser`, which runs the flow and draws its steps | +| Owner step | The user picker, `BaseUserSelect` | +| Details and dropdown steps | `TextField`, `Select` | +| Credentials step | `CopyableText`, with the secret hidden until shown | +| Buttons | `Button` | -The app also uses the SDK hooks `useThunderID`, `useFetchUsers`, `useFetchAuthFlows`, `useFetchUserTypes`, `useTheme` and `useTranslation`. The organization unit dropdown and the step buttons are drawn by the app itself, through the SDK's custom renderers. +The app also uses the SDK hooks `useThunderID`, `useFetchUsers`, `useFetchAuthFlows`, `useFetchUserTypes`, `useTheme`, and `useTranslation`. The organization unit dropdown and the step buttons are drawn by the app itself, through the SDK's custom renderers. ## Prerequisites -- Node.js 20+ and npm -- ThunderID React SDK 1.4.0 or later (`@thunderid/react`). It is the first release with the user picker (`BaseUserSelect` and `useFetchUsers`) and the masked `CopyableText` that this sample uses. `npm install` fetches it, together with `@thunderid/react-router` 1.3.0. -- A running ThunderID server (defaults to `https://localhost:8090`) and an administrator account +- Node.js 20 or later +- A running ThunderID server (`https://localhost:8090` by default) and an administrator account - The agent onboarding flow on that server. A standard install already has one, named `default-agent-onboarding-flow`. -New to ThunderID with React? Follow the [React quickstart guide](https://thunderid.dev/docs/next/getting-started/connect-your-application/react/) to set up a ThunderID server and connect a React app to it. +The sample needs `@thunderid/react` 1.4.0 or later, the first release with the user picker (`BaseUserSelect` and `useFetchUsers`) and the masked `CopyableText`. `npm install` fetches it. + +## Get the sample -## Setup +Download the latest zip from the [releases](https://github.com/thunder-id/samples/releases?q=sample%2Fb2b%2Fmanage&expanded=true), or copy the source: -1. Start your ThunderID server. +```bash +npx degit thunder-id/samples/b2b/manage my-app +cd my-app +``` -2. In the ThunderID Console, [create a React application](https://thunderid.dev/docs/getting-started/connect-your-application/react/#:~:text=2-,Create%20an%20Application,-Sign%20in%20to). Use `http://localhost:5173` as the redirect URL, and copy the client ID it gives you. Then add `http://localhost:5173` to the allowed origins (Settings โ†’ CORS), or the browser will block the sign-in requests. +## Configure -3. Configure the app: +1. In the ThunderID Console, create a **React** application with `http://localhost:5173` as its redirect URL, and copy its client ID. Then add `http://localhost:5173` to the allowed origins (**Settings โ†’ CORS**), or the browser blocks the sign-in requests. + +2. Create your `.env`: ```bash cp .env.example .env ``` - | Variable | Description | - | ----------------------------------- | ----------------------------------------------------------------------------------------------------------- | - | `VITE_THUNDERID_BASE_URL` | Base URL of your ThunderID server. | - | `VITE_THUNDERID_CLIENT_ID` | Client ID of the application (from step 2). | - | `VITE_AGENT_ONBOARDING_FLOW_HANDLE` | Handle of the flow that creates agents. Defaults to `default-agent-onboarding-flow`. | - | `VITE_THUNDERID_RESOURCE` | Optional. The part of ThunderID that guards admin information. A standard install already uses the default. | + | Variable | Description | + | ----------------------------------- | -------------------------------------------------------------------------------------------------- | + | `VITE_THUNDERID_BASE_URL` | Base URL of your ThunderID server. | + | `VITE_THUNDERID_CLIENT_ID` | Client ID of the application. | + | `VITE_AGENT_ONBOARDING_FLOW_HANDLE` | Handle of the flow that creates agents. Defaults to `default-agent-onboarding-flow`. | + | `VITE_THUNDERID_RESOURCE` | Optional. The resource that guards admin information. A standard install already uses the default. | -4. Install and start: +## Run - ```bash - npm install - npm run dev - ``` +```bash +npm install +npm run dev +``` -5. Open `http://localhost:5173` and sign in as an administrator. +Open [http://localhost:5173](http://localhost:5173) and sign in as an administrator. -Only administrators can use the Agents section. Anyone else can sign in, but the server turns down the requests and the page shows an error. +Only administrators can use the **Agents** section. Anyone else can sign in, but the server turns down the requests and the page shows an error. -## Docs +## Learn more -- Full SDK reference: [thunderid.dev/docs](https://thunderid.dev/docs) +- [React quickstart guide](https://thunderid.dev/docs/getting-started/connect-your-application/react) +- [React SDK reference](https://thunderid.dev/docs/sdks-and-tools/react/overview) ## License -Apache License 2.0. +Apache License 2.0. See [LICENSE](https://github.com/thunder-id/samples/blob/main/LICENSE). diff --git a/integrations/better-auth-nextjs/README.md b/integrations/better-auth-nextjs/README.md index 3178f7b..d636c5c 100644 --- a/integrations/better-auth-nextjs/README.md +++ b/integrations/better-auth-nextjs/README.md @@ -1,71 +1,72 @@ ![ThunderID Better Auth Sample](https://raw.githubusercontent.com/thunder-id/samples/main/.github/assets/banners/integrations-better-auth-nextjs.png) -# Better Auth + ThunderID Sample +# ThunderID Better Auth Sample -<a href="https://stackblitz.com/fork/github/thunder-id/samples/tree/main/integrations/better-auth-nextjs?file=.env" target="_blank"><img src="https://developer.stackblitz.com/img/open_in_stackblitz.svg" alt="Open in StackBlitz" /></a> +A Next.js 15 App Router app that signs users in to ThunderID through [Better Auth](https://better-auth.com)'s [Generic OAuth plugin](https://better-auth.com/docs/plugins/generic-oauth), configured with the [`@thunderid/better-auth`](https://www.npmjs.com/package/@thunderid/better-auth) provider helper. -A minimal Next.js 15 App Router application demonstrating [Better Auth](https://better-auth.com)'s -[Generic OAuth plugin](https://better-auth.com/docs/plugins/generic-oauth) configured for ThunderID via the -[`@thunderid/better-auth`](https://github.com/thunder-id/javascript-sdks/tree/main/packages/better-auth) provider helper. - -All OAuth 2.0 / OIDC handling is performed by Better Auth itself โ€” this sample has no ThunderID SDK -dependency, and keeps users/sessions in an in-memory store (`better-auth/adapters/memory`) that resets on -every server restart. Swap it for a real [database adapter](https://better-auth.com/docs/adapters) in a real -app. +Better Auth does all the OAuth 2.0 and OIDC work; there is no ThunderID SDK in the app. Users and sessions live in an in-memory store (`better-auth/adapters/memory`) that resets when the server restarts. Use a real [database adapter](https://better-auth.com/docs/adapters) in your own app. ## Prerequisites -- Node.js 18+ -- A ThunderID application with an OAuth 2.0 / OIDC (`authorization_code`) client +- Node.js 20 or later +- A running ThunderID server (`https://localhost:8090` by default) -## Getting started +## Get the sample -1. Copy the example environment file: +Download the latest zip from the [releases](https://github.com/thunder-id/samples/releases?q=sample%2Fintegrations%2Fbetter-auth-nextjs&expanded=true), or copy the source: - ```bash - cp .env.example .env - ``` +```bash +npx degit thunder-id/samples/integrations/better-auth-nextjs my-app +cd my-app +``` -2. Fill in your ThunderID credentials in `.env`: +## Configure - ```dotenv - BETTER_AUTH_SECRET=<run: openssl rand -base64 32> - BETTER_AUTH_URL=http://localhost:3000 - THUNDERID_ISSUER=https://localhost:8090 - THUNDERID_CLIENT_ID=<your-client-id> - THUNDERID_CLIENT_SECRET=<your-client-secret> - ``` +1. In the ThunderID Console, create an application with an OAuth 2.0 client that uses the `authorization_code` grant and has a client secret. Register this redirect URL on it: - `THUNDERID_CLIENT_ID` and `THUNDERID_CLIENT_SECRET` come from the application's Credentials tab in the - ThunderID console. - -3. Register the redirect URI on your ThunderID application (see the app's config notice in this sample for - the exact value to use): - - ``` + ```text http://localhost:3000/api/auth/callback/thunderid ``` -4. Install dependencies and start the development server: + Copy its client ID and client secret from the **Credentials** tab. + +2. Create your `.env`: ```bash - npm install - npm run dev + cp .env.example .env ``` - The app is now running at [http://localhost:3000](http://localhost:3000). Click **Sign in with - ThunderID** to try the flow. + | Variable | Description | + |---|---| + | `BETTER_AUTH_SECRET` | Signs and encrypts Better Auth's session cookies. Generate it with `openssl rand -base64 32`. | + | `BETTER_AUTH_URL` | Base URL the app is served from. The callback URL is derived from it. | + | `THUNDERID_ISSUER` | Your ThunderID server's issuer URL. | + | `THUNDERID_CLIENT_ID` | Client ID of the application. | + | `THUNDERID_CLIENT_SECRET` | Client secret of the application. Server-only. | + | `NODE_TLS_REJECT_UNAUTHORIZED` | Set to `0` in the example to accept a local server's self-signed certificate. Local development only. | + +## Run + +```bash +npm install +npm run dev +``` + +Open [http://localhost:3000](http://localhost:3000) and click **Sign in with ThunderID**. ## How it works -- [`lib/auth.ts`](./lib/auth.ts) โ€” the Better Auth server instance. Registers the `genericOAuth` plugin with - the `thunderid()` helper from `@thunderid/better-auth`, which supplies the ThunderID issuer's discovery URL - and default `openid profile email` scopes. -- [`lib/auth-client.ts`](./lib/auth-client.ts) โ€” the Better Auth React client. No client plugin is needed for - ThunderID; sign-in goes through the standard social-provider API. -- [`app/api/auth/[...all]/route.ts`](./app/api/auth/%5B...all%5D/route.ts) โ€” the catch-all route handler that - exposes Better Auth's API via `toNextJsHandler`. -- [`app/page.tsx`](./app/page.tsx) โ€” signs in with `authClient.signIn.social({provider: 'thunderid'})`, shows - the session via `authClient.useSession()`, and signs out with `authClient.signOut()`. -- [`app/components/ConfigNotice.tsx`](./app/components/ConfigNotice.tsx) โ€” shown instead of the app when a - required environment variable is missing, with the exact redirect URI to register on ThunderID. +- [`lib/auth.ts`](./lib/auth.ts) is the Better Auth server instance. It registers the `genericOAuth` plugin with the `thunderid()` helper, which supplies the issuer's discovery URL and the default `openid profile email` scopes. +- [`lib/auth-client.ts`](./lib/auth-client.ts) is the Better Auth React client. ThunderID needs no client plugin; sign-in goes through the standard social provider API. +- [`app/api/auth/[...all]/route.ts`](./app/api/auth/%5B...all%5D/route.ts) is the catch-all route handler that exposes Better Auth's API through `toNextJsHandler`. +- [`app/page.tsx`](./app/page.tsx) signs in with `authClient.signIn.social({provider: 'thunderid'})`, shows the session with `authClient.useSession()`, and signs out with `authClient.signOut()`. +- [`app/components/ConfigNotice.tsx`](./app/components/ConfigNotice.tsx) is shown instead of the app when a required environment variable is missing, with the exact redirect URL to register. + +## Learn more + +- [Better Auth guide](https://thunderid.dev/sdks-and-tools/better-auth) +- [Better Auth Generic OAuth plugin](https://better-auth.com/docs/plugins/generic-oauth) + +## License + +Apache License 2.0. See [LICENSE](https://github.com/thunder-id/samples/blob/main/LICENSE). diff --git a/integrations/flutter-app-auth/README.md b/integrations/flutter-app-auth/README.md index a2bf71d..5b2d495 100644 --- a/integrations/flutter-app-auth/README.md +++ b/integrations/flutter-app-auth/README.md @@ -2,28 +2,37 @@ # ThunderID Flutter AppAuth Sample -A minimal Flutter app that signs users in to ThunderID with [flutter_appauth](https://pub.dev/packages/flutter_appauth), a third-party OpenID Connect plugin that wraps AppAuth for iOS and Android. It uses the authorization code flow with PKCE in the system browser, refreshes tokens, and signs out through ThunderID's end session endpoint. - -The full walkthrough is the [Flutter AppAuth guide](https://thunderid.dev/sdks-and-tools/flutter-appauth) in the ThunderID docs. +A Flutter app that signs users in to ThunderID with [flutter_appauth](https://pub.dev/packages/flutter_appauth), a third-party OpenID Connect plugin that wraps AppAuth for iOS and Android. It uses the authorization code flow with PKCE in the system browser, refreshes tokens, and signs out through ThunderID's end session endpoint. ## Prerequisites - Flutter 3.38.1 or later -- An Android emulator (API 24+) or an iOS Simulator (iOS 13+) -- A running ThunderID instance (default: `https://localhost:8090`) +- An Android emulator running API 24 or later, or an iOS simulator running iOS 13 or later +- A running ThunderID server (`https://localhost:8090` by default) + +## Get the sample + +Download the latest zip from the [releases](https://github.com/thunder-id/samples/releases?q=sample%2Fintegrations%2Fflutter-app-auth&expanded=true), or copy the source: + +```bash +npx degit thunder-id/samples/integrations/flutter-app-auth my-app +cd my-app +``` -## Configure ThunderID +## Configure -1. In the Console, go to **Applications**, click **Add Application**, and choose **Flutter**. +1. In the ThunderID Console, go to **Applications**, click **Add Application**, and choose **Flutter**. 2. Under **Sign-In Approach**, choose **Redirect to ThunderID Gate**. 3. Under **Deep Link / Universal Link**, enter `com.example.appauth://callback`. 4. Create the application and copy its **Client ID**. 5. On the **Advanced** tab, add `com.example.appauth://logout` under **Post-Logout Redirect URIs**. 6. On the **Token** tab, open **User**, then **ID Token**, and add the attributes the app should see, such as `email` and `name`. -## Trust the Local Certificate +The app takes its configuration at run time, as shown under [Run](#run). -A local ThunderID instance serves a self-signed certificate from `<THUNDERID_HOME>/config/certs/server.cert`. The device must trust it before the browser or AppAuth can reach the server. +### Trust the local certificate + +A local ThunderID server serves a self-signed certificate from `<THUNDERID_HOME>/config/certs/server.cert`. The device must trust it before the browser or AppAuth can reach the server. **Android emulator** @@ -34,7 +43,7 @@ adb push <THUNDERID_HOME>/config/certs/server.cert /sdcard/Download/thunderid-de Then install it on the emulator under **Settings > Security & privacy > More security & privacy > Encryption & credentials > Install a certificate > CA certificate**, and pick `thunderid-dev.crt` from **Downloads**. Older Android versions list **Encryption & credentials** directly under **Settings > Security**. Debug builds of this sample trust user-installed certificates through `android/app/src/debug/res/xml/network_security_config.xml`; release builds do not. -**iOS Simulator** +**iOS simulator** ```bash xcrun simctl keychain booted add-root-cert <THUNDERID_HOME>/config/certs/server.cert @@ -47,12 +56,12 @@ flutter pub get flutter run --dart-define=THUNDERID_CLIENT_ID=<your-client-id> ``` -For an instance that is not at `https://localhost:8090`, also pass `--dart-define=THUNDERID_ISSUER=<issuer-url>`. +For a server that is not at `https://localhost:8090`, also pass `--dart-define=THUNDERID_ISSUER=<issuer-url>`. -## Where Things Are +## Where things are -| File | What it does | -|------|--------------| +| Path | What it is | +|---|---| | `lib/auth_config.dart` | Issuer, client ID, redirect URIs, and scopes | | `lib/auth_service.dart` | Sign-in, refresh, session restore, and sign-out with flutter_appauth | | `lib/main.dart` | A single screen that drives the service | @@ -60,4 +69,13 @@ For an instance that is not at `https://localhost:8090`, also pass `--dart-defin | `android/app/src/main/AndroidManifest.xml` | `MainActivity` without the `android:taskAffinity=""` that `flutter create` adds, which would stop the redirect from completing sign-in | | `ios/Runner/Info.plist` | Registers the same scheme under `CFBundleURLTypes` | -To use your own scheme, change it in all three of `auth_config.dart`, `build.gradle.kts`, and `Info.plist`, keep it lowercase, and register the new URIs on the ThunderID application. +To use your own scheme, change it in `auth_config.dart`, `build.gradle.kts`, and `Info.plist`, keep it lowercase, and register the new URIs on the ThunderID application. + +## Learn more + +- [Flutter AppAuth guide](https://thunderid.dev/sdks-and-tools/flutter-appauth), which walks through every step this sample runs +- [flutter_appauth](https://pub.dev/packages/flutter_appauth) + +## License + +Apache License 2.0. See [LICENSE](https://github.com/thunder-id/samples/blob/main/LICENSE). diff --git a/quickstarts/android/README.md b/quickstarts/android/README.md index cbe644b..caeb1e4 100644 --- a/quickstarts/android/README.md +++ b/quickstarts/android/README.md @@ -2,65 +2,77 @@ # ThunderID Android Quickstart -ThunderID Android Quickstart demonstrates the full authentication lifecycle using the [ThunderID Android SDK](https://github.com/thunder-id/android-sdks) on Android. +A Jetpack Compose app that signs users in with the [ThunderID Android SDK](https://github.com/thunder-id/android-sdks), using app-native authentication: sign-in and sign-up run inside the app through the Flow Execution API, with no browser redirect. It depends on the published SDK from [JitPack](https://jitpack.io/#thunder-id/android-sdks) (`com.github.thunder-id:android-sdks`). -**Flow demonstrated:** -1. App opens โ†’ unauthenticated state (sign-in screen) -2. User initiates sign-in / sign-up โ†’ SDK starts app-native Flow Execution -3. User completes the flow -4. Sign-in โ†’ authenticated state with profile information, token debugging, and sign-out button. - Sign-up creates the account but does not start a session, so it returns to the landing screen - and the new credentials have to be used to sign in. -5. User taps Sign Out โ†’ session terminated, returns to sign-in screen +What the app does: -The sample depends on the published SDK from [JitPack](https://jitpack.io/#thunder-id/android-sdks) -(`com.github.thunder-id:android-sdks`), declared in `build.gradle.kts`. +1. Opens signed out, on the sign-in screen. +2. Starts sign-in or sign-up as an app-native flow, which the user completes in the app. +3. After sign-in, shows the user's profile, token details for debugging, and a sign-out button. Sign-up creates the account without starting a session, so it returns to the landing screen to sign in with the new credentials. +4. Signing out ends the session and returns to the sign-in screen. ## Prerequisites - JDK 17 or later - Android Studio, or the Android SDK with `ANDROID_HOME` set -- An Android emulator or device (API 26+) -- A running ThunderID instance +- An Android emulator or device running API 26 or later +- A running ThunderID server (`https://localhost:8090` by default) -## Get the Sample +## Get the sample + +Download the latest zip from the [releases](https://github.com/thunder-id/samples/releases?q=sample%2Fquickstarts%2Fandroid&expanded=true), or copy the source: ```bash -git clone https://github.com/thunder-id/samples.git -cd samples/quickstarts/android -cp config.properties.example config.properties +npx degit thunder-id/samples/quickstarts/android my-app +cd my-app ``` ## Configure -This sample uses app-native authentication (Flow Execution API), so only the base URL and application ID are required, no OAuth2 client ID or redirect URIs. +1. In the ThunderID Console, create an **Android** application and copy its application ID. App-native authentication needs no OAuth2 client ID or redirect URL. + +2. Create your `config.properties`: + + ```bash + cp config.properties.example config.properties + ``` -| Variable | Description | -|----------|-------------| -| `THUNDERID_BASE_URL` | Base URL of your ThunderID server (HTTPS) | -| `THUNDERID_APPLICATION_ID` | Application UUID from the ThunderID Console | -| `THUNDERID_ATTESTATION_ENABLED` | `true` to send a Google Play Integrity token with each flow (optional) | -| `THUNDERID_CLOUD_PROJECT_NUMBER` | Google Cloud project number used for Play Integrity (optional) | + | Variable | Description | + |---|---| + | `THUNDERID_BASE_URL` | Base URL of your ThunderID server (HTTPS). | + | `THUNDERID_APPLICATION_ID` | Application ID of the application. | + | `THUNDERID_ATTESTATION_ENABLED` | Optional. `true` sends a Google Play Integrity token with each flow. | + | `THUNDERID_CLOUD_PROJECT_NUMBER` | Optional. Google Cloud project number used for Play Integrity. | -`config.properties` is gitignored. Never commit real credentials. Each value can also be supplied as an environment variable of the same name. + `config.properties` is gitignored. Each value can also be set as an environment variable of the same name. -If your ThunderID server runs on `localhost`, don't use `localhost` in `THUNDERID_BASE_URL` directly: + A ThunderID server on your machine is not at `localhost` from the device's point of view: -- **Emulator**: use `https://10.0.2.2:8090`, the emulator's alias for your host machine's loopback. -- **Physical device**: run `adb reverse tcp:8090 tcp:8090` and keep using `https://localhost:8090`, or point the URL at your host machine's LAN IP. + - **Emulator**: use `https://10.0.2.2:8090`, the emulator's alias for your machine. This is the default in the example file. + - **Physical device**: run `adb reverse tcp:8090 tcp:8090` and use `https://localhost:8090`, or use your machine's LAN IP. ## Run -Open this directory in Android Studio, sync Gradle, and run it on an emulator or device. From the command line: +Open the project in Android Studio, sync Gradle, and run it on an emulator or device. From the command line: ```bash ./gradlew installDebug ``` -## Attestation and Passkeys +## Where things are + +| Path | What it is | +|---|---| +| `config.properties.example` | The configuration template | +| `assetlinks.json.example` | Digital Asset Links template for passkeys | +| `thunderid-config/thunderid-config.yaml` | The application the [Android SDK end-to-end suite](https://github.com/thunder-id/android-sdks/tree/main/tests/e2e) provisions on a test server. The suite fetches this sample and builds it against the SDK checkout under test. | + +## Learn more -See [Try the Android Sample App](https://thunderid.dev/docs/v1.0.x/sdks/android/guides/try-the-sample-app) in the Android SDK docs for Google Play Integrity attestation and passkey (Digital Asset Links, `assetlinks.json.example`) setup. +- [Android quickstart guide](https://thunderid.dev/docs/getting-started/connect-your-application/android) +- [Try the Android sample app](https://thunderid.dev/docs/sdks-and-tools/android/guides/try-the-sample-app), including Google Play Integrity attestation and passkey setup +- [Android SDK reference](https://thunderid.dev/docs/sdks-and-tools/android/overview) -## End-to-End Tests +## License -`thunderid-config/thunderid-config.yaml` declares the application the Android SDK's [E2E suite](https://github.com/thunder-id/android-sdks/tree/main/tests/e2e) provisions on a test server. The suite fetches this sample and builds it against the SDK checkout under test. +Apache License 2.0. See [LICENSE](https://github.com/thunder-id/samples/blob/main/LICENSE). diff --git a/quickstarts/browser/README.md b/quickstarts/browser/README.md index 0a230f2..6421b03 100644 --- a/quickstarts/browser/README.md +++ b/quickstarts/browser/README.md @@ -2,36 +2,51 @@ # ThunderID Browser Quickstart -A minimal Vite + vanilla JS app demonstrating sign-in and sign-out with the ThunderID JavaScript SDK (`@thunderid/browser`). +A framework-free JavaScript app, built with Vite, that signs users in and out with the [ThunderID Browser SDK](https://www.npmjs.com/package/@thunderid/browser) (`@thunderid/browser`). ## Prerequisites -- Node.js 18+ -- A running ThunderID instance (default: `https://localhost:8090`) -- A configured application with an authorized redirect URI set to your app's origin +- Node.js 20 or later +- A running ThunderID server (`https://localhost:8090` by default) -## Getting started +## Get the sample -1. Copy the environment file and fill in your values: - ```sh +Download the latest zip from the [releases](https://github.com/thunder-id/samples/releases?q=sample%2Fquickstarts%2Fbrowser&expanded=true), or copy the source: + +```bash +npx degit thunder-id/samples/quickstarts/browser my-app +cd my-app +``` + +## Configure + +1. In the ThunderID Console, create a **JavaScript** application with `http://localhost:5173` as its redirect URL, and copy its client ID. + +2. Create your `.env`: + + ```bash cp .env.example .env ``` -2. Edit `.env` with your application's credentials: - ``` - VITE_THUNDERID_CLIENT_ID=<your-client-id> - VITE_THUNDERID_BASE_URL=https://localhost:8090 - ``` + | Variable | Description | + |---|---| + | `VITE_THUNDERID_BASE_URL` | Base URL of your ThunderID server. | + | `VITE_THUNDERID_CLIENT_ID` | Client ID of the application. | -3. Install dependencies and start the dev server: - ```sh - npm install - npm run dev - ``` +## Run + +```bash +npm install +npm run dev +``` -Open [http://localhost:5173](http://localhost:5173) in your browser. +Open [http://localhost:5173](http://localhost:5173) and sign in. ## Learn more -- [ThunderID Docs](https://thunderid.dev/docs) -- [`@thunderid/browser` SDK reference](https://thunderid.dev/docs/sdks/javascript/browser) +- [Browser quickstart guide](https://thunderid.dev/docs/getting-started/connect-your-application/browser) +- [Browser SDK reference](https://thunderid.dev/docs/sdks-and-tools/browser/overview) + +## License + +Apache License 2.0. See [LICENSE](https://github.com/thunder-id/samples/blob/main/LICENSE). diff --git a/quickstarts/express/README.md b/quickstarts/express/README.md index 59241ad..243fca3 100644 --- a/quickstarts/express/README.md +++ b/quickstarts/express/README.md @@ -2,68 +2,67 @@ # ThunderID Express Quickstart -A minimal Express.js **API** protected by ThunderID access tokens, using the ThunderID JavaScript -SDK (`@thunderid/express`). Unlike the browser-focused quickstarts, this sample doesn't have a -sign-in button โ€” it's a resource server. Open [http://localhost:3000](http://localhost:3000) and -you'll get API documentation (endpoints, curl examples, a downloadable Postman collection) instead -of a login screen. +An Express API protected by ThunderID access tokens, using the [ThunderID Express SDK](https://www.npmjs.com/package/@thunderid/express) (`@thunderid/express`). It is a resource server, so there is no sign-in button: [http://localhost:3000](http://localhost:3000) serves API documentation with endpoints, curl examples, and a downloadable Postman collection. -Protected routes validate the `Authorization: Bearer <token>` header against ThunderID's OIDC -`/oauth2/userinfo` endpoint โ€” the same check any OAuth 2.0 resource server performs. A `/login` โ†’ -`/token` helper is included purely so you have a fast way to mint a demo access token to test with. +Protected routes check the `Authorization: Bearer <token>` header against ThunderID's OIDC `/oauth2/userinfo` endpoint, the same check any OAuth 2.0 resource server performs. A `/login` and `/token` helper is included only to give you a quick way to get a demo access token. ## Prerequisites -- Node.js 18+ -- A running ThunderID instance (default: `https://localhost:8090`) -- A configured application with `http://localhost:3000/login` added as an authorized redirect URI +- Node.js 20 or later +- A running ThunderID server (`https://localhost:8090` by default) -## Getting started +## Get the sample -1. Copy the environment file and fill in your values: - ```sh +Download the latest zip from the [releases](https://github.com/thunder-id/samples/releases?q=sample%2Fquickstarts%2Fexpress&expanded=true), or copy the source: + +```bash +npx degit thunder-id/samples/quickstarts/express my-app +cd my-app +``` + +## Configure + +1. In the ThunderID Console, create an **Express** application with `http://localhost:3000/login` as its redirect URL, and copy its client ID and client secret. + +2. Create your `.env`: + + ```bash cp .env.example .env ``` -2. Edit `.env` with your application's credentials: - ``` - THUNDERID_CLIENT_ID=<your-client-id> - THUNDERID_CLIENT_SECRET=<your-client-secret> - THUNDERID_BASE_URL=https://localhost:8090 - ``` + | Variable | Description | + |---|---| + | `THUNDERID_BASE_URL` | Base URL of your ThunderID server. | + | `THUNDERID_CLIENT_ID` | Client ID of the application. | + | `THUNDERID_CLIENT_SECRET` | Client secret of the application. Server-only. | + | `NODE_TLS_REJECT_UNAUTHORIZED` | Set to `0` in the example to accept a local server's self-signed certificate. Local development only. | -3. Install dependencies and start the server: - ```sh - npm install - npm start - ``` +## Run + +```bash +npm install +npm start +``` -Open [http://localhost:3000](http://localhost:3000) for the API documentation page. +Open [http://localhost:3000](http://localhost:3000) for the API documentation. -## Trying the API +## Try the API -- `GET /api/public` โ€” no auth required. -- `GET /api/protected`, `GET /api/me`, and `PATCH /api/me/credentials` โ€” require `Authorization: Bearer <access_token>`. +- `GET /api/public` needs no token. +- `GET /api/protected`, `GET /api/me`, and `PATCH /api/me/credentials` need `Authorization: Bearer <access_token>`. -To get a token to test with, open [http://localhost:3000/login](http://localhost:3000/login), -sign in once, and your access token (decoded claims included) will be shown at -[http://localhost:3000/token](http://localhost:3000/token). Then: +To get a token, open [http://localhost:3000/login](http://localhost:3000/login) and sign in. The access token and its decoded claims are shown at [http://localhost:3000/token](http://localhost:3000/token). Then: -```sh +```bash curl http://localhost:3000/api/me \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` -Prefer a GUI? Download the Postman collection from the API docs page (or directly at -`/postman-collection.json`), paste your token into the `accessToken` collection variable, and run -the requests from there. +To use Postman instead, download the collection from the API documentation page (or `/postman-collection.json`), paste your token into the `accessToken` collection variable, and send the requests. ## Back-channel logout -The demo session behind `/login` and `/token` can be ended by ThunderID itself. When the user's -ThunderID session ends somewhere else, for example by signing out of another application, -ThunderID posts a logout token to this app, and the SDK ends the local session. The route is one -line in `index.mjs`: +ThunderID can end the demo session behind `/login` and `/token` itself. When the user's ThunderID session ends somewhere else, for example by signing out of another application, ThunderID posts a logout token to this app and the SDK ends the local session. The route is one line in `index.mjs`: ```js app.post('/backchannel-logout', handleBackchannelLogout()); @@ -71,29 +70,28 @@ app.post('/backchannel-logout', handleBackchannelLogout()); To try it: -1. In the ThunderID Console, open this application, go to **Advanced Settings โ†’ OAuth2 - Configuration**, and set **Back-Channel Logout URI** to - `http://localhost:3000/backchannel-logout`. -2. ThunderID refuses localhost and private network addresses by default. For local testing only, - turn that off in the server's `deployment.yaml` and restart it: +1. In the ThunderID Console, open this application, go to **Advanced Settings โ†’ OAuth2 Configuration**, and set **Back-Channel Logout URI** to `http://localhost:3000/backchannel-logout`. +2. ThunderID refuses localhost and private network addresses by default. For local testing only, turn that off in the server's `deployment.yaml` and restart it: + ```yaml oauth: logout: backchannel: reject_private_addresses: false ``` -3. Sign in at [http://localhost:3000/login](http://localhost:3000/login), then sign in to a second - application in the same browser, so both share one ThunderID session. -4. Sign out of the second application. Open [http://localhost:3000/token](http://localhost:3000/token): - you are sent back to sign-in, because this app's session was ended too. -The Bearer-token API routes (`/api/*`) are not affected: they check each access token with -ThunderID on every request and hold no session. +3. Sign in at [http://localhost:3000/login](http://localhost:3000/login), then sign in to a second application in the same browser, so both share one ThunderID session. +4. Sign out of the second application, then open [http://localhost:3000/token](http://localhost:3000/token). You are sent back to sign in, because this app's session ended too. -The SDK keeps sessions in memory by default. If you run more than one instance of an app, give the -SDK a shared store, since ThunderID's request reaches only one of them. +The Bearer token routes under `/api` are not affected: they check each access token with ThunderID on every request and hold no session. + +The SDK keeps sessions in memory by default. If you run more than one instance, give the SDK a shared store, since ThunderID's request reaches only one of them. ## Learn more -- [ThunderID Docs](https://thunderid.dev/docs) -- [`@thunderid/express` SDK reference](https://thunderid.dev/docs/sdks/javascript/express) +- [Express quickstart guide](https://thunderid.dev/docs/getting-started/connect-your-application/express) +- [Express SDK reference](https://thunderid.dev/docs/sdks-and-tools/express/overview) + +## License + +Apache License 2.0. See [LICENSE](https://github.com/thunder-id/samples/blob/main/LICENSE). diff --git a/quickstarts/flutter/README.md b/quickstarts/flutter/README.md index bbc39ba..7750a4e 100644 --- a/quickstarts/flutter/README.md +++ b/quickstarts/flutter/README.md @@ -2,36 +2,46 @@ # ThunderID Flutter Quickstart -ThunderID Flutter Quickstart demonstrates the full authentication lifecycle using the [`thunderid_flutter`](https://pub.dev/packages/thunderid_flutter) SDK on iOS and Android. +A Flutter app for iOS and Android that signs users in with the [`thunderid_flutter`](https://pub.dev/packages/thunderid_flutter) package, using app-native authentication: sign-in and sign-up run inside the app through the Flow Execution API, with no browser redirect. -**Flow demonstrated:** -1. App opens โ†’ unauthenticated state (sign-in screen) -2. User initiates sign-in / sign-up โ†’ SDK starts app-native Flow Execution -3. User completes the flow -4. Sign-in โ†’ authenticated state with profile information, token debugging, and sign-out button. - Sign-up creates the account but does not start a session, so it returns to the landing screen - and the new credentials have to be used to sign in. -5. User taps Sign Out โ†’ session terminated, returns to sign-in screen +What the app does: -## Get the Sample +1. Opens signed out, on the sign-in screen. +2. Starts sign-in or sign-up as an app-native flow, which the user completes in the app. +3. After sign-in, shows the user's profile, token details for debugging, and a sign-out button. Sign-up creates the account without starting a session, so it returns to the landing screen to sign in with the new credentials. +4. Signing out ends the session and returns to the sign-in screen. + +## Prerequisites + +- Flutter 3.16 or later +- An Android emulator or device, or an iOS simulator or device +- A running ThunderID server (`https://localhost:8090` by default) + +## Get the sample + +Download the latest zip from the [releases](https://github.com/thunder-id/samples/releases?q=sample%2Fquickstarts%2Fflutter&expanded=true), or copy the source: ```bash -git clone https://github.com/thunder-id/samples.git -cd samples/quickstarts/flutter +npx degit thunder-id/samples/quickstarts/flutter my-app +cd my-app ``` ## Configure -```bash -cp .env.example .env -``` +1. In the ThunderID Console, create a **Flutter** application and copy its application ID. App-native authentication needs no OAuth2 client ID or redirect URL. -| Variable | Description | -|---|---| -| `THUNDERID_BASE_URL` | Base URL of your ThunderID server (default `https://localhost:8090`). | -| `THUNDERID_APP_ID` | ID of the ThunderID application the sample signs in to. | -| `THUNDERID_ATTESTATION_ENABLED` | Set to `true` to enable platform attestation. | -| `THUNDERID_CLOUD_PROJECT_NUMBER` | Google Cloud project number, used for Play Integrity attestation on Android. | +2. Create your `.env`: + + ```bash + cp .env.example .env + ``` + + | Variable | Description | + |---|---| + | `THUNDERID_BASE_URL` | Base URL of your ThunderID server. | + | `THUNDERID_APP_ID` | Application ID of the application. | + | `THUNDERID_ATTESTATION_ENABLED` | Optional. `true` turns on platform attestation. | + | `THUNDERID_CLOUD_PROJECT_NUMBER` | Optional. Google Cloud project number used for Play Integrity attestation on Android. | ## Run @@ -40,7 +50,20 @@ flutter pub get flutter run ``` -See [Try the Flutter Sample App](https://thunderid.dev/docs/v1.0.x/sdks/flutter/guides/try-the-sample-app) -in the Flutter SDK docs for prerequisites, creating the application, attestation, passkeys, and run instructions. +## Where things are + +| Path | What it is | +|---|---| +| `lib/` | The app | +| `assetlinks.json.example` | Digital Asset Links template for passkeys on Android | +| `thunderid-config/thunderid-config.yaml` | The application the [Flutter SDK end-to-end suite](https://github.com/thunder-id/flutter-sdks) provisions on a test server before it drives this sample | + +## Learn more + +- [Flutter quickstart guide](https://thunderid.dev/docs/getting-started/connect-your-application/flutter) +- [Try the Flutter sample app](https://thunderid.dev/docs/sdks-and-tools/flutter/guides/try-the-sample-app), including attestation and passkey setup +- [Flutter SDK reference](https://thunderid.dev/docs/sdks-and-tools/flutter/overview) + +## License -The SDK source lives in [thunder-id/flutter-sdks](https://github.com/thunder-id/flutter-sdks). +Apache License 2.0. See [LICENSE](https://github.com/thunder-id/samples/blob/main/LICENSE). diff --git a/quickstarts/ios/README.md b/quickstarts/ios/README.md index 9ea9697..aeef6e5 100644 --- a/quickstarts/ios/README.md +++ b/quickstarts/ios/README.md @@ -2,42 +2,67 @@ # ThunderID iOS Quickstart -ThunderID iOS Quickstart demonstrates the full authentication lifecycle using the `ThunderID iOS` SDK. +A SwiftUI app that signs users in with the [ThunderID iOS SDK](https://github.com/thunder-id/ios-sdks), using app-native authentication: sign-in and sign-up run inside the app through the Flow Execution API, with no browser redirect. It depends on the published SDK release through Swift Package Manager, so it builds without a checkout of the SDK. -**Flow demonstrated:** -1. App opens โ†’ unauthenticated state (sign-in screen) -2. User initiates sign-in / sign-up โ†’ SDK starts app-native Flow Execution -3. User completes the flow -4. Sign-in โ†’ authenticated state with profile information, token debugging, and sign-out button. - Sign-up creates the account but does not start a session, so it returns to the landing screen - and the new credentials have to be used to sign in. -5. User taps Sign Out โ†’ session terminated, returns to sign-in screen +What the app does: -The app depends on the published [ThunderID iOS SDK](https://github.com/thunder-id/ios-sdks) -release through Swift Package Manager, so it builds on its own without a checkout of the SDK. +1. Opens signed out, on the sign-in screen. +2. Starts sign-in or sign-up as an app-native flow, which the user completes in the app. +3. After sign-in, shows the user's profile, token details for debugging, and a sign-out button. Sign-up creates the account without starting a session, so it returns to the landing screen to sign in with the new credentials. +4. Signing out ends the session and returns to the sign-in screen. -## Get the Sample +## Prerequisites + +- Xcode 15 or later +- An iOS simulator or device running iOS 16 or later +- A running ThunderID server (`https://localhost:8090` by default) + +## Get the sample + +Download the latest zip from the [releases](https://github.com/thunder-id/samples/releases?q=sample%2Fquickstarts%2Fios&expanded=true), or copy the source: ```bash -git clone https://github.com/thunder-id/samples.git -cd samples/quickstarts/ios -cp Sources/Config.plist.example Sources/Config.plist +npx degit thunder-id/samples/quickstarts/ios my-app +cd my-app ``` -Set `THUNDERID_BASE_URL` and `THUNDERID_APPLICATION_ID` in `Sources/Config.plist`, then open -`Quickstart.xcodeproj` in Xcode and run the `Quickstart` scheme on a simulator or device. -`Sources/Config.plist` is listed in `.gitignore`, so your local values are not committed. +## Configure + +1. In the ThunderID Console, create an **iOS** application and copy its application ID. App-native authentication needs no OAuth2 client ID or redirect URL. + +2. Create your `Config.plist`: + + ```bash + cp Sources/Config.plist.example Sources/Config.plist + ``` -## Setup & Run + | Key | Description | + |---|---| + | `THUNDERID_BASE_URL` | Base URL of your ThunderID server (HTTPS). | + | `THUNDERID_APPLICATION_ID` | Application ID of the application. | + | `THUNDERID_ATTESTATION_ENABLED` | Optional. `true` turns on platform attestation. | -See [Try the iOS Sample App](https://thunderid.dev/docs/v1.0.x/sdks/ios/guides/try-the-sample-app) -in the iOS SDK docs for prerequisites, configuration, attestation, passkeys, and run instructions. + `Sources/Config.plist` is gitignored, so your local values are not committed. -## Where Things Are +## Run + +Open `Quickstart.xcodeproj` in Xcode and run the `Quickstart` scheme on a simulator or device. + +## Where things are | Path | What it is | -|------|------------| +|---|---| | `Sources/` | The SwiftUI app and `Config.plist.example` | | `Quickstart.xcodeproj` | Xcode project, with the SDK as a remote Swift package | | `Package.swift` | The same app as a Swift package | -| `thunderid-config/thunderid-config.yaml` | The application the [iOS SDK E2E suite](https://github.com/thunder-id/ios-sdks/tree/main/Tests/e2e) imports into ThunderID before it drives this sample | +| `thunderid-config/thunderid-config.yaml` | The application the [iOS SDK end-to-end suite](https://github.com/thunder-id/ios-sdks/tree/main/Tests/e2e) imports into ThunderID before it drives this sample | + +## Learn more + +- [iOS quickstart guide](https://thunderid.dev/docs/getting-started/connect-your-application/ios) +- [Try the iOS sample app](https://thunderid.dev/docs/sdks-and-tools/ios/guides/try-the-sample-app), including attestation and passkey setup +- [iOS SDK reference](https://thunderid.dev/docs/sdks-and-tools/ios/overview) + +## License + +Apache License 2.0. See [LICENSE](https://github.com/thunder-id/samples/blob/main/LICENSE). diff --git a/quickstarts/nextjs/README.md b/quickstarts/nextjs/README.md index 1f341c8..82a4c5a 100644 --- a/quickstarts/nextjs/README.md +++ b/quickstarts/nextjs/README.md @@ -2,116 +2,111 @@ # ThunderID Next.js Quickstart -A minimal Next.js 15 App Router application demonstrating ThunderID authentication with OAuth 2.0, PKCE, and JWT out of the box. +A Next.js 15 App Router app that signs users in with the [ThunderID Next.js SDK](https://www.npmjs.com/package/@thunderid/nextjs) (`@thunderid/nextjs`), on the client and the server. By default, sign-in and sign-up render inside the app on its own `/signin` and `/signup` routes (the native flow). It can also send users to ThunderID's hosted sign-in page instead. ## Prerequisites -- Node.js 18+ -- A ThunderID application +- Node.js 20 or later +- A running ThunderID server (`https://localhost:8090` by default) -## Getting started +## Get the sample -1. Copy the example environment file: +Download the latest zip from the [releases](https://github.com/thunder-id/samples/releases?q=sample%2Fquickstarts%2Fnextjs&expanded=true), or copy the source: - ```bash - cp .env.example .env - ``` - -2. Fill in your ThunderID credentials in `.env`. By default the file is set up for the native flow: +```bash +npx degit thunder-id/samples/quickstarts/nextjs my-app +cd my-app +``` - ```dotenv - NEXT_PUBLIC_THUNDERID_BASE_URL=https://localhost:8090 - NEXT_PUBLIC_THUNDERID_APPLICATION_ID=<your-application-id> - THUNDERID_FLOW_SECRET=<the app's Flow Secret, from its Credentials tab in the console> - NEXT_PUBLIC_THUNDERID_SIGN_IN_URL=/signin - NEXT_PUBLIC_THUNDERID_SIGN_UP_URL=/signup - THUNDERID_SECRET=<run: openssl rand -base64 32> - ``` +## Configure - The Flow Secret is generated by the server when the application is created, shown once, and only - retrievable afterward from the app's Credentials tab (under Edit). It's a separate credential from - the OAuth2 Client Secret used by the redirect-based flow below โ€” an embedded app (no OAuth2 - configuration) has a Flow Secret and no client secret; a redirect-based `authorization_code` app has - a client secret and no Flow Secret. +1. In the ThunderID Console, create a **Next.js** application. Copy its application ID, and its Flow Secret, which is shown once when the application is created and can be regenerated later from the application's **Credentials** tab. -3. Install dependencies and start the development server: +2. Create your `.env`: ```bash - npm install - npm run dev + cp .env.example .env ``` - The app is now running at [http://localhost:3000](http://localhost:3000). + | Variable | Description | + |---|---| + | `NEXT_PUBLIC_THUNDERID_BASE_URL` | Base URL of your ThunderID server. | + | `NEXT_PUBLIC_THUNDERID_APPLICATION_ID` | Application ID of the application. | + | `THUNDERID_FLOW_SECRET` | Flow Secret of the application. Server-only. | + | `THUNDERID_SECRET` | Encrypts the session cookie. Generate it with `openssl rand -base64 32`. | + | `NEXT_PUBLIC_THUNDERID_SIGN_IN_URL` | The app's sign-in route. Keep `/signin`. | + | `NEXT_PUBLIC_THUNDERID_SIGN_UP_URL` | The app's sign-up route. Keep `/signup`. | + | `NODE_TLS_REJECT_UNAUTHORIZED` | Set to `0` in the example to accept a local server's self-signed certificate. Local development only. | + + The Flow Secret is a different credential from the OAuth2 client secret used by the redirect-based flow below. An application with no OAuth2 configuration has a Flow Secret and no client secret; a redirect-based `authorization_code` application has a client secret and no Flow Secret. + +## Run -<details> -<summary><h2>Redirect-based flow</h2></summary> +```bash +npm install +npm run dev +``` + +Open [http://localhost:3000](http://localhost:3000) and sign in. -By default this quickstart uses the native (embedded) flow, where sign-in/sign-up render inline on this -app's own `/signin` and `/signup` routes with no redirect to ThunderID's hosted pages. +## Redirect-based flow -To send the user to ThunderID's hosted sign-in page instead, switch to the redirect-based flow: +To send users to ThunderID's hosted sign-in page instead of the app's own pages: -1. Register a redirect URI for your application (see the app's config notice in the console for the - exact value to use). -2. Regenerate `.env` for the redirect flow: +1. Register a redirect URL on your application. The app's config notice shows the exact value. +2. Switch `.env` to the redirect flow: ```bash npm run prepare-dev:redirect ``` - This comments out the native-flow vars (`NEXT_PUBLIC_THUNDERID_APPLICATION_ID`, - `NEXT_PUBLIC_THUNDERID_SIGN_IN_URL`, `NEXT_PUBLIC_THUNDERID_SIGN_UP_URL`, `THUNDERID_FLOW_SECRET`) and - adds: + This comments out the native flow variables (`NEXT_PUBLIC_THUNDERID_APPLICATION_ID`, `NEXT_PUBLIC_THUNDERID_SIGN_IN_URL`, `NEXT_PUBLIC_THUNDERID_SIGN_UP_URL`, `THUNDERID_FLOW_SECRET`) and adds: ```dotenv NEXT_PUBLIC_THUNDERID_CLIENT_ID=<your-client-id> THUNDERID_CLIENT_SECRET=<your-client-secret> ``` - Both values come from the application's Credentials tab in the console. To switch back to the native - flow, run `node scripts/prepare-dev.cjs --flow=native` (or manually re-enable the native-flow vars and - comment out the two above). -3. Fill in `NEXT_PUBLIC_THUNDERID_CLIENT_ID` and `THUNDERID_CLIENT_SECRET` in `.env`, then restart the dev - server. +3. Fill in both values from the application's **Credentials** tab, then restart the dev server. -</details> +To switch back, run `node scripts/prepare-dev.cjs --flow=native`. ## Back-channel logout -ThunderID can end this app's session itself. When the user's ThunderID session ends somewhere else, -for example by signing out of another application, ThunderID posts a logout token to this app. The -route is one line in `app/api/auth/backchannel-logout/route.ts`: +ThunderID can end this app's session itself. When the user's ThunderID session ends somewhere else, for example by signing out of another application, ThunderID posts a logout token to this app. The route is one line in `app/api/auth/backchannel-logout/route.ts`: ```ts export const {POST} = backchannelLogout() ``` -The session lives in a cookie that only the browser can delete, so the SDK records the logout and -treats every later request with that session as signed out. +The session lives in a cookie that only the browser can delete, so the SDK records the logout and treats every later request with that session as signed out. + +To try it, use the redirect-based flow, since the logout token is addressed to the client ID: -To try it, use the redirect-based flow above, since the logout token is addressed to the client ID: +1. In the ThunderID Console, open this application, go to **Advanced Settings โ†’ OAuth2 Configuration**, and set **Back-Channel Logout URI** to `http://localhost:3000/api/auth/backchannel-logout`. +2. ThunderID refuses localhost and private network addresses by default. For local testing only, turn that off in the server's `deployment.yaml` and restart it: -1. In the ThunderID Console, open this application, go to **Advanced Settings โ†’ OAuth2 - Configuration**, and set **Back-Channel Logout URI** to - `http://localhost:3000/api/auth/backchannel-logout`. -2. ThunderID refuses localhost and private network addresses by default. For local testing only, - turn that off in the server's `deployment.yaml` and restart it: ```yaml oauth: logout: backchannel: reject_private_addresses: false ``` -3. Sign in at [http://localhost:3000](http://localhost:3000), then sign in to a second application - in the same browser, so both share one ThunderID session. -4. Sign out of the second application, then reload this app: you are signed out here too. - -Things to know before production: - -- The SDK records ended sessions in memory by default. If you run more than one instance, pass a - shared `store` to both `backchannelLogout()` and `thunderIDProxy()`, since ThunderID's request - reaches only one instance. -- Route protection in `thunderIDProxy()` sees the in-memory record only when the proxy runs on the - Node.js runtime. On Next.js 15, add `runtime: 'nodejs'` to the `config` export of your - `middleware.ts`. On the Edge runtime, use a shared `store`. + +3. Sign in at [http://localhost:3000](http://localhost:3000), then sign in to a second application in the same browser, so both share one ThunderID session. +4. Sign out of the second application, then reload this app. You are signed out here too. + +Before production: + +- The SDK records ended sessions in memory by default. If you run more than one instance, pass a shared `store` to both `backchannelLogout()` and `thunderIDProxy()`, since ThunderID's request reaches only one instance. +- Route protection in `thunderIDProxy()` sees the in-memory record only when the proxy runs on the Node.js runtime. On Next.js 15, add `runtime: 'nodejs'` to the `config` export of your `middleware.ts`. On the Edge runtime, use a shared `store`. - An access token already handed to the browser or to another API stays valid until it expires. + +## Learn more + +- [Next.js quickstart guide](https://thunderid.dev/docs/getting-started/connect-your-application/nextjs) +- [Next.js SDK reference](https://thunderid.dev/docs/sdks-and-tools/nextjs/overview) + +## License + +Apache License 2.0. See [LICENSE](https://github.com/thunder-id/samples/blob/main/LICENSE). diff --git a/quickstarts/node/README.md b/quickstarts/node/README.md index d8b1acd..4867ae3 100644 --- a/quickstarts/node/README.md +++ b/quickstarts/node/README.md @@ -1,79 +1,71 @@ ![ThunderID Node.js Quickstart](https://raw.githubusercontent.com/thunder-id/samples/main/.github/assets/banners/quickstarts-node.png) -# ThunderID Node.js Service Quickstart +# ThunderID Node.js Quickstart -A minimal machine-to-machine (service-to-service) client, using the ThunderID Node.js SDK -(`@thunderid/node`). Unlike the other quickstarts, there's no user and no browser sign-in: this -service authenticates as **itself** with the OAuth 2.0 `client_credentials` grant, then uses the -resulting access token to call another piece of business logic. +A machine-to-machine client built with the [ThunderID Node.js SDK](https://www.npmjs.com/package/@thunderid/node) (`@thunderid/node`). There is no user and no browser sign-in: the service authenticates as itself with the OAuth 2.0 `client_credentials` grant, then uses the access token to call another piece of business logic. Use this pattern for background jobs, scheduled tasks, or one backend service calling another. -This is the pattern to use for background jobs, cron tasks, or one backend service calling -another, where there's no human in the loop to redirect through a login page. +## Prerequisites -The sample is organized the way a real backend usually is, with authentication kept in its own -service instead of scattered across business logic: +- Node.js 20 or later +- A running ThunderID server (`https://localhost:8090` by default) -```text -quickstarts/node/ -โ”œโ”€โ”€ index.mjs Wires the services together and prints the result -โ””โ”€โ”€ lib/ - โ”œโ”€โ”€ AuthService.mjs Acquires and caches this service's own access token - โ”œโ”€โ”€ InventoryService.mjs Business logic; asks AuthService for a token before answering - โ””โ”€โ”€ ui.mjs Terminal output, built on boxen and picocolors +## Get the sample + +Download the latest zip from the [releases](https://github.com/thunder-id/samples/releases?q=sample%2Fquickstarts%2Fnode&expanded=true), or copy the source: + +```bash +npx degit thunder-id/samples/quickstarts/node my-app +cd my-app ``` -## How it works +## Configure -- `lib/AuthService.mjs` initializes `ThunderIDNodeClient` with `grantType: 'client_credentials'`. - With that set, `getAccessToken()` authenticates as the service itself (no session, no sign-in) - and transparently fetches, caches, and refreshes the token, the same method a user-facing - quickstart would call to read an existing session's token, just authenticating as the service - itself instead of a signed-in user. -- `lib/InventoryService.mjs` is the business logic that needs a token before it can act. It asks - `AuthService` for one; the rest of the app never handles a token or an `Authorization` header - directly. In a real deployment, `InventoryService` would send that token to a separate inventory - backend over HTTP, in place of another service calling `AuthService`'s owner the same way. +1. In the ThunderID Console (`https://localhost:8090/console`), go to **Applications**, click **Add Application**, and select **Backend Service**. Give it a name, such as `node-service-quickstart`, and create it. Backend Service applications come set up for the `client_credentials` grant with `client_secret_basic` authentication. +2. Copy the **Client ID** from the **General** tab, and the **Client Secret** from the dialog shown when the application is created. The secret is shown only once. +3. Create your `.env`: -## Prerequisites + ```bash + cp .env.example .env + ``` -- Node.js 18+ -- A running ThunderID instance (default: `https://localhost:8090`) -- A **Backend Service** application registered in ThunderID + | Variable | Description | + |---|---| + | `THUNDERID_BASE_URL` | Base URL of your ThunderID server. | + | `THUNDERID_CLIENT_ID` | Client ID of the application. | + | `THUNDERID_CLIENT_SECRET` | Client secret of the application. | + | `THUNDERID_SCOPE` | Optional. Space-separated scopes to request. | + | `NODE_TLS_REJECT_UNAUTHORIZED` | Set to `0` in the example to accept a local server's self-signed certificate. Local development only. | -## Create an application +## Run -1. Open the ThunderID Console (`https://localhost:8090/console`), navigate to **Applications**, and - click **Add Application**. -2. From the **Choose a type** page, select **Backend Service**. -3. Enter a name (e.g. `node-service-quickstart`) and create the application. Backend Service apps - are pre-configured for the `client_credentials` grant with `client_secret_basic` authentication, - no extra setup needed. -4. Copy the **Client ID** from the **General** tab, and the **Client Secret** from the window that - pops up when the application is created (shown only once), you'll need them below. +```bash +npm install +npm start +``` -## Getting started +The script authenticates once, calls `InventoryService.getStock()` for a few SKUs, prints the result, and exits: a scope line, then an `Inventory` panel with one line per SKU, green for items in stock, yellow for items out of stock, and red for a SKU that does not exist. -1. Copy the environment file and fill in your application's credentials: - ```sh - cp .env.example .env - ``` - ``` - THUNDERID_CLIENT_ID=<your client ID> - THUNDERID_CLIENT_SECRET=<your client secret> - THUNDERID_BASE_URL=https://localhost:8090 - ``` +## How it works -2. Install dependencies and run it: - ```sh - npm install - npm start - ``` +Authentication lives in its own service instead of being spread across the business logic: + +```text +โ”œโ”€โ”€ index.mjs Wires the services together and prints the result +โ””โ”€โ”€ lib/ + โ”œโ”€โ”€ AuthService.mjs Gets and caches this service's own access token + โ”œโ”€โ”€ InventoryService.mjs Business logic; asks AuthService for a token before answering + โ””โ”€โ”€ ui.mjs Terminal output, built on boxen and picocolors +``` -The script authenticates once, then calls `InventoryService.getStock()` for a few SKUs and prints -the result before exiting: a scope line, then an `Inventory` panel with one line per SKU, green -for in-stock items, yellow for out-of-stock, red for a SKU that doesn't exist. +- `lib/AuthService.mjs` creates a `ThunderIDNodeClient` with `grantType: 'client_credentials'`. With that set, `getAccessToken()` authenticates as the service itself and fetches, caches, and refreshes the token. It is the same method a user-facing app calls to read a session's token. +- `lib/InventoryService.mjs` needs a token before it can act and asks `AuthService` for one. The rest of the app never handles a token or an `Authorization` header. In a real deployment, `InventoryService` would send the token to a separate inventory backend over HTTP. ## Learn more -- [ThunderID Docs](https://thunderid.dev/docs) -- [OAuth 2.0 Client Credentials Grant (RFC 6749 ยง4.4)](https://www.rfc-editor.org/rfc/rfc6749#section-4.4) +- [Node.js quickstart guide](https://thunderid.dev/docs/getting-started/connect-your-application/node) +- [Node.js SDK reference](https://thunderid.dev/docs/sdks-and-tools/node/overview) +- [OAuth 2.0 client credentials grant (RFC 6749, section 4.4)](https://www.rfc-editor.org/rfc/rfc6749#section-4.4) + +## License + +Apache License 2.0. See [LICENSE](https://github.com/thunder-id/samples/blob/main/LICENSE). diff --git a/quickstarts/nuxt/README.md b/quickstarts/nuxt/README.md index ffc7391..0409a4c 100644 --- a/quickstarts/nuxt/README.md +++ b/quickstarts/nuxt/README.md @@ -2,80 +2,76 @@ # ThunderID Nuxt Quickstart -A minimal Nuxt 3 application demonstrating ThunderID authentication with OAuth 2.0, PKCE, and JWT out of the box. +A Nuxt app that signs users in with the [ThunderID Nuxt SDK](https://www.npmjs.com/package/@thunderid/nuxt) (`@thunderid/nuxt`), with server-side sessions. By default, sign-in and sign-up render inside the app on its own `/signin` and `/signup` routes (the native flow). It can also send users to ThunderID's hosted sign-in page instead. ## Prerequisites -- Node.js 18+ -- A ThunderID application +- Node.js 20 or later +- A running ThunderID server (`https://localhost:8090` by default) -## Getting started +## Get the sample -1. Copy the example environment file: +Download the latest zip from the [releases](https://github.com/thunder-id/samples/releases?q=sample%2Fquickstarts%2Fnuxt&expanded=true), or copy the source: - ```bash - cp .env.example .env - ``` +```bash +npx degit thunder-id/samples/quickstarts/nuxt my-app +cd my-app +``` -2. Fill in your ThunderID credentials in `.env`. By default the file is set up for the native flow: +## Configure - ```dotenv - NUXT_PUBLIC_THUNDERID_BASE_URL=https://localhost:8090 - NUXT_PUBLIC_THUNDERID_APPLICATION_ID=<your-application-id> - NUXT_PUBLIC_THUNDERID_SIGN_IN_URL=/signin - NUXT_PUBLIC_THUNDERID_SIGN_UP_URL=/signup - THUNDERID_FLOW_SECRET=<your-flow-secret> - THUNDERID_SESSION_SECRET=<run: openssl rand -base64 32> - ``` +1. In the ThunderID Console, create a **Nuxt** application. Copy its application ID, and its Flow Secret, which is shown once when the application is created and can be regenerated later from the application's **Credentials** tab. -3. Install dependencies and start the development server: +2. Create your `.env`: ```bash - npm install - npm run dev + cp .env.example .env ``` - The app is now running at [http://localhost:3000](http://localhost:3000). + | Variable | Description | + |---|---| + | `NUXT_PUBLIC_THUNDERID_BASE_URL` | Base URL of your ThunderID server. | + | `NUXT_PUBLIC_THUNDERID_APPLICATION_ID` | Application ID of the application. | + | `THUNDERID_FLOW_SECRET` | Flow Secret of the application. Server-only. | + | `THUNDERID_SESSION_SECRET` | Encrypts the session cookie. Generate it with `openssl rand -base64 32`. | + | `NUXT_PUBLIC_THUNDERID_SIGN_IN_URL` | The app's sign-in route. Keep `/signin`. | + | `NUXT_PUBLIC_THUNDERID_SIGN_UP_URL` | The app's sign-up route. Keep `/signup`. | + | `NODE_TLS_REJECT_UNAUTHORIZED` | Set to `0` in the example to accept a local server's self-signed certificate. Local development only. | + +## Run + +```bash +npm install +npm run dev +``` -<details> -<summary><h2>Redirect-based flow</h2></summary> +Open [http://localhost:3000](http://localhost:3000) and sign in. -By default this quickstart uses the native (embedded) flow, where sign-in/sign-up render inline on this -app's own `/signin` and `/signup` routes with no redirect to ThunderID's hosted pages. +## Redirect-based flow -To send the user to ThunderID's hosted sign-in page instead, switch to the redirect-based flow: +To send users to ThunderID's hosted sign-in page instead of the app's own pages: -1. Register a redirect URI for your application (see the app's config notice in the console for the - exact value to use). -2. Regenerate `.env` for the redirect flow: +1. Register a redirect URL on your application. The app's config notice shows the exact value. +2. Switch `.env` to the redirect flow: ```bash npm run prepare-dev:redirect ``` - This comments out the native-flow vars (`NUXT_PUBLIC_THUNDERID_APPLICATION_ID`, - `NUXT_PUBLIC_THUNDERID_SIGN_IN_URL`, `NUXT_PUBLIC_THUNDERID_SIGN_UP_URL`) and adds: + This comments out the native flow variables (`NUXT_PUBLIC_THUNDERID_APPLICATION_ID`, `NUXT_PUBLIC_THUNDERID_SIGN_IN_URL`, `NUXT_PUBLIC_THUNDERID_SIGN_UP_URL`) and adds: ```dotenv NUXT_PUBLIC_THUNDERID_CLIENT_ID=<your-client-id> THUNDERID_CLIENT_SECRET=<your-client-secret> ``` - Both values come from the application's Credentials tab in the console. The redirect-based flow - doesn't use `THUNDERID_FLOW_SECRET` (that's only sent when the native flow starts), so it can stay - set in `.env` from step 2 above, unused. To switch back to the native flow, run - `node scripts/prepare-dev.cjs --flow=native` (or manually re-enable the native-flow vars and comment - out the two above). -3. Fill in `NUXT_PUBLIC_THUNDERID_CLIENT_ID` and `THUNDERID_CLIENT_SECRET` in `.env`, then restart the - dev server. +3. Fill in both values from the application's **Credentials** tab, then restart the dev server. `THUNDERID_FLOW_SECRET` is only used when the native flow starts, so it can stay set. -</details> +To switch back, run `node scripts/prepare-dev.cjs --flow=native`. ## Back-channel logout -ThunderID can end this app's session itself. When the user's ThunderID session ends somewhere else, -for example by signing out of another application, ThunderID posts a logout token to this app. The -module serves the route once it is turned on in `nuxt.config.ts`: +ThunderID can end this app's session itself. When the user's ThunderID session ends somewhere else, for example by signing out of another application, ThunderID posts a logout token to this app. The module serves the route once it is turned on in `nuxt.config.ts`: ```ts thunderid: { @@ -83,31 +79,27 @@ thunderid: { }, ``` -The session lives in a cookie that only the browser can delete, so the SDK records the logout and -treats every later request with that session as signed out. +The session lives in a cookie that only the browser can delete, so the SDK records the logout and treats every later request with that session as signed out. -To try it, use the redirect-based flow above, since the logout token is addressed to the client ID: +To try it, use the redirect-based flow, since the logout token is addressed to the client ID: + +1. In the ThunderID Console, open this application, go to **Advanced Settings โ†’ OAuth2 Configuration**, and set **Back-Channel Logout URI** to `http://localhost:3000/api/auth/backchannel-logout`. +2. ThunderID refuses localhost and private network addresses by default. For local testing only, turn that off in the server's `deployment.yaml` and restart it: -1. In the ThunderID Console, open this application, go to **Advanced Settings โ†’ OAuth2 - Configuration**, and set **Back-Channel Logout URI** to - `http://localhost:3000/api/auth/backchannel-logout`. -2. ThunderID refuses localhost and private network addresses by default. For local testing only, - turn that off in the server's `deployment.yaml` and restart it: ```yaml oauth: logout: backchannel: reject_private_addresses: false ``` -3. Sign in at [http://localhost:3000](http://localhost:3000), then sign in to a second application - in the same browser, so both share one ThunderID session. -4. Sign out of the second application, then reload this app: you are signed out here too. -Things to know before production: +3. Sign in at [http://localhost:3000](http://localhost:3000), then sign in to a second application in the same browser, so both share one ThunderID session. +4. Sign out of the second application, then reload this app. You are signed out here too. + +Before production: + +- The SDK records ended sessions in memory by default. If you run more than one instance, name a [Nitro storage](https://nitro.build/guide/storage) mount point that all of them share, since ThunderID's request reaches only one instance: -- The SDK records ended sessions in memory by default. If you run more than one instance, name a - [Nitro storage](https://nitro.build/guide/storage) mount point that all of them share, since - ThunderID's request reaches only one instance: ```ts thunderid: { backchannelLogout: { enabled: true, store: 'redis' }, @@ -116,4 +108,14 @@ Things to know before production: storage: { redis: { driver: 'redis', url: process.env.REDIS_URL } }, }, ``` + - An access token already handed to the browser or to another API stays valid until it expires. + +## Learn more + +- [Nuxt quickstart guide](https://thunderid.dev/docs/getting-started/connect-your-application/nuxt) +- [Nuxt SDK reference](https://thunderid.dev/docs/sdks-and-tools/nuxt/overview) + +## License + +Apache License 2.0. See [LICENSE](https://github.com/thunder-id/samples/blob/main/LICENSE). diff --git a/quickstarts/react/README.md b/quickstarts/react/README.md index a431301..e4ef69d 100644 --- a/quickstarts/react/README.md +++ b/quickstarts/react/README.md @@ -2,34 +2,51 @@ # ThunderID React Quickstart -A minimal React + Vite application demonstrating ThunderID authentication with OAuth 2.0, PKCE, and JWT support using the `@thunderid/react` SDK. +A React and Vite app that signs users in with the [ThunderID React SDK](https://www.npmjs.com/package/@thunderid/react) (`@thunderid/react`), using the authorization code flow with PKCE, and shows the signed-in user's profile and tokens. ## Prerequisites -- Node.js 18+ -- A ThunderID application +- Node.js 20 or later +- A running ThunderID server (`https://localhost:8090` by default) -## Setup +## Get the sample -1. Copy the environment template: - ```sh +Download the latest zip from the [releases](https://github.com/thunder-id/samples/releases?q=sample%2Fquickstarts%2Freact&expanded=true), or copy the source: + +```bash +npx degit thunder-id/samples/quickstarts/react my-app +cd my-app +``` + +## Configure + +1. In the ThunderID Console, create a **React** application with `http://localhost:5173` as its redirect URL, and copy its client ID. + +2. Create your `.env`: + + ```bash cp .env.example .env ``` -2. Fill in your ThunderID credentials in `.env`: - ``` - VITE_THUNDERID_CLIENT_ID=<your-client-id> - VITE_THUNDERID_BASE_URL=https://your-thunderid-instance - ``` + | Variable | Description | + |---|---| + | `VITE_THUNDERID_BASE_URL` | Base URL of your ThunderID server. | + | `VITE_THUNDERID_CLIENT_ID` | Client ID of the application. | -3. Install dependencies and start the dev server: - ```sh - npm install - npm run dev - ``` +## Run + +```bash +npm install +npm run dev +``` + +Open [http://localhost:5173](http://localhost:5173) and sign in. + +## Learn more -The app will be available at `http://localhost:5173`. +- [React quickstart guide](https://thunderid.dev/docs/getting-started/connect-your-application/react) +- [React SDK reference](https://thunderid.dev/docs/sdks-and-tools/react/overview) -## Docs +## License -Full SDK reference: [thunderid.dev/docs](https://thunderid.dev/docs) +Apache License 2.0. See [LICENSE](https://github.com/thunder-id/samples/blob/main/LICENSE). diff --git a/quickstarts/vue/README.md b/quickstarts/vue/README.md index b95351b..2c57240 100644 --- a/quickstarts/vue/README.md +++ b/quickstarts/vue/README.md @@ -2,34 +2,51 @@ # ThunderID Vue Quickstart -A minimal Vue 3 + Vite application demonstrating ThunderID authentication with OAuth 2.0, PKCE, and JWT support using the `@thunderid/vue` SDK. +A Vue 3 and Vite app that signs users in with the [ThunderID Vue SDK](https://www.npmjs.com/package/@thunderid/vue) (`@thunderid/vue`), using the authorization code flow with PKCE, and shows the signed-in user's profile. ## Prerequisites -- Node.js 18+ -- A ThunderID application +- Node.js 20 or later +- A running ThunderID server (`https://localhost:8090` by default) -## Setup +## Get the sample -1. Copy the environment template: - ```sh +Download the latest zip from the [releases](https://github.com/thunder-id/samples/releases?q=sample%2Fquickstarts%2Fvue&expanded=true), or copy the source: + +```bash +npx degit thunder-id/samples/quickstarts/vue my-app +cd my-app +``` + +## Configure + +1. In the ThunderID Console, create a **Vue** application with `http://localhost:5173` as its redirect URL, and copy its client ID. + +2. Create your `.env`: + + ```bash cp .env.example .env ``` -2. Fill in your ThunderID credentials in `.env`: - ``` - VITE_THUNDERID_CLIENT_ID=<your-client-id> - VITE_THUNDERID_BASE_URL=https://your-thunderid-instance - ``` + | Variable | Description | + |---|---| + | `VITE_THUNDERID_BASE_URL` | Base URL of your ThunderID server. | + | `VITE_THUNDERID_CLIENT_ID` | Client ID of the application. | -3. Install dependencies and start the dev server: - ```sh - npm install - npm run dev - ``` +## Run + +```bash +npm install +npm run dev +``` + +Open [http://localhost:5173](http://localhost:5173) and sign in. + +## Learn more -The app will be available at `http://localhost:5173`. +- [Vue quickstart guide](https://thunderid.dev/docs/getting-started/connect-your-application/vue) +- [Vue SDK reference](https://thunderid.dev/docs/sdks-and-tools/vue/overview) -## Docs +## License -Full SDK reference: [thunderid.dev/docs](https://thunderid.dev/docs) +Apache License 2.0. See [LICENSE](https://github.com/thunder-id/samples/blob/main/LICENSE). diff --git a/self-care/account/README.md b/self-care/account/README.md index b3672e1..b37f241 100644 --- a/self-care/account/README.md +++ b/self-care/account/README.md @@ -1,10 +1,10 @@ ![ThunderID Account Sample](https://raw.githubusercontent.com/thunder-id/samples/main/.github/assets/banners/self-care-account.png) -# ThunderID Account +# ThunderID Account Sample -ThunderID Account is where users manage their own ThunderID account. Signed-in users can view and edit their profile and -change their password. It is a React (Vite + TypeScript) app built with the self-care components of the -[ThunderID React SDK](https://www.npmjs.com/package/@thunderid/react). +A React (Vite and TypeScript) app where signed-in users manage their own ThunderID account: view and edit their profile, +and change their password. It is built with the self-care components of the +[ThunderID React SDK](https://www.npmjs.com/package/@thunderid/react) (`@thunderid/react`). | Account page tab | SDK component | | ---------------- | ------------------ | @@ -12,55 +12,59 @@ change their password. It is a React (Vite + TypeScript) app built with the self | Personal info | `UserProfile` | | Security | `ChangeCredential` | -The top nav uses `SignInButton`, `UserDropdown` and `SignedIn`/`SignedOut`. +The top bar uses `SignInButton`, `UserDropdown`, `SignedIn`, and `SignedOut`. ## Prerequisites -- Node.js 20+ and npm -- A running ThunderID server (defaults to `https://localhost:8090`) +- Node.js 20 or later +- A running ThunderID server (`https://localhost:8090` by default) -New to ThunderID with React? Follow the -[React quickstart guide](https://thunderid.dev/docs/next/getting-started/connect-your-application/react/) to set up a -ThunderID server and connect a React app to it. +## Get the sample -## Setup +Download the latest zip from the +[releases](https://github.com/thunder-id/samples/releases?q=sample%2Fself-care%2Faccount&expanded=true), or copy the +source: -1. In the ThunderID Console, - [create a React application](https://thunderid.dev/docs/getting-started/connect-your-application/react/#:~:text=2-,Create%20an%20Application,-Sign%20in%20to) - using the React quickstart guide. Use `http://localhost:5173` as the app's redirect URL, and copy the client ID it - gives you. +```bash +npx degit thunder-id/samples/self-care/account my-app +cd my-app +``` -2. Configure the app: +## Configure + +1. In the ThunderID Console, create a **React** application with `http://localhost:5173` as its redirect URL, and copy + its client ID. + +2. Create your `.env`: ```bash cp .env.example .env ``` - | Variable | Description | - | -------------------------- | ------------------------------------------- | - | `VITE_THUNDERID_BASE_URL` | Base URL of your ThunderID server. | - | `VITE_THUNDERID_CLIENT_ID` | Client ID of the application (from step 1). | + | Variable | Description | + | -------------------------- | ---------------------------------- | + | `VITE_THUNDERID_BASE_URL` | Base URL of your ThunderID server. | + | `VITE_THUNDERID_CLIENT_ID` | Client ID of the application. | -3. Install and start: +## Run - ```bash - npm install - npm run dev - ``` +```bash +npm install +npm run dev +``` -4. Open `http://localhost:5173` and sign in. You land on the account page. +Open [http://localhost:5173](http://localhost:5173) and sign in. You land on the account page. -## Adding new self-care components +## Add a self-care component When the SDK ships a new self-care component, bump `@thunderid/react` in `package.json` and add the component to -`src/pages/AccountPage.tsx`: - -- A new area (for example, Security): add a tab to `TABS` and `TILES`, and render the component for that tab. +`src/pages/AccountPage.tsx`. For a new area, add a tab to `TABS` and `TILES`, and render the component for that tab. -## Docs +## Learn more -- Full SDK reference: [thunderid.dev/docs](https://thunderid.dev/docs) +- [React quickstart guide](https://thunderid.dev/docs/getting-started/connect-your-application/react) +- [React SDK reference](https://thunderid.dev/docs/sdks-and-tools/react/overview) ## License -Apache License 2.0. +Apache License 2.0. See [LICENSE](https://github.com/thunder-id/samples/blob/main/LICENSE).