fxa/docs/adr/0007-subscription-claim-jwt-access-token.md

Placing subscription info in the fxa-subscriptions claim of JWT access tokens

• Status: proposed
• Deciders: Shane Tomlinson
• Date: 2019-09-30

Technical Story: https://github.com/mozilla/fxa/issues/1595

Context and Problem Statement

A mechanism is needed to inform service providers (SP) that a user has paid for a given subscription. A SP could fetch the user's profile information, however, we prevent some 3rd party SPs from doing so, and instead give them all the information they need in a JWT format access token. Adding subscription information in JWT access tokens will give SPs the information they need to verify users have paid for a subscription.

Decision Drivers

• Security - Users should not be able to get access to subscriptions they have not paid for.
• Extensibility - Adding subscription info should not inhibit future extensions to JWT access tokens.
• Standards - The JWT access token draft spec format should be followed as closely as possible.

Considered Options

1. Add subscriptions to the scopes claim
2. Add subscriptions as its own claim, fxa-subscriptions

Decision Outcome

Chosen option: Adding subscription info into its own claim was chosen because FxA's lax scope checking means bad acting users could grant themselves access to subscriptions they have not paid for. See this bug regarding FxA's lax scope checking.

Positive Consequences

• The JWT access token contains all the information an SP needs to verify the user has paid for a subscription.
• Users are unable to grant themselves access to subscriptions they have not paid for.

Negative Consequences

• SPs must now check two claims from the JWT to ensure a user is able to access a protected resource.
• An additional claim is added that is not defined in the JWT access token draft spec.

Pros and Cons of the Options

Add subscriptions to the scopes claim

An access token for a user that has paid for subscription1 would have subscription1 in it's scope claim.

e.g.,

{
  "jti": "cafecafe",
  "sub": "deadbeef",
  "scope": "profile:read subscription1",
  ...
}

• Good, because subscription information is in scope which is most likely the expected claim in which an SP would look for this info.
• Good, because no new claims are added over what's defined in the JWT access token draft spec.
• Bad, because FxA's lax scope checking means users would grant themselves access to subscriptions they have not paid for.

Add subscriptions to the fxa-subscriptions claim

An access token for a user that has paid for subscription1 would have subscription1 in it's scope claim.

e.g.,

{
  "jti": "cafecafe",
  "sub": "deadbeef",
  "scope": "profile:read",
  "fxa-subscriptions": "subscription1"
  ...
}

• Good, because users are unable to grant themselves access to subscriptions they have not paid for.
• Good, because subscription information is isolated from other possible future JWT extensions.
• Bad, because fxa-subscriptions is a non-standard claim and SP developers may not expect to look there.

Links