idp-auth-guide

Implements OAuth 2.1 and OIDC authentication flows against the Overlens Identity Provider.

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

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Integrating user authentication with the Overlens Identity Provider requires correctly implementing OAuth 2.1 with PKCE, token exchange, JWT validation, refresh rotation, and logout — a process with many failure points like exact redirect_uri matching, S256 code challenges, and cookie maxAge unit bugs. This Skill provides the complete framework-agnostic integration guide plus endpoint contracts, security rules, and troubleshooting references so the integration is done correctly the first time. ## Core Features & Use Cases - Full OAuth 2.1 + PKCE flow guidance: Step-by-step instructions for authorization code flow, token exchange, id_token validation via JWKS, refresh token rotation, and OIDC RP-initiated logout. - Complete endpoint reference: Request/response contracts for every IDP endpoint (authorize, token, signup, userinfo, logout, JWKS, OIDC discovery) in references/endpoints.md. - Security rules and troubleshooting: Non-negotiable rules (RS256 only, SameSite=Lax, PKCE mandatory) and diagnostics for common errors like invalid_client, PKCE validation failures, and disappearing cookies. - Use Case: You are adding Overlens SSO login to a custom web app that is not Next.js or Vite+BFF. This Skill walks through PKCE generation, the authorize redirect, callback handling, secure token storage, silent refresh, and logout, then points you to the conformance test suite to prove correctness. ## Quick Start Ask the assistant to integrate Overlens IDP login into your application and it will guide you through the OAuth 2.1 PKCE flow step by step.

Frequently Asked Questions about idp-auth-guide

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

FAQPage Schema
How do I integrate OAuth 2.1 login with the Overlens IDP?

Generate a PKCE code_verifier and S256 code_challenge, redirect the user to /auth/authorize with your client_id and registered redirect_uri, then exchange the returned authorization code at /auth/token. Validate the id_token using the public key from /.well-known/jwks.json.

How do I validate JWT tokens from the Overlens Identity Provider?

Fetch the public key from https://idp.overlens.com.br/.well-known/jwks.json and verify the RS256 signature, issuer, audience, and expiration. Most JWT libraries do this automatically when given the JWKS URL and expected issuer and audience.

Does the Overlens IDP support OIDC discovery for automatic configuration?

Yes, the IDP exposes a standard discovery document at /.well-known/openid-configuration listing all endpoints, scopes, grant types, and signing algorithms. Any OIDC-compatible library can auto-configure by pointing at that URL.

Why does my PKCE validation fail during token exchange?

PKCE validation fails when the code_verifier does not match the code_challenge sent during authorization. Ensure the challenge is BASE64URL(SHA256(verifier)) with no padding, the method is S256, and you reuse the same verifier stored from the authorize step.

Why do my auth cookies disappear immediately after login?

This is almost always a maxAge unit bug: Express and NestJS expect milliseconds, so maxAge: 900 becomes Max-Age=0 and deletes the cookie. Use maxAge: 900_000 for a 15-minute access token cookie.

When should I use this guide instead of the Next.js or Vite skills?

Use this framework-agnostic guide for any stack other than Next.js or Vite with a separate backend, which have dedicated skills (idp-auth-nextjs and idp-auth-vite-bff). For pure backend token validation, use idp-validate-token instead.