LWS Protocol

The authorization server's token endpoint MUST support the urn:ietf:params:oauth:grant-type:token-exchange grant type, as described in OAuth 2.0 Token Exchange [RFC8693].

When performing the token exchange grant type, the following additional requirements apply:

• The resource parameter is REQUIRED. The value of this parameter MUST be an absolute URI and will be used to populate the aud (audience) claim in the resulting access token. The supplied value will be the same as the realm parameter response in a WWW-Authenticate challenge. The authorization server MUST reject any request in which the resource parameter identifies an unknown or untrusted storage.
• The subject_token parameter is REQUIRED. The value of this parameter MUST include a valid subject token, such as an end-user credential.
• Before returning an access token to the client, the authorization server MUST successfully validate all presented tokens.

Non-normative example of a token request (the subject_token parameter has been truncated).

POST /token HTTP/1.1
Host: authorization.example
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange
&resource=https%3A%2F%2Fstorage.example%2Fstorage_1
&subject_token=eyJ0eXAiOiJhcytqd3QiLCJhbGciO...fiK51VwhsxJ-siBMR-YFiA
&subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Aid_token

If the token request is valid and the client is authorized to make the request, the authorization server response MUST conform to Section 5.1 from the OAuth 2.0 Authorization Framework [RFC6749]. The resulting access token MUST conform to the JSON Web Token Profile for OAuth 2.0 Access Tokens [RFC9068].

In addition, the access token must meet the following requirements:

• sub (subject) — REQUIRED. This claim MUST be an absolute URI identifying the agent performing the operation
• iss (issuer) — REQUIRED. This claim MUST be the absolute URI of the authorization server
• client_id (client id) — REQUIRED. This claim MUST be an absolute URI identifying the client.
• aud (audience) — REQUIRED. This claim MUST include the absolute URI supplied by the client in the resource parameter. This value will be used to restrict the entities for which the access token is valid. This will be the same value as provided by a storage server in the realm parameter of a WWW-Authenticate challenge.
• exp (expiration) — REQUIRED. Authorization servers SHOULD issue tokens with short lifetimes (RECOMMENDED: 300 seconds or less) to limit exposure from token theft.
• iat (issued at) — REQUIRED.
• jti (JWT ID) — REQUIRED.

A non-normative example of a successful token response is included below.

HTTP/1.1 200 OK
Content-Type: application/json

{
    "access_token":"eyJ0eXAiOiJhcytqd3QiLCJhbGciOiJFUzI1NiIs...DeWt4QuZXso",
    "token_type":"Bearer",
    "expires_in":3600
}

All invalid or unauthorized requests MUST result in an error response as described in Section 5.2 in the OAuth 2.0 Authorization Framework [RFC6749].

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error":"invalid_request"
}

A client MUST present an access token to a storage server using the Authorization header with an authentication scheme as defined in [RFC6750].

Authorization: Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...

A storage server MUST validate an access token by performing the following checks, rejecting the request upon any failure:

• JWT Signature Validation: Verify the JWT signature using the authorization server's public key retrieved from the jwks_uri specified in the authorization server metadata. Storage servers SHOULD cache these keys and MUST support key rotation.
• Issuer Validation: Verify the iss claim matches the expected authorization server identifier.
• Audience Validation: Verify the aud claim contains exactly one value and this value is an absolute URI identifying the storage server which logically contains the target resource.
• Temporal Validation, subject to an allowable clock skew between systems.
  • Verify the current time is before the exp (expiration) claim.
  • Verify the current time is not before the nbf (not before) claim, if present.
  • Verify that the iat (issued at) claim is not in the future.

If validation fails, the storage server MUST return 401 Unauthorized with a WWW-Authenticate header containing an appropriate error parameter (e.g., invalid_token, invalid_request, or insufficient_scope).

If the token is otherwise valid but an authorization policy does not allow the requested operation, the storage server MUST reject the request.