%%% title = "The Bearer Capability URI Scheme" abbrev = "Bearer Capabilities"
ipr = "trust200902" area = "General" workgroup = "Independent Submission" keyword = ["Internet-Draft"]
submissionType = "independent" category = "info"
[pi] toc = "yes"
[seriesInfo] name = "Internet-Draft" value = "draft-conill-bearcaps-uri-scheme-01" stream = "independent" status = "info"
[[author]] initials = "A." surname = "Conill" fullname = "Ariadne Conill" organization = "Pleroma"
[author.address] email = "email@example.com" %%%
Bearer Capability URIs provide a mechanism for granting access to anyone who possess a copy of the bearer capability URI. It builds on previous work surrounding capability URLs to improve upon their security properties.
Capability URLs [@!W3C.WD-capability-urls-20140218] grant access to resources to whoever possesses the URL. An example of a case where this is useful would be the URLs included in various transactional e-mails, such as password reset or unsubscribe links. This technique of embedding authority inside the URLs themselves is not without it's problems, however.
Bearer Capability URIs define a new URI scheme and associated composition mechanism that is used to combine a stable URL with an access token. By separating the access token from the URL, it is hoped that several security problems can be solved.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [@!RFC2119].
Bearer Capability URIs combine a stable URI with an access token. An example URI would be:
This example URI would define that the URL
could be accessed with the token
123456 using the appropriate
Bearer capability URIs MUST have two query parameters:
u: The stable URL that the bearer capability URI is
associated with for requests.
t: The access token to use for requests.
Bearer capability URIs MUST NOT have any other query parameters.
For bearer capability URIs which reference
the access token MUST be treated as being equivalent to an OAuth
2.0 Bearer token [@!RFC6750].
For example, given the URI
the following HTTP GET request could be made:
GET / HTTP/1.1 Host: example.com Authorization: Bearer 123456
For bearer capability URIs which reference URLs other than
https URLs, the access token SHOULD be supplied using whatever
mechanism is the most appropriate for supplying access tokens for
the given protocol.
Bearer capability URIs by their design should resolve many security concerns that exist with capability URLs. However, they introduce a few new ones that should be considered when implementing clients that consume them.
Browsers and other applications which consume URIs are generally not designed to treat them as sensitive information. For example, URIs appear in application logs and the URI bar in browsers and can be copied from these sources easily.
Applications which consume
bearcap URIs SHOULD display the
underlying stable URL instead of the
bearcap URI itself in
application logs and other UI elements that would normally
Referer header is sent by many HTTP clients to indicate
the URL they are fetching the new resource from. In the case of
capability URLs, this can result in authority being leaked in the
form of server logs, if they log the
Referer header value.
Accordingly, clients which are following a
bearcap URI MUST NOT
Referer header containing the
bearcap URI when fetching
the associated URL. Also, server implementations SHOULD NOT log
bearcap URIs encountered in the
In the event that a
bearcap URI is disclosed to an undesired
party, the person who originally granted access through the
bearcap URI must revoke the associated token. This is not
dissimilar to any other access token based authorization
It is strongly suggested that implementors look at the security considerations section of the OAuth 2.0 Bearer Token Usage specification [@!RFC6750].
This specification registers the following URI Scheme in the URI Schemes Registry [@!RFC7595].
bearcapURI Scheme Registration Request
Scheme name: bearcap
Applications/protocols that use this scheme name: The
bearcap URI scheme is planned to be used for referring
to private resources in the ActivityPub federated network.
Change controller: TODO