RFC070: Using WWW-Authenticate header as an access token endpoint discovery mechanism

Background and rationale

This Request for Comments describes the use of a WWW-Authenticate response header field as an authentication challenge for access token endpoint discovery. A service consumer typically knows the location of the resource it seeks access to but does not know where to obtain an access token for authentication. This proposal suggests communicating the URL using the authentication grant.

Proposed change: purpose

Using the iSHARE protocol to handle authentication for a resource requires a service consumer to know where to find a token endpoint to request an access token. Currently, the protocol does not specify how to derive the location of this endpoint for a given resource.

The protocol seems to imply that every service implements the /connect/token endpoint, but this is not practical in many cases. The service may not allow routing to the root of the URL path, or the access token endpoint may only be available on a different host. Deploying the access token endpoint as a separate service makes sense because it is more involved than validating the validity of an access token; the access token endpoint also needs to validate the adherence of the requesting party for instance.

Configuring the location of the access token endpoint per service endpoint is not feasible because the variation of endpoints is endless, and the service consumer may require access to service locations which are not known prior to implementation. Thus, a discovery mechanism is needed.

Typical implementations that will benefit from a discovery mechanism are applications where URLs to resources are shared between parties, for instance, when using events or webhooks.

Proposed change: considerations and requirements

Following the HTTP protocol, unauthorized access from a service consumer should be responded to with "a 401 (Unauthorized) response, and a server MUST send a WWW-Authenticate header field containing at least one challenge" (see also RFC 9110 "HTTP Semantics" section 11.6.1 "WWW-Authenticate"). However, the iSHARE protocol does not specify what the content of this header should be.

Since iSHARE is related to OAuth 2.0, it can build upon RFC 6750 "The OAuth 2.0 Authorization Framework: Bearer Token Usage" to provide more information about the access token endpoint location and party ID of the service provider.

Unauthenticated Request

When receiving a request for a protected resource, a service provider MUST respond with a 401 (Unauthorized) response and provide at least one authentication challenge with the authentication scheme Bearer and an authentication parameter scope containing iSHARE using the "WWW-Authenticate" response header. See also RFC 6749 "The OAuth 2.0 Authorization Framework" section 3.3 "Access Token Scope" and the iSHARE protocol section about "Access token (M2M)".

WWW-Authenticate: Bearer scope="iSHARE"

This signals to the service consumer that an iSHARE access token endpoint MUST be used to obtain a bearer token for access. An access token endpoint MAY be available at /connect/token relative to the location of the resource, and the service consumer SHOULD try that location when no other information is available.

When the access token endpoint is not available at the known location, the authentication grant SHOULD include the server_id containing the party ID of the service provider and server_access_token_endpoint for the URL to the access token endpoint. The URL MAY be relative to the URL of the resource being accessed.

WWW-Authenticate: Bearer scope="iSHARE" server_id="EU.EORI.1234" server_access_token_endpoint="https://example.com/foo/connect/token"

Both server_id and server_access_token_endpoint MUST be provided to allow a service consumer to obtain an access token at the location.

Security Considerations

Exposing the location of the access token endpoint does not weaken the service provider because this endpoint SHOULD already be hardened and protected against common network attack vectors. Hiding an access token endpoint is not considered a valid security practice.

Normative References

RFC9110

Fielding, R., Nottingham, M., and J. Reschke, "HTTP Semantics", STD 97, RFC 9110, DOI 10.17487/RFC9110, February 2022, https://www.rfc-editor.org/rfc/rfc9110.

RFC6749

Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012, https://www.rfc-editor.org/info/rfc6749.

RFC6750

Jones, M. and D. Hardt, "The OAuth 2.0 Authorization Framework: Bearer Token Usage", RFC 6750, DOI 10.17487/RFC6750, October 2012, https://www.rfc-editor.org/info/rfc6750.