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.

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.
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>/
```
Start the product

Start the product using the following command:

If you are using a Linux or macOS machine:
```
bash start.sh
```
If you are using a Windows machine:
```
.\start.ps1
```

Option 2: Run with Docker

Follow these steps to run WSO2 Thunder using Docker.

Pull the Docker image

docker pull ghcr.io/asgardeo/thunder:latest

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

To get started quickly, you can set up initial data including an admin user and the Develop application using the --setup flag when starting Thunder:

Linux/macOS:

bash start.sh --setup

Windows (PowerShell):

.\start.ps1 --setup

This will:

Create a user schema
Create an admin user with credentials: admin / admin
Create the Develop application for accessing the admin console

You can also run the setup script manually at any time:

Linux/macOS:

bash scripts/setup_initial_data.sh

Windows (PowerShell):

.\scripts\setup_initial_data.ps1

After the setup is complete, follow these steps to access the Developer Console:

Open your browser and navigate to https://localhost:8090/develop.
Log in using the admin credentials created during the initial data setup (admin / admin).

Try Out with the Sample App

To quickly get started with Thunder, you can use the sample app provided with the product. This guide demonstrates how to download and run the sample app, self register a user and try out login to the sample app.

Download and Run the Sample App

Download the sample app from the latest release

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

Unzip and navigate to the sample app directory

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

Create required application for sample app in Thunder

Before using the sample app, you need to create an application in Thunder:

curl -kL -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' https://localhost:8090/applications \
-d '{
    "name": "Sample App",
    "description": "Sample application for testing",
    "url": "https://localhost:3000",
    "logo_url": "https://localhost:3000/logo.png",
    "tos_uri": "https://localhost:3000/terms",
    "policy_uri": "https://localhost:3000/privacy",
    "contacts": ["[email protected]", "[email protected]"],
    "auth_flow_graph_id": "auth_flow_config_basic",
    "registration_flow_graph_id": "registration_flow_config_basic",
    "is_registration_flow_enabled": true,
    "user_attributes": ["given_name","family_name","email","groups"],
    "inbound_auth_config": [{
        "type": "oauth2",
        "config": {
            "client_id": "sample_app_client",
            "client_secret": "sample_app_secret",
            "redirect_uris": ["https://localhost:3000"],
            "grant_types": ["authorization_code", "client_credentials"],
            "response_types": ["code"],
            "token_endpoint_auth_method": "client_secret_basic",
            "pkce_required": false,
            "public_client": false,
            "scopes": ["openid", "profile", "email"],
            "token": {
                "issuer": "thunder",
                "access_token": {
                    "validity_period": 3600,
                    "user_attributes": ["given_name","family_name","email","groups"]
                },
                "id_token": {
                    "validity_period": 3600,
                    "user_attributes": ["given_name","family_name","email","groups"],
                    "scope_claims": {
                        "profile": ["name","given_name","family_name","picture"],
                        "email": ["email","email_verified"],
                        "phone": ["phone_number","phone_number_verified"],
                        "group": ["groups"]
                    }
                }
            }
        }
    }]
}'

Note the id from the response - you'll need it for the sample app configuration.

Configure the sample app

Open the runtime.json file in the thunder-sample-app---/app directory and update the configurations:
- applicationID: Use the application ID from step 3
- flowEndpoint: The root endpoint for the flow execution API (default: https://localhost:8090/flow)
Start the sample app
```
sh start.sh
```

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

Self Register a User

To self register a user in the sample app, follow these steps:

Open the sample app in your browser at https://localhost:3000 and click on the "Sign up" button.
Provide a username and password for the new user and click on the "Create Account" button.
Fill in the additional user attributes such as first name, last name and email address. Click "Continue" to complete the registration.
After successful registration, you will be automatically logged in to the sample application.

Login to the Sample App

To log in to the sample app, follow these steps:

Open the sample app in your browser at https://localhost:3000.
Enter username and password you used during the self registration process and click on the "Sign In" button.
If the login is successful, you will be redirected to the home page of the sample app with the access token.

Try Out Client Credentials Flow

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:

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.

curl -kL -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' https://localhost:8090/applications \
-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"]
            }
        }
    ]
}'

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 20+

Build the product with tests using the following command:
```
make all
```

⚙️ Development Setup

Prerequisites

Go 1.24+
Node.js 20+

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

Navigate to the sample app directory:
```
cd samples/apps/oauth
```

Create a file .env in the path samples/apps/oauth/ and add below values.

VITE_REACT_APP_SERVER_FLOW_ENDPOINT=https://localhost:8090/flow
VITE_REACT_APPLICATIONS_ENDPOINT=https://localhost:8090/applications
VITE_REACT_APP_AUTH_APP_ID={your-application-id}
VITE_REACT_APP_REDIRECT_BASED_LOGIN=false

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

Navigate to local-development directory

cd install/local-development

Start PostgreSQL Database in background

docker compose up -d

View PostgreSQL Database logs

docker compose logs -f

Stop PostgreSQL Database

docker compose down

Stop PostgreSQL Database and delete all data

docker compose down -v

Step 2: Configure Thunder to Use PostgreSQL

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

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"

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.

Name		Name	Last commit message	Last commit date
Latest commit History 1,013 Commits
.github		.github
.vscode		.vscode
api		api
backend		backend
docs		docs
frontend		frontend
install		install
resources/images		resources/images
samples		samples
tests/integration		tests/integration
.dockerignore		.dockerignore
.gitignore		.gitignore
.nvmrc		.nvmrc
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
build.ps1		build.ps1
build.sh		build.sh
codecov.yml		codecov.yml
start.ps1		start.ps1
start.sh		start.sh
version.txt		version.txt

License

asgardeo/thunder

Folders and files

Latest commit

History

Repository files navigation

WSO2 Thunder ⚡

Identity Management Suite

🚀 Features

⚡ Quickstart

Download and Run WSO2 Thunder

Option 1: Run from Release Artifact

Option 2: Run with Docker

Try Out the Product

Try out the Developer Console

Try Out with the Sample App

Download and Run the Sample App

Self Register a User

Login to the Sample App

Try Out Client Credentials Flow

🛠️ Build the Product from Source

Prerequisites

⚙️ Development Setup

Prerequisites

Start Thunder in Development Mode

Start the Sample App in Development Mode

Remote Debugging Setup

Install Delve Debugger

Start Thunder in Debug Mode

Connect from IDE

Testing

Run Unit Tests

Run Integration Tests

Run Tests with Coverage

🔧 Advanced Setup & Configuration

Running with PostgreSQL Database

Step 1: Start and Initialize PostgreSQL

Step 2: Configure Thunder to Use PostgreSQL

Step 3: Run the Product

Star History

🤝 Contributing

License

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors 27

Languages

Packages