WSO2 Thunder ⚡

Identity Management Suite

Thunder is a modern, open-source identity management service designed for teams building secure, customizable authentication experiences across applications, services, and AI agents. It enables developers to design and orchestrate login, registration, and recovery flows using a flexible identity flow designer.

Designed for extensibility, scalability, and seamless containerized deployment, Thunder integrates naturally with microservices and DevOps environments—serving as the core identity layer for your cloud platform.

---

🚀 Features

• Standards-Based
  • OAuth 2/ OpenID Connect (OIDC): Client Credentials, Authorization Code, Refresh Token
• Login Options:
  • Basic Authentication (Username/Password)
  • Social Logins: Google, Github
  • SMS OTP
• Registration Options:
  • Username/Password
  • Social Registration: Google, Github
  • SMS OTP
• RESTful APIs:
  • App Native Login/Registration
  • User Management
  • Application Management
  • Identity Provider Management
  • Message Notification Sender Management

---

⚡ Quickstart

This Quickstart guide will help you get started with WSO2 Thunder quickly. It walks you through downloading and running the product, trying out the sample app, and exploring registering a user, logging in, and using the Client Credentials flow.

Download and Run WSO2 Thunder

You can run WSO2 Thunder either by downloading the release artifact or using the official Docker image.

Option 1: Run from Release Artifact

Follow these steps to download the latest release of WSO2 Thunder and run it locally.

1. Download the distribution from the latest release

   Download thunder-<version>-<os>-<arch>.zip from the latest release for your operating system and architecture.

   For example, if you are using a MacOS machine with a Apple Silicon (ARM64) processor, you would download thunder-<version>-macos-arm64.zip.

2. Unzip the product

   Unzip the downloaded file using the following command:

   unzip thunder-<version>-<os>-<arch>.zip

   Navigate to the unzipped directory:

   cd thunder-<version>-<os>-<arch>/

3. Setup the product

   You need to setup the server with the initial configurations and data before starting the server for the first time.

   If you are using a Linux or macOS machine:

   ./setup.sh

   If you are using a Windows machine:

   .\setup.ps1

   Note the id of the sample app indicated with the log line [INFO] Sample App ID: <id>. You'll need it for the sample app configuration.

4. Start the product

   If you are using a Linux or macOS machine:

   ./start.sh

   If you are using a Windows machine:

   .\start.ps1

   The product will start on https://localhost:8090.

Option 2: Run with Docker

Follow these steps to run WSO2 Thunder using Docker.

1. Pull the Docker image

   docker pull ghcr.io/asgardeo/thunder:latest

2. Setup the product

   You need to setup the server with the initial configurations and data before starting the server for the first time.

       docker run -it --rm \
           ghcr.io/asgardeo/thunder:latest \
           ./setup.sh

   Note the id of the sample app indicated with the log line [INFO] Sample App ID: <id>. You'll need it for the sample app configuration.

   [!NOTE] This will shut down the container after the setup is complete. You need to start the container again using the command in step 3. If you are using sqlite as the database, then you need to mount a volume to persist the database file and share it between the setup and server run containers.

3. Run the container

   docker run --rm \
     -p 8090:8090 \
     ghcr.io/asgardeo/thunder:latest

   Optionally if you want to modify the server configurations, you can mount a custom deployment.yaml file. Create a deployment.yaml file in your working directory similar to the deployment.yaml, and mount it as below:

   docker run --rm \
     -p 8090:8090 \
     -v $(pwd)/deployment.yaml:/opt/thunder/repository/conf/deployment.yaml \
     ghcr.io/asgardeo/thunder:latest

   Optionally if you want to use custom configurations or certificates, you can mount them as follows:

   docker run --rm \
     -p 8090:8090 \
     -v $(pwd)/deployment.yaml:/opt/thunder/repository/conf/deployment.yaml \
     -v $(pwd)/certs/server.cert:/opt/thunder/repository/resources/security/server.cert \
     -v $(pwd)/certs/server.key:/opt/thunder/repository/resources/security/server.key \
     ghcr.io/asgardeo/thunder:latest

Try Out the Product

Try out the Developer Console

Follow these steps to access the Developer Console:

1. Open your browser and navigate to https://localhost:8090/develop.

2. Log in using the admin credentials created during the initial data setup (admin / admin).

Try Out with the Sample App

Thunder provides two sample applications to help you get started quickly:

