# Jwt 403 Debug Expert

> Diagnose 401/403 responses at the AI Citadel APIM gateway — decode JWT claims, verify Access Contract scope grants, and validate Foundry managed-identity token audience.

- **Type:** Skill
- **Install:** `agentstack add skill-aiappsgbb-awesome-gbb-jwt-403-debug-expert`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [aiappsgbb](https://agentstack.voostack.com/s/aiappsgbb)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [aiappsgbb](https://github.com/aiappsgbb)
- **Source:** https://github.com/aiappsgbb/awesome-gbb/tree/main/skills/azure-sre-agent/references/plugins/gbb-citadel/skills/jwt_403_debug_expert

## Install

```sh
agentstack add skill-aiappsgbb-awesome-gbb-jwt-403-debug-expert
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# jwt_403_debug_expert

## When to use

The SRE Agent should invoke this skill when:

- A user reports a 401 or 403 from the Citadel gateway
- A hosted agent's BYOK call returns "Authentication failed with provider … (HTTP 401)" but the underlying provider is the Citadel-routed AOAI
- After running `citadel-spoke-onboarding`, the new spoke can't reach the gateway

## Investigation flow

1. **Get the correlation ID** of the failing request from the user or from
   the application's logs.

2. **Pull the request from APIM diagnostics**:
   ```kql
   ApiManagementGatewayLogs
   | where TimeGenerated > ago(2h)
   | where CorrelationId == ""
   | project TimeGenerated, OperationId, ApiId, ProductId, ResponseCode, BackendStatusReason, LastErrorReason, RequestHeaders, ResponseHeaders
   ```

3. **Decode the JWT** if present (claims only — NEVER the signature):
   - `aud` — must match the gateway URL configured in the Access Contract
   - `iss` — must be `https://login.microsoftonline.com//v2.0`
   - `oid` — the calling principal's object ID
   - `scp` / `roles` — must include the operation scope (e.g. `llm:read`)
   - `exp` — must not be in the past

4. **Match against the Access Contract**:

   | Symptom | Root cause | Fix |
   |---|---|---|
   | `aud` mismatch | Token issued for wrong audience | Re-issue token with correct audience |
   | Missing scope claim | Access Contract didn't grant this scope | Re-run citadel-spoke-onboarding with the needed scope in `gbb_access_contracts` |
   | `exp` in past | Token expired (default ~1h for MI) | Refresh; check caller's token-cache TTL |
   | No `Authorization` header | Caller using product-key path but no key | Set `Ocp-Apim-Subscription-Key` or switch to JWT |
   | 403 with valid JWT | Per-product policy denies | Check `rate-limit-by-key` and product subscription state |

5. **Output**: classification, root cause hypothesis, ONE recommended fix
   and ONE verification step.

## Tools

This skill uses:
- `RunAzCliReadCommands`
- `QueryLogAnalyticsByWorkspaceId`

## Safety

- NEVER display the JWT signature, named-value contents, or any signing material
- Refer to credentials by resource name only (e.g. "Foundry MI on project `aifp-pilot`")
- Read-only investigation; any RBAC change requires human action

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [aiappsgbb](https://github.com/aiappsgbb)
- **Source:** [aiappsgbb/awesome-gbb](https://github.com/aiappsgbb/awesome-gbb)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-aiappsgbb-awesome-gbb-jwt-403-debug-expert
- Seller: https://agentstack.voostack.com/s/aiappsgbb
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.