JWT Integration Skill

Use this skill to implement JWT authentication and authorization across StyleMate microservices including both .NET APIs and React frontends.

When to Use

• Setting up JWT authentication in new services
• Configuring authorization policies in .NET APIs
• Implementing token interceptors in React apps
• Troubleshooting authentication issues
• Adding role-based access control

What This Skill Does

1. .NET API JWT Setup

Configures:

• JWT validation in Program.cs
• Authorization policies for roles
• Claims extraction from tokens
• Business isolation via businessId claim
• Secure token validation parameters

2. React JWT Integration

Sets up:

• Axios interceptors for token injection
• Automatic token refresh on 401
• Token storage (httpOnly cookies or secure storage)
• Route guards based on JWT claims
• Business context from token

3. Authorization Policies

Creates policies for:

• RequireOwnerOrAdmin
• RequireManagerOrAbove
• RequireStaffAccess
• RequireEmailConfirmed
• RequireBusiness

4. Route Metadata

Configures route metadata with:

• Allowed roles array
• Email confirmation requirements
• Business association requirements
• Two-factor auth requirements

Expected Inputs

• Service context name
• Required authorization policies
• JWT issuer and audience configuration
• Roles to support

Deliverables

• .NET Program.cs JWT configuration
• React Axios interceptor setup
• Authorization policies
• Route guard implementation
• Token refresh logic

Example Usage

Set up JWT authentication for the appointments service. It needs Owner, Admin, and
Staff access levels. All endpoints should require a valid business association.

.NET API Configuration

Program.cs JWT Setup

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidateAudience = true,
            ValidateLifetime = true,
            ValidateIssuerSigningKey = true,
            ValidIssuer = builder.Configuration["Jwt:Issuer"],
            ValidAudience = builder.Configuration["Jwt:Audience"],
            IssuerSigningKey = new SymmetricSecurityKey(
                Encoding.UTF8.GetBytes(builder.Configuration["Jwt:SecretKey"]))
        };
    });

Authorization Policies

builder.Services.AddAuthorization(options =>
{
    options.AddPolicy("RequireOwnerOrAdmin", policy =>
        policy.RequireClaim("role", "Owner", "Admin"));

    options.AddPolicy("RequireManagerOrAbove", policy =>
        policy.RequireClaim("role", "Owner", "Admin", "Manager"));

    options.AddPolicy("RequireBusiness", policy =>
        policy.RequireClaim("business_id"));

    options.AddPolicy("RequireEmailConfirmed", policy =>
        policy.RequireClaim("email_confirmed", "true"));
});

Controller Usage

[ApiController]
[Route("api/appointments/[controller]")]
[Authorize] // Requires valid JWT
public class AppointmentsController : ControllerBase
{
    [HttpGet]
    [Authorize(Policy = "RequireStaffAccess")]
    public async Task<IActionResult> GetAll()
    {
        var businessId = User.FindFirst("business_id")?.Value;
        var userId = User.FindFirst(ClaimTypes.NameIdentifier)?.Value;

        // Query filtered by businessId
        var appointments = await _service.GetByBusinessAsync(Guid.Parse(businessId));
        return Ok(appointments);
    }
}

React Frontend Configuration

Axios Interceptor Setup

import axios from 'axios';

const apiClient = axios.create({
  baseURL: '/api/appointments',
  withCredentials: true // For httpOnly cookies
});

// Request interceptor - Add JWT token
apiClient.interceptors.request.use(
  (config) => {
    const token = localStorage.getItem('accessToken');
    if (token) {
      config.headers.Authorization = `Bearer ${token}`;
    }
    return config;
  },
  (error) => Promise.reject(error)
);

// Response interceptor - Handle token refresh
apiClient.interceptors.response.use(
  (response) => response,
  async (error) => {
    const originalRequest = error.config;

    if (error.response?.status === 401 && !originalRequest._retry) {
      originalRequest._retry = true;

      try {
        const { data } = await axios.post('/api/auth/refresh');
        localStorage.setItem('accessToken', data.token);
        originalRequest.headers.Authorization = `Bearer ${data.token}`;
        return apiClient(originalRequest);
      } catch (refreshError) {
        // Redirect to login
        window.location.href = '/login';
        return Promise.reject(refreshError);
      }
    }

    return Promise.reject(error);
  }
);

export default apiClient;

Route Guards

import { RouteObject } from 'react-router-dom';

interface RouteMetadata {
  label: string;
  allowedRoles: string[];
  requireEmailConfirmed: boolean;
  requireBusiness: boolean;
  requireTwoFactor?: boolean;
}

export const routes: RouteObject[] = [
  {
    path: '/appointments',
    element: <AppointmentsPage />,
    handle: {
      label: 'Appointments',
      allowedRoles: ['Owner', 'Admin', 'Staff'],
      requireEmailConfirmed: true,
      requireBusiness: true
    } as RouteMetadata
  }
];

JWT Claims Hook

import { jwtDecode } from 'jwt-decode';

interface JwtPayload {
  sub: string;
  email: string;
  role: string;
  business_id: string;
  email_confirmed: boolean;
}

export function useJwtClaims() {
  const token = localStorage.getItem('accessToken');

  if (!token) return null;

  try {
    return jwtDecode<JwtPayload>(token);
  } catch {
    return null;
  }
}

Security Checklist

• JWT tokens validated on all endpoints
• Tokens not stored in localStorage (use httpOnly cookies)
• Token refresh implemented
• Expired tokens handled gracefully
• Business isolation enforced via claims
• CORS properly configured
• HTTPS required in production
• Sensitive claims not exposed client-side

Common Issues

Issue: 401 on all requests

Cause: Token not being sent or invalid signature Fix: Check Axios interceptor, verify JWT_SECRET matches

Issue: Can access other business data

Cause: Missing business_id filter Fix: Always filter queries by businessId from JWT

Issue: Token expired errors

Cause: No refresh logic Fix: Implement token refresh in interceptor

Issue: CORS errors

Cause: Missing credentials or wrong origin Fix: Set withCredentials: true and configure CORS properly