• React Vanilla Sample — Sample React application demonstrating direct API integration without external SDKs. Supports Native Flow API or Standard OAuth/OIDC.
• React SDK Sample — Sample React application demonstrating SDK-based integration using @asgardeo/react for OAuth 2.0/OIDC authentication.

React Vanilla Sample

1. Download the sample

   Download sample-app-react-vanilla-<version>-<os>-<arch>.zip from the latest release.

2. Unzip and navigate to the sample app directory

   unzip sample-app-react-vanilla-<version>-<os>-<arch>.zip
   cd sample-app-react-vanilla-<version>-<os>-<arch>/

3. Configure the sample

   Open app/runtime.json and set the applicationID to the sample app ID generated during "Setup the product":

   {
       "applicationID": "{your-application-id}"
   }

4. Start the sample

   ./start.sh

   Open your browser and navigate to https://localhost:3000 to access the sample app.

   📖 Refer to the README.md inside the extracted sample app for detailed configuration options including OAuth redirect-based login.

React SDK Sample

1. Download the sample

   Download sample-app-react-sdk-<version>-<os>-<arch>.zip from the latest release.

2. Unzip and navigate to the sample app directory

   unzip sample-app-react-sdk-<version>-<os>-<arch>.zip
   cd sample-app-react-sdk-<version>-<os>-<arch>/

3. Start the sample

   ./start.sh

   Open your browser and navigate to https://localhost:3000 to access the sample app.

   📖 Refer to the README.md inside the extracted sample app for detailed configuration and troubleshooting.

Self Register and Login (React Vanilla Sample)

The React Vanilla sample supports user self-registration and login:

1. Open https://localhost:3000 and click "Sign up" to register a new user.

   

2. After registration, use the same credentials to "Sign In".

   

3. Upon successful login, you'll see the home page with your access token.

Try Out Client Credentials Flow

To try out the Client Credentials flow, you first need to obtain a token to access the System APIs of Thunder. Follow these steps:

Replace <application_id> with the sample app ID generated during "Setup the product."

curl -k -X POST 'https://localhost:8090/flow/execute' \
  -d '{"applicationId":"<application_id>","flowType":"AUTHENTICATION", "inputs":{"username":"admin","password":"admin", "requested_permissions":"system"}}'

The response will contain an assertion field.

{"flowId":"<flow_id>","flowStatus":"COMPLETE","data":{},"assertion":"<assertion>"}

The Client Credentials flow is used to obtain an access token for machine-to-machine communication. This flow does not require user interaction and is typically used for server-to-server communication.

To try out the Client Credentials flow, follow these steps:

1. Create a Client Application

   Create a client application in the system to use for the Client Credentials flow. You can use the following cURL command to create a new application. Replace <assertion> with the assertion value obtained from the previous step.

   curl -kL -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' https://localhost:8090/applications \
   -H 'Authorization: Bearer <assertion>' \
   -d '{
       "name": "Test Sample App",
       "description": "Initial testing App",
       "auth_flow_graph_id": "auth_flow_config_basic",
       "inbound_auth_config": [
           {
               "type": "oauth2",
               "config": {
                   "client_id": "<client_id>",
                   "client_secret": "<client_secret>",
                   "redirect_uris": [
                       "https://localhost:3000"
                   ],
                   "grant_types": [
                       "client_credentials"
                   ],
                   "token_endpoint_auth_method": "client_secret_basic",
                   "pkce_required": false,
                   "public_client": false,
                   "scopes": ["api:read", "api:write"]
               }
           }
       ]
   }'

2. Obtain an Access Token

   Use the following cURL command to obtain an access token using the Client Credentials flow. Make sure to replace the <client_id> and <client_secret> with the values you used when creating the client application.

   curl -k -X POST https://localhost:8090/oauth2/token \
     -d 'grant_type=client_credentials' \
     -u '<client_id>:<client_secret>'

---

🛠️ Build the Product from Source

Prerequisites

• Go 1.25+
• Node.js 24+

---

• Build the product with tests using the following command:

  make all

---

⚙️ Development Setup

Prerequisites

• Go 1.24+
• Node.js 24+

Start Thunder in Development Mode

• Clone the repository:

  git clone https://github.com/asgardeo/thunder
  cd thunder

• Run the following command to start the product in development mode:

  make run

• The product will start on https://localhost:8090.

