idp-validate-token

Implements local JWT validation for APIs receiving Overlens IDP access tokens.

Updated Jul 24, 2026
One-click install
npx skills add https://github.com/overlens/claude-marketplace --skill idp-validate-token-overlens
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: idp-validate-token
Source: https://github.com/overlens/claude-marketplace/tree/main/plugins/idp-integration/skills/idp-validate-token
Command: npx skills add https://github.com/overlens/claude-marketplace --skill idp-validate-token-overlens

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires passport, passport-jwt, jwks-rsa, cookie-parser, @nestjs/passport, and includes references (resource) components.

What problem does it solve? Backend APIs that receive requests carrying an Overlens IDP access token need to verify that JWT locally — without calling the IDP on every request. This Skill provides the decision logic, security rules, and copy-paste templates to build that token-validation layer correctly, avoiding common mistakes like accepting HS256, skipping audience checks, or fetching the JWKS per request. ## Core Features & Use Cases - Copy-paste validation templates: NestJS JwtStrategy with Bearer+cookie extraction, RS256 pinning, and iss/aud validation, plus JwtAuthGuard, RequireRole, RequireScope, and a @CurrentPrincipal() decorator, and a single-file Express middleware. - User vs M2M discrimination: Builds a typed Principal that tells user tokens (authorize by role) apart from service tokens (authorize by scope) using the client_id/email claim rule. - Security guidance: Explains why RS256 pinning stops algorithm-confusion attacks, how JWKS caching and key rotation work, and why you must never poll the IDP per request. - Use Case: You are adding a JwtAuthGuard to a NestJS API so that requests with an Overlens Bearer token or access_token cookie get a typed req.user principal, with admin routes gated by role and service routes gated by scope. ## Quick Start Ask the assistant to add Overlens JWT validation with a JwtAuthGuard and req.user principal to your NestJS or Express API.

Frequently Asked Questions about idp-validate-token

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I validate an Overlens JWT in a NestJS backend?

Use the provided JwtStrategy template with passport-jwt and jwks-rsa: it fetches and caches the JWKS public key for one hour, pins algorithms to RS256, validates issuer and audience, and extracts the token from the Bearer header or access_token cookie. Protect routes with the JwtAuthGuard template.

How do I get req.user from an Overlens access token?

After the JWT is verified, the validate() method shapes the payload into a typed Principal: a user object with id, email, and role, or a service object with clientId and scopes. Inject it into handlers with the @CurrentPrincipal() decorator or read req.user in Express.

Can I validate Overlens tokens in FastAPI or Spring Boot?

Yes, the contract is identical across frameworks. FastAPI uses PyJWKClient with jwt.decode pinned to RS256, and Spring Boot uses spring-boot-starter-oauth2-resource-server pointed at the issuer URI. The references/other-frameworks.md file includes working snippets for Fastify, Hono, FastAPI, and Spring.

Why must I pin RS256 and never accept HS256?

Accepting HS256 enables the algorithm-confusion attack: an attacker uses the public JWKS key as an HMAC secret to forge tokens that pass verification. The IDP only ever issues RS256, so pinning algorithms: ['RS256'] closes the hole at no cost.

Should my API call the IDP to check if a user is blocked?

No. Blocked users cannot refresh, but their current access token stays valid until expiry (at most 15 minutes), and there is no global blocklist. Per-request IDP calls add latency and a cascading-failure dependency; use a local block cache fed by events if instant revocation is truly required.

Why does my M2M service get a 403 on a role-protected endpoint?

Service tokens carry client_id and scope but no role claim, so a role check fails closed by design. Authorize machine-to-machine callers with the RequireScope guard against their space-separated scope claim instead of RequireRole.