{"id":31548725,"url":"https://github.com/asgardeo/thunder","last_synced_at":"2026-02-20T14:01:28.346Z","repository":{"id":290964928,"uuid":"976142433","full_name":"asgardeo/thunder","owner":"asgardeo","description":"Thunder is a Go based Identity and Access Management product by WSO2","archived":false,"fork":false,"pushed_at":"2025-12-23T16:16:12.000Z","size":31409,"stargazers_count":88,"open_issues_count":92,"forks_count":247,"subscribers_count":20,"default_branch":"main","last_synced_at":"2025-12-23T18:04:47.256Z","etag":null,"topics":["access-management","adaptive-authentication","authentication","authorization","go","golang","hacktoberfest","identity","mfa","oauth2","oidc"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/asgardeo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-05-01T15:17:40.000Z","updated_at":"2025-12-23T16:16:16.000Z","dependencies_parsed_at":"2025-05-01T16:29:50.581Z","dependency_job_id":"80123153-72d9-4d4a-a502-6d2bedaa3107","html_url":"https://github.com/asgardeo/thunder","commit_stats":null,"previous_names":["asgardeo/thunder"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/asgardeo/thunder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asgardeo%2Fthunder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asgardeo%2Fthunder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asgardeo%2Fthunder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asgardeo%2Fthunder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/asgardeo","download_url":"https://codeload.github.com/asgardeo/thunder/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asgardeo%2Fthunder/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28337737,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T06:09:07.588Z","status":"ssl_error","status_checked_at":"2026-01-12T06:05:18.301Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["access-management","adaptive-authentication","authentication","authorization","go","golang","hacktoberfest","identity","mfa","oauth2","oidc"],"created_at":"2025-10-04T16:53:22.465Z","updated_at":"2026-02-20T14:01:28.337Z","avatar_url":"https://github.com/asgardeo.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WSO2 Thunder ⚡\n\n### Identity Management Suite\n\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![GitHub last commit](https://img.shields.io/github/last-commit/asgardeo/thunder.svg)](https://github.com/asgardeo/thunder/commits/main)\n[![GitHub issues](https://img.shields.io/github/issues/asgardeo/thunder.svg)](https://github.com/asgardeo/thunder/issues)\n[![codecov.io](https://codecov.io/github/asgardeo/thunder/coverage.svg?branch=main)](https://codecov.io/github/asgardeo/thunder?branch=main)\n\nThunder 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.\n\nDesigned 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.\n\n---\n\n## 🚀 Features\n\n- **Standards-Based**\n  - OAuth 2/ OpenID Connect (OIDC): Client Credentials, Authorization Code, Refresh Token\n- **Login Options:**\n  - Basic Authentication (Username/Password)\n  - Social Logins: Google, Github\n  - SMS OTP\n- **Registration Options:**\n  - Username/Password\n  - Social Registration: Google, Github\n  - SMS OTP\n- **RESTful APIs:**\n  - App Native Login/Registration\n  - User Management\n  - Application Management\n  - Identity Provider Management\n  - Message Notification Sender Management\n\n---\n\n## ⚡ Quickstart\n\nThis 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.\n\n### Download and Run WSO2 Thunder\n\nYou can run WSO2 Thunder either by downloading the release artifact or using the official Docker image.\n\n#### Option 1: Run from Release Artifact\n\nFollow these steps to download the latest release of WSO2 Thunder and run it locally.\n\n1. **Download the distribution from the latest release**\n\n    Download `thunder-\u003cversion\u003e-\u003cos\u003e-\u003carch\u003e.zip` from the [latest release](https://github.com/asgardeo/thunder/releases/latest) for your operating system and architecture.\n\n    For example, if you are using a MacOS machine with a Apple Silicon (ARM64) processor, you would download `thunder-\u003cversion\u003e-macos-arm64.zip`.\n\n2. **Unzip the product**\n\n    Unzip the downloaded file using the following command:\n\n    ```bash\n    unzip thunder-\u003cversion\u003e-\u003cos\u003e-\u003carch\u003e.zip\n    ```\n\n    Navigate to the unzipped directory:\n\n    ```bash\n    cd thunder-\u003cversion\u003e-\u003cos\u003e-\u003carch\u003e/\n    ```\n\n3. **Setup the product**\n\n    You need to setup the server with the initial configurations and data before starting the server for the first time.\n\n    If you are using a Linux or macOS machine:\n\n    ```bash\n    ./setup.sh\n    ```\n\n    If you are using a Windows machine:\n\n    ```powershell\n    .\\setup.ps1\n    ```\n\n    **Note the id of the sample app indicated with the log line `[INFO] Sample App ID: \u003cid\u003e`.** You'll need it for the sample app configuration.\n\n4. **Start the product**\n\n    If you are using a Linux or macOS machine:\n\n    ```bash\n    ./start.sh\n    ```\n\n    If you are using a Windows machine:\n\n    ```powershell\n    .\\start.ps1\n    ```\n\n    The product will start on `https://localhost:8090`.\n\n#### Option 2: Run with Docker Compose\n\nFollow these steps to run WSO2 Thunder using Docker Compose.\n\n1. **Download the Docker Compose file**\n\n    Download the `docker-compose.yml` file using the following command:\n\n    ```bash\n    curl -o docker-compose.yml https://raw.githubusercontent.com/asgardeo/thunder/v0.23.0/install/quick-start/docker-compose.yml\n    ```\n\n2. **Start Thunder**\n\n    Run the following command in the directory where you downloaded the `docker-compose.yml` file:\n\n    ```bash\n    docker compose up\n    ```\n\n    This will automatically:\n    - Initialize the database\n    - Run the setup process\n    - Start the Thunder server\n\n    **Note the id of the sample app indicated with the log line `[INFO] Sample App ID: \u003cid\u003e` in the setup logs.** You'll need it for the sample app configuration.\n\n    The product will start on `https://localhost:8090`.\n\n### Try Out the Product\n\n#### Try out the Developer Console\n\nFollow these steps to access the Developer Console:\n\n1. Open your browser and navigate to [https://localhost:8090/develop](https://localhost:8090/develop).\n\n2. Log in using the admin credentials created during the initial data setup (`admin` / `admin`).\n\n#### Try Out with the Sample App\n\nThunder provides two sample applications to help you get started quickly:\n\n- **React Vanilla Sample** — Sample React application demonstrating direct API integration without external SDKs. Supports Native Flow API or Standard OAuth/OIDC.\n- **React SDK Sample** — Sample React application demonstrating SDK-based integration using `@asgardeo/react` for OAuth 2.0/OIDC authentication.\n\n##### React Vanilla Sample\n\n1. **Download the sample**\n\n    Download `sample-app-react-vanilla-\u003cversion\u003e-\u003cos\u003e-\u003carch\u003e.zip` from the [latest release](https://github.com/asgardeo/thunder/releases/latest).\n\n2. **Unzip and navigate to the sample app directory**\n\n    ```bash\n    unzip sample-app-react-vanilla-\u003cversion\u003e-\u003cos\u003e-\u003carch\u003e.zip\n    cd sample-app-react-vanilla-\u003cversion\u003e-\u003cos\u003e-\u003carch\u003e/\n    ```\n\n3. **Configure the sample**\n\n    Open `app/runtime.json` and set the `applicationID` to the sample app ID generated during \"Setup the product\":\n\n    ```json\n    {\n        \"applicationID\": \"{your-application-id}\"\n    }\n    ```\n\n4. **Start the sample**\n\n    ```bash\n    ./start.sh\n    ```\n\n    Open your browser and navigate to [https://localhost:3000](https://localhost:3000) to access the sample app.\n\n    \u003e 📖 Refer to the `README.md` inside the extracted sample app for detailed configuration options including OAuth redirect-based login.\n\n##### React SDK Sample\n\n1. **Download the sample**\n\n    Download `sample-app-react-sdk-\u003cversion\u003e-\u003cos\u003e-\u003carch\u003e.zip` from the [latest release](https://github.com/asgardeo/thunder/releases/latest).\n\n2. **Unzip and navigate to the sample app directory**\n\n    ```bash\n    unzip sample-app-react-sdk-\u003cversion\u003e-\u003cos\u003e-\u003carch\u003e.zip\n    cd sample-app-react-sdk-\u003cversion\u003e-\u003cos\u003e-\u003carch\u003e/\n    ```\n\n3. **Start the sample**\n\n    ```bash\n    ./start.sh\n    ```\n\n    Open your browser and navigate to [https://localhost:3000](https://localhost:3000) to access the sample app.\n\n    \u003e 📖 Refer to the `README.md` inside the extracted sample app for detailed configuration and troubleshooting.\n\n##### Self Register and Login (React Vanilla Sample)\n\nThe React Vanilla sample supports user self-registration and login:\n\n1. Open [https://localhost:3000](https://localhost:3000) and click **\"Sign up\"** to register a new user.\n\n    \u003cp align=\"left\"\u003e\n        \u003cimg src=\"resources/images/sample-app-self-registration-basic.png\" alt=\"Self Registration Username Password\" width=\"400\"\u003e\n    \u003c/p\u003e\n\n2. After registration, use the same credentials to **\"Sign In\"**.\n\n    \u003cp align=\"left\"\u003e\n        \u003cimg src=\"resources/images/sample-app-login.png\" alt=\"Login to Sample App\" width=\"400\"\u003e\n    \u003c/p\u003e\n\n3. Upon successful login, you'll see the home page with your access token.\n\n\n#### Obtain System API Token\n\nTo access the system APIs of Thunder, you need a token with system permissions. Follow the steps below to obtain a system API token.\n\n1. Run the following command, replacing `\u003capplication_id\u003e` with the sample app ID generated during \"Setup the product.\"\n\n```bash\ncurl -k -X POST 'https://localhost:8090/flow/execute' \\\n  -d '{\"applicationId\":\"\u003capplication_id\u003e\",\"flowType\":\"AUTHENTICATION\"}'\n```\n2. Extract the `flowId` value from the response.\n```json\n{\"flowId\":\"\u003cflow_id\u003e\",\"flowStatus\":\"INCOMPLETE\", ...}\n```\n\n3. Run the following command, replacing `\u003cflow_id\u003e` with the `flowId` value you extracted above.\n```bash\ncurl -k -X POST 'https://localhost:8090/flow/execute' \\\n  -d '{\"flowId\":\"\u003cflow_id\u003e\", \"inputs\":{\"username\":\"admin\",\"password\":\"admin\", \"requested_permissions\":\"system\"},\"action\": \"action_001\"}'\n```\n\n4. Obtain the system API token by extracting the `assertion` value from the response.\n```json\n{\"flowId\":\"\u003cflow_id\u003e\",\"flowStatus\":\"COMPLETE\",\"data\":{},\"assertion\":\"\u003cassertion\u003e\"}\n```\n\n#### Try Out Client Credentials Flow\n\nThe 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.\n\nTo try out the Client Credentials flow, follow these steps:\n\n1. Create a Client Application\n\n   Application creation is secured functionality, so you first need to obtain a system API token as mentioned in the \"Obtain System API Token\" section above.\n\n   Run the following command, replacing `\u003cassertion\u003e` with the assertion value obtained from the previous step.\n\n    ```bash\n    curl -kL -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' https://localhost:8090/applications \\\n    -H 'Authorization: Bearer \u003cassertion\u003e' \\\n    -d '{\n        \"name\": \"Test Sample App\",\n        \"description\": \"Initial testing App\",\n        \"inbound_auth_config\": [\n            {\n                \"type\": \"oauth2\",\n                \"config\": {\n                    \"client_id\": \"\u003cclient_id\u003e\",\n                    \"client_secret\": \"\u003cclient_secret\u003e\",\n                    \"redirect_uris\": [\n                        \"https://localhost:3000\"\n                    ],\n                    \"grant_types\": [\n                        \"client_credentials\"\n                    ],\n                    \"token_endpoint_auth_method\": \"client_secret_basic\",\n                    \"pkce_required\": false,\n                    \"public_client\": false,\n                    \"scopes\": [\"api:read\", \"api:write\"]\n                }\n            }\n        ]\n    }'\n    ```\n\n2. Obtain an Access Token\n\n   Use the following cURL command to obtain an access token using the Client Credentials flow. Make sure to replace the `\u003cclient_id\u003e` and `\u003cclient_secret\u003e` with the values you used when creating the client application.\n\n    ```bash\n    curl -k -X POST https://localhost:8090/oauth2/token \\\n      -d 'grant_type=client_credentials' \\\n      -u '\u003cclient_id\u003e:\u003cclient_secret\u003e'\n    ```\n\n---\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ch2\u003e🛠️ Build the Product from Source\u003c/h2\u003e\u003c/summary\u003e\n\n### Prerequisites\n\n- Go 1.26+\n- Node.js 24+\n\n---\n\n- Build the product with tests using the following command:\n\n    ```bash\n    make all\n    ```\n\n\u003c/details\u003e\n\n---\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ch2\u003e⚙️ Development Setup\u003c/h2\u003e\u003c/summary\u003e\n\n### Prerequisites\n\n- Go 1.26+\n- Node.js 24+\n\n### Start Thunder in Development Mode\n\n- Clone the repository:\n\n    ```bash\n    git clone https://github.com/asgardeo/thunder\n    cd thunder\n    ```\n\n- Run the following command to start the product in development mode:\n\n    ```bash\n    make run\n    ```\n\n- The product will start on `https://localhost:8090`.\n\n### Start the Sample App in Development Mode\n\nThe sample apps support two configuration approaches:\n- **`.env` file**: Used during development (values are bundled at build time)\n- **`runtime.json` file**: Used for deployed/distributed apps (values loaded at runtime)\n\nFor development, use the `.env` file approach:\n\n- Navigate to the sample app directory:\n\n  ```bash\n  cd samples/apps/react-vanilla-sample\n  ```\n\n- Create a file `.env` in the path `samples/apps/react-vanilla-sample/` by copying `.env.example`:\n\n  ```bash\n  cp .env.example .env\n  ```\n\n- Edit the `.env` file and configure the required values:\n\n  ```env\n  # Application ID registered in Thunder\n  VITE_REACT_APP_AUTH_APP_ID={your-application-id}\n  \n  # Thunder server endpoints\n  VITE_REACT_APP_SERVER_FLOW_ENDPOINT=https://localhost:8090/flow\n  VITE_REACT_APPLICATIONS_ENDPOINT=https://localhost:8090/applications\n  \n  # Set to false for native flow, true for OAuth redirect flow\n  VITE_REACT_APP_REDIRECT_BASED_LOGIN=false\n  ```\n\n  \u003e **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.\n\n- Install the dependencies:\n\n  ```bash\n  npm install\n  ```\n\n- Run the sample app using the following command:\n\n  ```bash\n  npm run dev\n  ```\n  \n- Open your browser and navigate to `http://localhost:3000` to see the sample app in action.\n\n### Remote Debugging Setup\n\nThunder supports remote debugging using Delve debugger, enabling debugging from any IDE that supports the Debug Adapter Protocol (DAP).\n\n#### Install Delve Debugger\n\nInstall Delve using Go:\n\n```bash\ngo install github.com/go-delve/delve/cmd/dlv@latest\n```\n\nAdd Delve to your PATH:\n\n```bash\nexport PATH=$PATH:$(go env GOPATH)/bin\n```\n\n#### Start Thunder in Debug Mode\n\nFrom the distribution directory:\n\n**Linux/macOS:**\n\n```bash\n./start.sh --debug\n```\n\n**Windows (PowerShell):**\n\n```powershell\n.\\start.ps1 --debug\n```\n\n**Windows (Command Prompt):**\n\n```cmd\nstart.bat --debug\n```\n\nThe debugger will listen on `localhost:2345` by default.\n\n#### Connect from IDE\n\n**VS Code:**\n- Use the provided `.vscode/launch.json` configuration\n- Press `F5` or go to `Run and Debug`\n\n**GoLand/IntelliJ:**\n- Go to `Run → Edit Configurations → + → Go Remote`\n- Set Host: `127.0.0.1`, Port: `2345`\n\n**Other IDEs:**\n- Configure DAP client to connect to `127.0.0.1:2345`\n\n### Testing\n\nThunder includes both unit tests and integration tests:\n\n#### Run Unit Tests\n\n```bash\nmake test_unit\n```\n\n#### Run Integration Tests\n\n```bash\nmake test_integration\n```\n\n**Note:** This command will run integration tests on an already built product. If you need to build the product before running integration tests, use:\n\n```bash\nmake build_backend test_integration\n```\n\n#### Run Tests with Coverage\n\n```bash\nmake build_with_coverage\n```\n\nThis will build the server with coverage instrumentation, run tests, and generate coverage reports at `target/` directory.\n\n\u003c/details\u003e\n\n---\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ch2\u003e🔧 Advanced Setup \u0026 Configuration\u003c/h2\u003e\u003c/summary\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ch3\u003eRunning with PostgreSQL Database\u003c/h3\u003e\u003c/summary\u003e\n\n#### Step 1: Start and Initialize PostgreSQL\n\n1. Navigate to local-development directory\n\n```bash\ncd install/local-development\n```\n\n2. Start PostgreSQL Database in background\n\n```bash\ndocker compose up -d \n```\n\n3. View PostgreSQL Database logs\n\n```bash\ndocker compose logs -f\n```\n\n4. Stop PostgreSQL Database\n\n```bash\ndocker compose down\n```\n\n- Stop PostgreSQL Database and delete all data \n\n```bash\ndocker compose down -v\n```\n\n#### Step 2: Configure Thunder to Use PostgreSQL\n\n1. Open the `backend/cmd/server/repository/conf/deployment.yaml` file.\n2. Update the `database` section to point to the PostgreSQL database:\n\n    ```yaml\n    database:\n        identity:\n            type: \"postgres\"\n            hostname: \"localhost\"\n            port: 5432\n            name: \"thunderdb\"\n            username: \"asgthunder\"\n            password: \"asgthunder\"\n            sslmode: \"disable\"\n        runtime:\n            type: \"postgres\"\n            hostname: \"localhost\"\n            port: 5432\n            name: \"runtimedb\"\n            username: \"asgthunder\"\n            password: \"asgthunder\"\n            sslmode: \"disable\"\n        user:\n            type: \"postgres\"\n            hostname: \"localhost\"\n            port: 5432\n            name: \"userdb\"\n            username: \"asgthunder\"\n            password: \"asgthunder\"\n            sslmode: \"disable\"\n    ```\n\n#### Step 3: Run the Product\n\n   ```bash\n   make run\n   ```\n\nThe product will now use the PostgreSQL database for its operations.\n\n\u003c/details\u003e\n\n\u003c/details\u003e\n\n---\n\n## Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=asgardeo/thunder\u0026type=date\u0026legend=top-left)](https://www.star-history.com/#asgardeo/thunder\u0026type=date\u0026legend=top-left)\n\n## 🤝 Contributing\n\nPlease refer to the [CONTRIBUTING.md](docs/content/community/contributing/README.md) for guidelines on how to contribute to this project.\n\n## License\n\nLicenses this source under the Apache License, Version 2.0 ([LICENSE](LICENSE)), You may not use this file except in compliance with the License.\n\n---------------------------------------------------------------------------\n(c) Copyright 2025 WSO2 LLC.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasgardeo%2Fthunder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fasgardeo%2Fthunder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasgardeo%2Fthunder/lists"}