Securing My Stack: Features and Experience Integrating Asgardeo, Ballerina, and Choreo

Mahesha Dinushan Heenatigala — Thu, 04 Dec 2025 16:49:03 +0000

🔑 Securing My Stack: Features and Experience with WSO2 Asgardeo

🚀 Introduction: Building a Secure Microservice Gateway

For my Secure Gateway Project—integrating a React Frontend with a Ballerina Backend on WSO2 Choreo—I chose WSO2 Asgardeo as the core Identity Provider (IDP). My goal was to leverage a modern, cloud-native Identity and Access Management (CIAM) solution that seamlessly handles the complexities of OAuth 2.0 and OpenID Connect (OIDC).

This post details the specific features of Asgardeo I utilized and explores my hands-on experience integrating them into a secure microservice architecture.

🏗️ Architecture at a Glance

Our simple stack provided layered security:

Component	Technology	Security Role
Frontend	React (Vite)	Initiates the OIDC flow and handles user session.
Backend API	Ballerina	Contains protected business logic, secured by a JWT Validator.
API Gateway	Choreo Connect	The first security layer; validates the JWT before routing.
IDP	Asgardeo	Issues the authenticated JSON Web Token (JWT).

💻 Feature 1: Seamless SPA Setup and PKCE

The developer experience for setting up the client application in the Asgardeo Console was remarkably straightforward.

My Experience: Intuitive and Secure Configuration

I defined my application as a Single Page Application (SPA). This choice instantly configured the necessary security protocol: the Authorization Code flow with PKCE (Proof Key for Code Exchange).

PKCE is Critical: For public clients like an SPA (which cannot securely store a Client Secret), PKCE is essential to prevent code interception attacks. Asgardeo automatically mandates this when the SPA template is chosen, offering immediate security without manual configuration struggle.
Redirect Management: Configuring the Authorized Redirect URLs (e.g., https://<my-app-url>/callback) was simple and clear, which is crucial for preventing authentication flow breakage.

🛡️ Feature 2: The React SDK (`@asgardeo/auth-react`)

Integrating the actual login/logout functionality was significantly simplified using the official Asgardeo SDK for React.

My Experience: Token Reliability in a Reactive App

The SDK provided the high-level hooks and context necessary to manage the user session:

useAuthContext Hook: This hook provided instant access to the user's authentication state (isAuthenticated) and session data.
Token Reliability: I learned a crucial distinction: relying on the reactive state for the access token can lead to race conditions. The SDK's getAccessToken() function, which is an asynchronous method, proved absolutely reliable for fetching the final, valid token just before initiating the API call. This guaranteed that the Authorization: Bearer <token> header was always current and complete.

javascript // Reliable way to fetch the token just before the API call const fetchData = async () => { const token = await getAccessToken(); const apiResponse = await fetch(apiUrl, { headers: { Authorization: `Bearer ${token}` } }); // ... handle response }

🔑 Feature 3: JWT Access Token Generation and Validation

The core function of Asgardeo was to issue a token that my backend could trust. This feature led to my deepest technical investigation.

My Experience: Uncovering the Issuer Conflict

My Ballerina API required a JWT (JSON Web Token) for validation. Asgardeo issued a valid JWT, but its content presented a challenge:

The Problematic Claim: The Issuer (iss) claim in the generated JWT contained the full token endpoint URL (https://.../oauth2/token).
The Standard Expectation: My validators were initially configured to expect the base URL (https://.../t/maheshadinushan).

This experience demonstrated the importance of inspecting the actual token payload

Lesson Learned: While documentation suggests the standard base URL, I had to configure my API Gateway (Choreo) and my Ballerina service to trust the full endpoint URL (.../oauth2/token) to match the exact token generated by Asgardeo. This adaptability was key to solving the JWT Validator Deadlock.

DEV Community: Mahesha Dinushan Heenatigala