fapi-2-advanced | July 2022 | |
Fett & Tonge | Standards Track | [Page] |
OIDF FAPI 2.0 is an API security profile based on the OAuth 2.0 Authorization Framework [RFC6749].¶
This document is not an OIDF International Standard. It is distributed for review and comment. It is subject to change without notice and may not be referred to as an International Standard.¶
Recipients of this draft are invited to submit, with their comments, notification of any relevant patent rights of which they are aware and to provide supporting documentation.¶
The OpenID Foundation (OIDF) grants to any Contributor, developer, implementer, or other interested party a non-exclusive, royalty free, worldwide copyright license to reproduce, prepare derivative works from, distribute, perform and display, this Implementers Draft or Final Specification solely for the purposes of (i) developing specifications, and (ii) implementing Implementers Drafts and Final Specifications based on such documents, provided that attribution be made to the OIDF as the source of the material, but that such attribution does not indicate an endorsement by the OIDF.¶
The technology described in this specification was made available from contributions from various sources, including members of the OpenID Foundation and others. Although the OpenID Foundation has taken steps to help ensure that the technology is available for distribution, it takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this specification or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any independent effort to identify any such rights. The OpenID Foundation and the contributors to this specification make no (and hereby expressly disclaim any) warranties (express, implied, or otherwise), including implied warranties of merchantability, non-infringement, fitness for a particular purpose, or title, related to this specification, and the entire risk as to implementing this specification is assumed by the implementer. The OpenID Intellectual Property Rights policy requires contributors to offer a patent promise not to assert certain patent claims against other contributors and against implementers. The OpenID Foundation invites any interested party to bring to its attention any copyrights, patents, patent applications, or other proprietary rights that may cover technology that may be required to practice this specification.¶
The keywords "shall", "shall not", "should", "should not", "may", and "can" in this document are to be interpreted as described in ISO Directive Part 2 [ISODIR2]. These keywords are not used as dictionary terms such that any occurrence of them shall be interpreted as keywords and are not to be interpreted with their natural language meanings.¶
OIDF FAPI is an API security profile based on the OAuth 2.0 Authorization Framework [RFC6749]. This Advanced Profile aims to reach the security goals and the non-repudiation goals laid out in the Attacker Model [attackermodel].¶
All provisions of the [Security Profile] apply to the Advanced Profile as well, with the extensions described in the following.¶
In addition to the technologies used in the [Security Profile], the following standards are used in the Advanced Profile:¶
OAuth 2.0 JWT Secured Authorization Request (JAR) [RFC9101] for signing authorization requests¶
JWT Secured Authorization Response Mode for OAuth 2.0 [JARM] for signing authorization responses¶
OAuth 2.0 Token Introspection [RFC7662] with [I-D.ietf-oauth-jwt-introspection-response] for signing introspection responses¶
HTTP Message Signatures [I-D.ietf-httpbis-message-signatures] and Digest Fields [I-D.ietf-httpbis-digest-headers] for signing HTTP requests to and responses from Resource Servers.¶
We understand that some ecosystems may only desire to implement 1 or 2 of the above 3, it is therefore anticipated that a piece of software will be able to conform to each of the methods separately, i.e. there will be separate tests for the following:¶
In the context of this specification, non-repudiation refers to the assurance that the owner of a signature key pair that was capable of generating an existing signature corresponding to certain data cannot convincingly deny having signed the data ([NIST.SP.800-133]).¶
To support non-repudiation for NR6 in the [attackermodel], Introspection Responses can be signed.¶
Clients implementing FAPI2 introspection response signing¶
shall request signed token introspection responses according to [I-D.ietf-oauth-jwt-introspection-response]¶
shall verify the signed token introspection responses¶
To support non-repudiation for NR7, NR8 and NR9 in the [attackermodel], HTTP requests and responses can be signed.¶
This profile supports HTTP Message Signing using the HTTP Message Signatures specification being developed by the IETF HTTP Working Group.¶
Clients implementing HTTP Message Signing¶
shall create an HTTP Message Signature as described in [I-D.ietf-httpbis-message-signatures].¶
shall include @method
(the method used in the HTTP request) in the signature input¶
shall include date
(the HTTP date header value) in the signature input¶
shall include @target-uri
(the full request URI of the HTTP request) in the signature input¶
when the message contains a request body, include the content-digest
header as defined in
[I-D.ietf-httpbis-digest-headers] in the request, and include that header in the signature input.
Content-encoding agnostic digest methods (such as sha-256) should be used.¶
shall retrieve the valid public key for the Resource Server.¶
shall accept and verify the signature in the response as described in [I-D.ietf-httpbis-message-signatures]¶
NOTE: This specification doesn't specify the exact means by which a Client can retrieve
the key for the Resource Server. Together with the identity of the Resource Server and the
keyId
in the Signature-Input
field, the Client can retrieve the key from a trusted third
party or by some other means.¶
The FAPI 2.0 endpoints are OAuth 2.0 protected resource endpoints that perform sensitive actions and return protected information for the resource owner associated with the submitted access token.¶
Resource servers with FAPI endpoints implementing HTTP Message Signing¶
shall retrieve the valid public key for the client¶
shall verify the signature received from the Client as described in [I-D.ietf-httpbis-message-signatures].¶
shall reject requests with missing or invalid signatures using HTTP Status Code 401¶
shall create an HTTP Message Signature for the response as described in [I-D.ietf-httpbis-message-signatures].¶
shall cryptographically link the response to the request by including the request signature in the response signature input by means of the req
boolean flag defined in 2.3 in [I-D.ietf-httpbis-message-signatures]¶
shall include the content-digest
header as defined in
[I-D.ietf-httpbis-digest-headers] in the response, and include that header in the signature input. Content-encoding agnostic digest methods (such as sha-256) should be used.¶
shall include @status
(the status code of the response) in the signature input¶
shall include date
(the HTTP date header value) in the signature input¶
NOTE: This specification doesn't specify the exact means by which a Resource Server can retrieve
the key for the Client. The Resource Server can obtain an identifier for the Client either from a
mutual TLS cerficiate or from a JWT access token or from a token introspection response. With a Client
identifier and the keyId
in the Signature-Input
field, the Resource Server can retrieve the key from
a trusted third party or by some other means.¶
Some ecosystems are choosing to require clients accessing their endpoints to supply a TLS client certificate at endpoints that would not otherwise require a TLS client certificate (for example, the PAR endpoint when using privatekeyjwt authentication).¶
This is outside of the scope of both [RFC8705] and the FAPI standards, however in the interests of interoperability we
state that when using TLS as a transport level protection in this manner, authorization servers should expect clients to
call the endpoints located in the root of the server metadata, and not those found in mtls_endpoint_aliases
.¶
(todo)¶