Phil Skentelbery
cbef0c1561
The token exchange request was missing the required grant_type parameter per OAuth 2.0 RFC 6749. IndieAuth providers that properly validate this were rejecting the request with a 422 error. - Add grant_type=authorization_code to token exchange data - Add ADR-022 documenting the spec compliance requirement 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
84 lines
3.6 KiB
Markdown
84 lines
3.6 KiB
Markdown
# ADR-022: IndieAuth Token Exchange Compliance
|
|
|
|
## Status
|
|
Accepted
|
|
|
|
## Context
|
|
StarPunk's IndieAuth implementation is failing to authenticate with certain providers (specifically gondulf.thesatelliteoflove.com) during the token exchange phase. The provider is rejecting our token exchange requests with a "missing grant_type" error.
|
|
|
|
Our current implementation sends:
|
|
- `code`
|
|
- `client_id`
|
|
- `redirect_uri`
|
|
- `code_verifier` (for PKCE)
|
|
|
|
But does NOT include `grant_type=authorization_code`.
|
|
|
|
## Decision
|
|
StarPunk MUST include `grant_type=authorization_code` in all token exchange requests to be compliant with both OAuth 2.0 RFC 6749 and IndieAuth specifications.
|
|
|
|
## Rationale
|
|
|
|
### OAuth 2.0 RFC 6749 Compliance
|
|
RFC 6749 Section 4.1.3 explicitly states that `grant_type` is a REQUIRED parameter with the value MUST be set to "authorization_code" for the authorization code grant flow.
|
|
|
|
### IndieAuth Specification
|
|
While the IndieAuth specification (W3C TR) doesn't use explicit RFC 2119 language (MUST/REQUIRED) for the grant_type parameter, it:
|
|
1. Lists `grant_type=authorization_code` as part of the token request parameters in Section 6.3.1
|
|
2. Shows it in all examples (Example 12)
|
|
3. States that IndieAuth "builds upon the OAuth 2.0 [RFC6749] Framework"
|
|
|
|
Since IndieAuth builds on OAuth 2.0, and OAuth 2.0 requires this parameter, IndieAuth implementations should include it.
|
|
|
|
### Provider Compliance
|
|
The provider (gondulf.thesatelliteoflove.com) is **correctly following the specifications** by requiring the `grant_type` parameter.
|
|
|
|
## Consequences
|
|
|
|
### Positive
|
|
- Full compliance with OAuth 2.0 RFC 6749
|
|
- Compatibility with all spec-compliant IndieAuth providers
|
|
- Clear, standard-compliant token exchange requests
|
|
|
|
### Negative
|
|
- Requires immediate code change to add the missing parameter
|
|
- May reveal other non-compliant providers that don't check for this parameter
|
|
|
|
## Implementation Requirements
|
|
|
|
The token exchange request MUST include these parameters:
|
|
```
|
|
grant_type=authorization_code # REQUIRED by OAuth 2.0
|
|
code={authorization_code} # REQUIRED
|
|
client_id={client_url} # REQUIRED
|
|
redirect_uri={redirect_url} # REQUIRED if used in initial request
|
|
me={user_profile_url} # REQUIRED by IndieAuth (extension to OAuth)
|
|
```
|
|
|
|
### Note on PKCE
|
|
The `code_verifier` parameter currently being sent is NOT part of the IndieAuth specification. IndieAuth does not mention PKCE (RFC 7636) support. However:
|
|
- Including it shouldn't break compliant providers (they should ignore unknown parameters)
|
|
- It provides additional security for public clients
|
|
- Consider making PKCE optional or detecting provider support
|
|
|
|
## Alternatives Considered
|
|
|
|
### Alternative 1: Argue for Optional grant_type
|
|
**Rejected**: While IndieAuth could theoretically make grant_type optional since there's only one grant type, this would break compatibility with OAuth 2.0 compliant libraries and providers.
|
|
|
|
### Alternative 2: Provider-specific workarounds
|
|
**Rejected**: Creating provider-specific code paths would violate the principle of standards compliance and create maintenance burden.
|
|
|
|
## Recommendation
|
|
|
|
**Immediate Action Required**:
|
|
1. Add `grant_type=authorization_code` to all token exchange requests
|
|
2. Maintain the existing parameters
|
|
3. Consider making PKCE optional or auto-detecting provider support
|
|
|
|
**StarPunk is at fault** - the implementation is missing a required OAuth 2.0 parameter that IndieAuth inherits.
|
|
|
|
## References
|
|
- [OAuth 2.0 RFC 6749 Section 4.1.3](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.3)
|
|
- [IndieAuth W3C TR Section 6.3.1](https://www.w3.org/TR/indieauth/#token-request)
|
|
- [PKCE RFC 7636](https://datatracker.ietf.org/doc/html/rfc7636) (not part of IndieAuth spec) |