Start the Sample App in Development Mode

The sample apps support two configuration approaches:

• .env file: Used during development (values are bundled at build time)
• runtime.json file: Used for deployed/distributed apps (values loaded at runtime)

For development, use the .env file approach:

• Navigate to the sample app directory:

  cd samples/apps/react-vanilla-sample

• Create a file .env in the path samples/apps/react-vanilla-sample/ by copying .env.example:

  cp .env.example .env

• Edit the .env file and configure the required values:

  # Application ID registered in Thunder
  VITE_REACT_APP_AUTH_APP_ID={your-application-id}
  
  # Thunder server endpoints
  VITE_REACT_APP_SERVER_FLOW_ENDPOINT=https://localhost:8090/flow
  VITE_REACT_APPLICATIONS_ENDPOINT=https://localhost:8090/applications
  
  # Set to false for native flow, true for OAuth redirect flow
  VITE_REACT_APP_REDIRECT_BASED_LOGIN=false

  Note: For OAuth redirect flow, additional configurations like VITE_REACT_APP_CLIENT_ID, VITE_REACT_APP_SERVER_AUTHORIZATION_ENDPOINT, and VITE_REACT_APP_SERVER_TOKEN_ENDPOINT are required. See .env.example for the complete list.

• Install the dependencies:

  npm install

• Run the sample app using the following command:

  npm run dev

• Open your browser and navigate to http://localhost:3000 to see the sample app in action.

Remote Debugging Setup

Thunder supports remote debugging using Delve debugger, enabling debugging from any IDE that supports the Debug Adapter Protocol (DAP).

Install Delve Debugger

Install Delve using Go:

go install github.com/go-delve/delve/cmd/dlv@latest

Add Delve to your PATH:

export PATH=$PATH:$(go env GOPATH)/bin

Start Thunder in Debug Mode

From the distribution directory:

Linux/macOS:

./start.sh --debug

Windows (PowerShell):

.\start.ps1 --debug

Windows (Command Prompt):

start.bat --debug

The debugger will listen on localhost:2345 by default.

Connect from IDE

VS Code:

• Use the provided .vscode/launch.json configuration
• Press F5 or go to Run and Debug

GoLand/IntelliJ:

• Go to Run → Edit Configurations → + → Go Remote
• Set Host: 127.0.0.1, Port: 2345

Other IDEs:

• Configure DAP client to connect to 127.0.0.1:2345

Testing

Thunder includes both unit tests and integration tests:

Run Unit Tests

make test_unit

Run Integration Tests

make test_integration

Note: This command will run integration tests on an already built product. If you need to build the product before running integration tests, use:

make build_backend test_integration

Run Tests with Coverage

make build_with_coverage

This will build the server with coverage instrumentation, run tests, and generate coverage reports at target/ directory.

---

🔧 Advanced Setup & Configuration

Running with PostgreSQL Database

Step 1: Start and Initialize PostgreSQL

1. Navigate to local-development directory

cd install/local-development

2. Start PostgreSQL Database in background

docker compose up -d 

3. View PostgreSQL Database logs

docker compose logs -f

4. Stop PostgreSQL Database

docker compose down

• Stop PostgreSQL Database and delete all data

docker compose down -v

Step 2: Configure Thunder to Use PostgreSQL

1. Open the backend/cmd/server/repository/conf/deployment.yaml file.

2. Update the database section to point to the PostgreSQL database:

   database:
       identity:
           type: "postgres"
           hostname: "localhost"
           port: 5432
           name: "thunderdb"
           username: "asgthunder"
           password: "asgthunder"
           sslmode: "disable"
       runtime:
           type: "postgres"
           hostname: "localhost"
           port: 5432
           name: "runtimedb"
           username: "asgthunder"
           password: "asgthunder"
           sslmode: "disable"
       user:
           type: "postgres"
           hostname: "localhost"
           port: 5432
           name: "userdb"
           username: "asgthunder"
           password: "asgthunder"
           sslmode: "disable"

Step 3: Run the Product

make run

The product will now use the PostgreSQL database for its operations.

---

Star History

🤝 Contributing

Please refer to the CONTRIBUTING.md for guidelines on how to contribute to this project.

License

Licenses this source under the Apache License, Version 2.0 (LICENSE), You may not use this file except in compliance with the License.

---

(c) Copyright 2025 WSO2 LLC.