Skip to content

Commit 6515c9a

Browse files
committed
docs: add RFC references for AuthBridge security standards
Add offline copies of RFCs that define the token exchange flow: - RFC 7515 (JWS), RFC 7519 (JWT), RFC 8693 (Token Exchange), RFC 8705 (mTLS Client Auth), RFC 9068 (JWT Access Token Profile) Also: - Add RFC summary table to CLAUDE.md - Exclude zt-monitor/ and docs/ from CI build triggers Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com>
1 parent f571ce3 commit 6515c9a

File tree

8 files changed

+10526
-0
lines changed

8 files changed

+10526
-0
lines changed

.github/workflows/build-push.yaml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ on:
1010
- "go.sum"
1111
- "opa-service/policies/**"
1212
- ".github/workflows/build-push.yaml"
13+
- "!zt-monitor/**"
14+
- "!docs/**"
1315

1416
env:
1517
REGISTRY: ghcr.io

CLAUDE.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -252,6 +252,19 @@ Common flags:
252252
- **SPIFFE/SPIRE** - Workload identity (mock mode for local dev)
253253
- **SSE (Server-Sent Events)** - Real-time dashboard updates
254254

255+
## Security Standards (RFCs)
256+
257+
The AuthBridge token exchange flow is built on these standards
258+
(offline copies in `docs/references/`):
259+
260+
| RFC | Title | Used for |
261+
| --- | ----- | -------- |
262+
| RFC 7515 | JSON Web Signature (JWS) | JWT signature verification via JWKS |
263+
| RFC 7519 | JSON Web Token (JWT) | Access token format (Keycloak-issued) |
264+
| RFC 8693 | OAuth 2.0 Token Exchange | Ext-proc token swap between services |
265+
| RFC 8705 | OAuth 2.0 Mutual-TLS | SPIFFE SVID client authentication |
266+
| RFC 9068 | JWT Profile for Access Tokens | Standardized JWT access token structure |
267+
255268
## Development Notes
256269

257270
### Adding a New Document

docs/references/README.md

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# RFC References
2+
3+
This directory contains offline copies of RFCs that define the security
4+
standards used in this project's AuthBridge token exchange flow.
5+
6+
## RFCs
7+
8+
| RFC | Title | Relevance |
9+
| --- | ----- | --------- |
10+
| [RFC 7515](rfc7515.html) | JSON Web Signature (JWS) | Foundation for JWT signature verification; used by `pkg/auth/jwt.go` to validate access tokens via JWKS |
11+
| [RFC 7519](rfc7519.html) | JSON Web Token (JWT) | Core token format for access tokens issued by Keycloak; claims structure used throughout the demo |
12+
| [RFC 8693](rfc8693.xml) | OAuth 2.0 Token Exchange | Defines the token exchange grant type used by AuthBridge's ext-proc to swap tokens between services |
13+
| [RFC 8705](rfc8705.xml) | OAuth 2.0 Mutual-TLS Client Authentication | mTLS-based client authentication; relates to SPIFFE X509-SVIDs used as client certificates |
14+
| [RFC 9068](rfc9068.xml) | JWT Profile for OAuth 2.0 Access Tokens | Standardizes JWT access token format; Keycloak issues tokens following this profile |
15+
16+
## How these RFCs fit together
17+
18+
The AuthBridge flow uses these standards in sequence:
19+
20+
1. A user authenticates with Keycloak and receives a **JWT access token**
21+
(RFC 7519, RFC 9068)
22+
2. The token is **signed** using JWS (RFC 7515); services verify signatures
23+
via Keycloak's JWKS endpoint
24+
3. When a service calls another service, the Envoy ext-proc performs
25+
**token exchange** (RFC 8693) to obtain a new token scoped to the
26+
target service's audience
27+
4. Services authenticate to Keycloak using **mTLS with SPIFFE SVIDs**
28+
as client certificates (RFC 8705)

docs/references/rfc7515.html

Lines changed: 3467 additions & 0 deletions
Large diffs are not rendered by default.

docs/references/rfc7519.html

Lines changed: 1843 additions & 0 deletions
Large diffs are not rendered by default.

docs/references/rfc8693.xml

Lines changed: 2050 additions & 0 deletions
Large diffs are not rendered by default.

docs/references/rfc8705.xml

Lines changed: 1980 additions & 0 deletions
Large diffs are not rendered by default.

docs/references/rfc9068.xml

Lines changed: 1143 additions & 0 deletions
Large diffs are not rendered by default.

0 commit comments

Comments
 (0)