authz-server

Explains PingOne Authorization Server architecture, decision API, and policy rules for MCP tool calls.

1|Updated Jun 25, 2026
One-click install
npx skills add https://github.com/curtismu7/AI-DEMO2 --skill authz-server-curtismu7
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: authz-server
Source: https://github.com/curtismu7/AI-DEMO2/tree/main/pingone/authz-server
Command: npx skills add https://github.com/curtismu7/AI-DEMO2 --skill authz-server-curtismu7

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Understanding how authorization decisions are made for MCP tool calls in this banking demo is difficult because logic is spread across the gateway, the authorization server, and PingOne. This Skill documents the full architecture, API surface, and rule evaluation order so you can configure, debug, or swap in real PingOne Authorize without reading all the source code. ## Core Features & Use Cases - Architecture Reference: Maps the three-server flow (BFF, MCP Gateway, Authorization Server) and explains how RFC 8693 token exchange and the act claim are enforced. - API Documentation: Covers the introspection endpoint (RFC 7662), the PingOne Authorize decision endpoint, token endpoint, and runtime rule-store management endpoints. - Policy Rule Walkthrough: Details the ordered authorization rules including scope checks, act claim validation, deny ceilings, RAR, entitlement tiers, and two-tier HITL (step-up vs. consent). - Use Case: When a tool call is unexpectedly denied, use this Skill to trace which rule fired, check the decision logs, and adjust thresholds like SIMULATED_AUTHORIZE_STEPUP_AMOUNT or the runtime rule overlay. ## Quick Start Ask the AI to explain why a specific MCP tool call was denied by the authorization server and which rule or configuration value caused the decision.

Frequently Asked Questions about authz-server

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

FAQPage Schema
How do I configure the MCP gateway to use the authorization server?▼

Set PINGAUTHORIZE_ENDPOINT to the authz server URL, PINGAUTHORIZE_WORKER_ID to any policy ID, and MCP_GW_P1AZ_ENABLED=true in demo_mcp_gateway/.env. Without these, the gateway fails closed and denies tools/list and most other methods.

Why was my MCP tool call denied by the authorization server?▼

Denials follow an ordered rule set in decision.js: act claim mismatch, missing required scopes, transaction amount above the deny ceiling (default 2000), or failed ownership and group checks. Check /tmp/demo-authorize.log for the decision line showing the tool, scopes, and reason.

How does step-up authentication differ from HITL consent in PingOne Authorize?▼

Amounts at or above SIMULATED_AUTHORIZE_STEPUP_AMOUNT (default 500) return INDETERMINATE with reason STEP_UP, requiring re-authentication. Amounts at or above the confirm threshold (default 250) return HITL_CONSENT, which is discharged when HitlApproved is true.

Can I switch from the mock authorization server to real PingOne Authorize?▼

Yes. Point PINGAUTHORIZE_ENDPOINT to https://authorize.pingone.com/<envId>, set a real worker ID, and keep MCP_GW_P1AZ_ENABLED=true. The gateway already uses the PingOne Authorize API format, so no code changes are needed.

Why does token introspection return active:false for my exchanged token?▼

GW_INTROSPECTION_CLIENT_ID must be the MCP Exchanger client that issued the gateway-audience token. PingOne only returns active:true for the issuing client or a client in the token audience; using the management Worker causes active:false and reauth loops.