mirror of https://github.com/dexidp/dex.git
kt
1 month ago
committed by
GitHub
1 changed files with 283 additions and 0 deletions
@ -0,0 +1,283 @@ |
|||||||
|
# Dex Enhancement Proposal (DEP) 4600 - 2026-03-02 - Identity Assertion JWT Authorization Grant (ID-JAG) |
||||||
|
|
||||||
|
## Table of Contents |
||||||
|
|
||||||
|
- [Dex Enhancement Proposal (DEP) 4600 - 2026-03-02 - Identity Assertion JWT Authorization Grant (ID-JAG)](#dex-enhancement-proposal-dep-4600---2026-03-02---identity-assertion-jwt-authorization-grant-id-jag) |
||||||
|
- [Table of Contents](#table-of-contents) |
||||||
|
- [Summary](#summary) |
||||||
|
- [Context](#context) |
||||||
|
- [Motivation](#motivation) |
||||||
|
- [Goals/Pain](#goalspain) |
||||||
|
- [Non-goals](#non-goals) |
||||||
|
- [Proposal](#proposal) |
||||||
|
- [User Experience](#user-experience) |
||||||
|
- [Implementation Details/Notes/Constraints](#implementation-detailsnotesconstraints) |
||||||
|
- [Observability](#observability) |
||||||
|
- [Risks and Mitigations](#risks-and-mitigations) |
||||||
|
- [Alternatives](#alternatives) |
||||||
|
- [Future Improvements](#future-improvements) |
||||||
|
|
||||||
|
## Summary |
||||||
|
|
||||||
|
[draft-ietf-oauth-identity-assertion-authz-grant-02] specifies a mechanism |
||||||
|
for an application to use an identity assertion to obtain an access token |
||||||
|
for a third-party API by coordinating through a common enterprise identity |
||||||
|
provider using Token Exchange [RFC 8693] and JWT Profile for OAuth 2.0 |
||||||
|
Authorization Grants [RFC 7523]. |
||||||
|
|
||||||
|
This DEP proposes to extend Dex's existing Token Exchange implementation |
||||||
|
to support issuing Identity Assertion JWT Authorization Grants (ID-JAGs), |
||||||
|
enabling cross-domain access managed by the enterprise IdP. |
||||||
|
|
||||||
|
[draft-ietf-oauth-identity-assertion-authz-grant-02]: https://datatracker.ietf.org/doc/draft-ietf-oauth-identity-assertion-authz-grant/ |
||||||
|
|
||||||
|
## Context |
||||||
|
|
||||||
|
- [#2812 DEP for RFC 8693 OAuth 2 Token Exchange] |
||||||
|
established the Token Exchange foundation that ID-JAG builds upon. |
||||||
|
- [draft-ietf-oauth-identity-assertion-authz-grant-02] |
||||||
|
is the IETF Standards Track specification this DEP implements. |
||||||
|
- [draft-ietf-oauth-identity-chaining] |
||||||
|
is the broader identity chaining specification that ID-JAG profiles. |
||||||
|
|
||||||
|
The specification is authored by A. Parecki (Okta), K. McGuinness, and |
||||||
|
B. Campbell (Ping Identity). It is actively being developed within the |
||||||
|
IETF OAuth Working Group. |
||||||
|
|
||||||
|
Use cases: |
||||||
|
|
||||||
|
- LLM agents accessing enterprise APIs on behalf of users (Appendix A.3 of the spec) |
||||||
|
- Enterprise applications embedding content from third-party apps |
||||||
|
- Email/calendaring applications accessing cross-domain resources |
||||||
|
|
||||||
|
Real-world adoption: |
||||||
|
|
||||||
|
- [Okta Cross App Access] is GA, implementing ID-JAG for SaaS-to-SaaS and |
||||||
|
AI agent scenarios with a developer tutorial available. |
||||||
|
- [Okta AI Agent Token Exchange] (Early Access) uses ID-JAG for AI agents |
||||||
|
accessing enterprise APIs on behalf of authenticated users. |
||||||
|
- [Keycloak #43971] tracks ID-JAG support as a feature request. |
||||||
|
- The upcoming MCP (Model Context Protocol) specification references ID-JAG |
||||||
|
for AI agent authorization flows. |
||||||
|
|
||||||
|
[#2812 DEP for RFC 8693 OAuth 2 Token Exchange]: https://github.com/dexidp/dex/pull/2812 |
||||||
|
[draft-ietf-oauth-identity-chaining]: https://datatracker.ietf.org/doc/draft-ietf-oauth-identity-chaining/ |
||||||
|
[Okta Cross App Access]: https://developer.okta.com/blog/2026/02/10/xaa-client |
||||||
|
[Okta AI Agent Token Exchange]: https://developer.okta.com/docs/guides/ai-agent-token-exchange/authserver/main/ |
||||||
|
[Keycloak #43971]: https://github.com/keycloak/keycloak/issues/43971 |
||||||
|
|
||||||
|
## Motivation |
||||||
|
|
||||||
|
### Goals/Pain |
||||||
|
|
||||||
|
In enterprise environments, applications are configured for SSO through |
||||||
|
a common IdP. When one application needs to access a user's data at another |
||||||
|
application, the current approach requires either: |
||||||
|
|
||||||
|
1. A direct OAuth flow between apps (bypassing the IdP's visibility and policy) |
||||||
|
2. Static API keys or service accounts (security risk) |
||||||
|
|
||||||
|
ID-JAG solves this by letting the IdP broker cross-domain access, maintaining |
||||||
|
visibility and policy control. |
||||||
|
|
||||||
|
**Specific goals:** |
||||||
|
|
||||||
|
- Issue ID-JAG tokens via Token Exchange (`requested_token_type=urn:ietf:params:oauth:token-type:id-jag`) |
||||||
|
- Support `audience` and `resource` parameters per the specification |
||||||
|
- Validate subject token audience against requesting client |
||||||
|
- Support configurable policy evaluation for token exchange requests |
||||||
|
|
||||||
|
### Non-goals |
||||||
|
|
||||||
|
- Implementing the Resource Authorization Server role (JWT Bearer Grant / RFC 7523) |
||||||
|
is out of scope for this initial DEP. It may be addressed in a follow-up. |
||||||
|
- SAML assertion support as `subject_token_type` is deferred. |
||||||
|
- Step-up authentication flow is deferred. |
||||||
|
|
||||||
|
## Proposal |
||||||
|
|
||||||
|
### User Experience |
||||||
|
|
||||||
|
End-to-end flow: |
||||||
|
|
||||||
|
```mermaid |
||||||
|
sequenceDiagram |
||||||
|
participant C as Client (Wiki App) |
||||||
|
participant Dex as Dex (IdP AS) |
||||||
|
participant RAS as Resource AS (Chat AS) |
||||||
|
participant RS as Resource Server (Chat API) |
||||||
|
|
||||||
|
C->>Dex: 1. OIDC Authentication (authorization_code flow) |
||||||
|
Dex-->>C: ID Token + optional Refresh Token |
||||||
|
|
||||||
|
C->>Dex: 2. Token Exchange (grant_type=token-exchange)<br/>subject_token=ID Token<br/>requested_token_type=id-jag<br/>audience=https://acme.chat.example/<br/>connector_id=google |
||||||
|
Note over Dex: Validate subject_token aud == client_id<br/>Evaluate policy (clientID → allowed audiences)<br/>Issue ID-JAG JWT (typ: oauth-id-jag+jwt) |
||||||
|
Dex-->>C: ID-JAG (access_token, token_type=N_A, expires_in=300) |
||||||
|
|
||||||
|
C->>RAS: 3. JWT Bearer Grant (RFC 7523)<br/>grant_type=jwt-bearer, assertion=ID-JAG |
||||||
|
Note over RAS: Validate ID-JAG signature (Dex JWKS)<br/>Validate aud == RAS issuer<br/>Issue access token |
||||||
|
RAS-->>C: Access Token |
||||||
|
|
||||||
|
C->>RS: 4. API Request with Access Token |
||||||
|
RS-->>C: Protected Resource |
||||||
|
``` |
||||||
|
|
||||||
|
Clients can request ID-JAG tokens from Dex's `/token` endpoint by specifying |
||||||
|
`requested_token_type=urn:ietf:params:oauth:token-type:id-jag` in a |
||||||
|
Token Exchange request. ID-JAG support is enabled by adding |
||||||
|
`urn:ietf:params:oauth:token-type:id-jag` to `oauth2.tokenExchange.tokenTypes`. |
||||||
|
When not listed, requests with this `requested_token_type` are rejected, |
||||||
|
ensuring no change in behavior for existing deployments. |
||||||
|
|
||||||
|
The request parameters (extending existing Token Exchange): |
||||||
|
|
||||||
|
- `grant_type`: REQUIRED - `urn:ietf:params:oauth:grant-type:token-exchange` |
||||||
|
- `subject_token`: REQUIRED - the identity assertion (OpenID Connect ID Token) |
||||||
|
- `subject_token_type`: REQUIRED - `urn:ietf:params:oauth:token-type:id_token`. |
||||||
|
SAML 2.0 (`urn:ietf:params:oauth:token-type:saml2`) is deferred (see Non-goals). |
||||||
|
- `requested_token_type`: REQUIRED - `urn:ietf:params:oauth:token-type:id-jag` |
||||||
|
- `audience`: REQUIRED - the Issuer URL of the Resource Authorization Server. |
||||||
|
**Note**: The existing Token Exchange implementation uses a Dex-specific `connector_id` |
||||||
|
parameter (not part of RFC 8693) for connector selection. The `audience` parameter was |
||||||
|
not used in the current implementation despite DEP #2812 originally proposing it for |
||||||
|
connector identification. ID-JAG introduces `audience` with its standard RFC 8693 |
||||||
|
meaning (target Resource AS). This is purely additive and does not affect existing |
||||||
|
Token Exchange requests. |
||||||
|
- `connector_id`: REQUIRED (Dex extension) - the ID of the Dex connector to verify the |
||||||
|
subject token against. The connector validates the token (issuer, signature, etc.), |
||||||
|
so a mismatched token is rejected. This parameter already exists in the current |
||||||
|
Token Exchange implementation and is reused as-is. |
||||||
|
- `resource`: OPTIONAL - the Resource Identifier of the Resource Server |
||||||
|
- `scope`: OPTIONAL - the requested scopes at the Resource Server |
||||||
|
|
||||||
|
The response: |
||||||
|
|
||||||
|
- `access_token`: the ID-JAG JWT (named `access_token` for RFC 8693 compatibility) |
||||||
|
- `issued_token_type`: `urn:ietf:params:oauth:token-type:id-jag` |
||||||
|
- `token_type`: `N_A` (this is not an OAuth access token) |
||||||
|
- `expires_in`: lifetime in seconds (default: 300, configurable independently of ID token |
||||||
|
lifetime via `expiry.idJAGTokens`) |
||||||
|
- `scope`: OPTIONAL if the issued scope is identical to the requested scope; REQUIRED |
||||||
|
otherwise. Per Section 4.3.2 of the specification, policy evaluation at the IdP may |
||||||
|
result in different scopes being issued than were requested. |
||||||
|
|
||||||
|
Complete configuration example: |
||||||
|
|
||||||
|
```yaml |
||||||
|
oauth2: |
||||||
|
grantTypes: |
||||||
|
- authorization_code |
||||||
|
- urn:ietf:params:oauth:grant-type:token-exchange |
||||||
|
tokenExchange: |
||||||
|
# List of token types enabled for exchange. Adding id-jag enables ID-JAG support. |
||||||
|
# Omitting it (default) disables ID-JAG without affecting other token exchange flows. |
||||||
|
# SAML2 (urn:ietf:params:oauth:token-type:saml2) may be added in a future release. |
||||||
|
tokenTypes: |
||||||
|
- urn:ietf:params:oauth:token-type:id_token |
||||||
|
- urn:ietf:params:oauth:token-type:id-jag |
||||||
|
|
||||||
|
expiry: |
||||||
|
idTokens: "24h" |
||||||
|
idJAGTokens: "5m" # default: 5m; independent of idTokens |
||||||
|
|
||||||
|
staticClients: |
||||||
|
- id: wiki-app |
||||||
|
name: "Wiki Application" |
||||||
|
secret: "wiki-secret" |
||||||
|
redirectURIs: |
||||||
|
- "https://wiki.example/callback" |
||||||
|
# Per-client ID-JAG policy. Clients without this section cannot obtain ID-JAG tokens |
||||||
|
# (default-deny). Only audiences and scopes listed here may be requested. |
||||||
|
idJAGPolicies: |
||||||
|
allowedAudiences: |
||||||
|
- "https://chat.example/" |
||||||
|
- "https://calendar.example/" |
||||||
|
allowedScopes: |
||||||
|
- "chat.read" |
||||||
|
- "calendar.read" |
||||||
|
|
||||||
|
- id: supermarket-app |
||||||
|
name: "Supermarket Application" |
||||||
|
secret: "supermarket-secret" |
||||||
|
redirectURIs: |
||||||
|
- "https://supermarket.example/callback" |
||||||
|
idJAGPolicies: |
||||||
|
allowedAudiences: |
||||||
|
- "https://grocery.store.1/" |
||||||
|
- "https://grocery.store.2/" |
||||||
|
allowedScopes: |
||||||
|
- "eat.bananas" |
||||||
|
- "eat.apples" |
||||||
|
``` |
||||||
|
|
||||||
|
### Implementation Details/Notes/Constraints |
||||||
|
|
||||||
|
- A new `id-jag` branch is added to the existing Token Exchange flow, issuing a signed JWT |
||||||
|
per Section 3 of the specification (header `typ: "oauth-id-jag+jwt"`, claims including |
||||||
|
`iss`, `sub`, `aud`, `client_id`, `jti`, `exp`, `iat`). |
||||||
|
|
||||||
|
- Per-client `idJAGPolicies` in `staticClients` control which audiences and scopes a |
||||||
|
given client may request in an ID-JAG. Clients without `idJAGPolicies` are denied |
||||||
|
by default. Dynamically registered clients are currently unsupported for ID-JAG policies; |
||||||
|
support via CEL expressions (building on the CEL infrastructure from #4601) is future work. |
||||||
|
|
||||||
|
- OIDC discovery is extended with `identity_chaining_requested_token_types_supported` per |
||||||
|
Section 7 of the specification. When ID-JAG is enabled, Dex includes |
||||||
|
`urn:ietf:params:oauth:token-type:id-jag` in this metadata property. |
||||||
|
|
||||||
|
- ID-JAG support is enabled by listing `urn:ietf:params:oauth:token-type:id-jag` in |
||||||
|
`oauth2.tokenExchange.tokenTypes`. When not listed (default), requests are rejected, |
||||||
|
ensuring no change in behavior for existing deployments. |
||||||
|
|
||||||
|
### Observability |
||||||
|
|
||||||
|
- Every ID-JAG token exchange request (issued or rejected) emits a structured log entry |
||||||
|
with `client_id`, `connector_id`, `audience`, `resource` (if present), requested and |
||||||
|
granted `scope` (these may differ after policy evaluation), `sub`, `jti` (if issued), |
||||||
|
and the policy decision (`approved`/`denied` with reason like `audience_not_allowed` |
||||||
|
or `client_has_no_policy`). |
||||||
|
|
||||||
|
- The following Prometheus counters are exposed: |
||||||
|
- `dex_id_jag_requests_total` (labels: `result`) — issued vs rejected |
||||||
|
- `dex_id_jag_policy_rejections_total` (labels: `reason`) — |
||||||
|
breakdown by denial reason, useful for spotting misconfigurations or abuse |
||||||
|
- `dex_id_jag_scope_modifications_total` — cases where policy reduced the requested scopes |
||||||
|
|
||||||
|
### Risks and Mitigations |
||||||
|
|
||||||
|
- **Lateral movement risk**: Same as existing Token Exchange. Mitigated by |
||||||
|
not issuing refresh tokens, short expiry (5 min recommended), and |
||||||
|
policy-based audience restrictions. |
||||||
|
- **Token confusion**: The `typ: "oauth-id-jag+jwt"` header and distinct |
||||||
|
`issued_token_type` prevent confusion with ID Tokens or access tokens. |
||||||
|
- **Replay attack risk**: Server-side `jti` tracking is deferred, so a stolen ID-JAG |
||||||
|
can be replayed within its 5-minute lifetime. Short `expires_in` is the only Dex-side |
||||||
|
mitigation; Resource Authorization Servers should implement `jti` caching independently. |
||||||
|
- **Public client misuse**: Per Section 8.1 of the specification, ID-JAG SHOULD only be |
||||||
|
used by confidential clients. Public clients should use the standard authorization code |
||||||
|
flow with interactive user consent at the Resource Authorization Server. Dex will enforce |
||||||
|
this by rejecting ID-JAG requests from public clients (clients without a secret). |
||||||
|
- **Breaking changes**: None. This is purely additive to the existing |
||||||
|
Token Exchange implementation. The `audience` parameter is newly introduced |
||||||
|
(not previously used in the implementation despite DEP #2812's original proposal), |
||||||
|
and `connector_id` already exists. |
||||||
|
|
||||||
|
### Alternatives |
||||||
|
|
||||||
|
- **Wait for spec finalization**: The draft is Standards Track and stable enough |
||||||
|
to implement. Okta and Ping Identity (the spec authors) already ship implementations, |
||||||
|
and the spec has been adopted by the IETF OAuth WG. |
||||||
|
- **External policy engine (OPA/CEL)**: Config-based policies are sufficient for now. |
||||||
|
The CEL infrastructure (#4601) is merged; ID-JAG policy evaluation via CEL is future work. |
||||||
|
|
||||||
|
## Future Improvements |
||||||
|
|
||||||
|
- Resource Authorization Server role (JWT Bearer Grant / RFC 7523) |
||||||
|
accepting ID-JAGs from external IdPs |
||||||
|
- SAML 2.0 assertion support as `subject_token_type` |
||||||
|
(`urn:ietf:params:oauth:token-type:saml2`) |
||||||
|
- CEL-based ID-JAG policy evaluation (building on #4601) enabling dynamic policies for |
||||||
|
DB-managed clients, including runtime policy changes without restart |
||||||
|
- Step-up authentication when authentication context is insufficient |
||||||
|
- `actor_token` support for delegation scenarios |
||||||
|
- Server-side `jti` tracking to prevent ID-JAG replay attacks |
||||||
Loading…
Reference in new issue