fapi-2-message-signing December 2022
Fett & Tonge Standards Track [Page]
Workgroup:
fapi
Internet-Draft:
fapi-2_0-message-signing-01
Published:
Intended Status:
Standards Track
Authors:
D. Fett
yes.com
D. Tonge
Moneyhub Financial Technology

FAPI 2.0 Message Signing

Abstract

OIDF FAPI 2.0 is an API security profile based on the OAuth 2.0 Authorization Framework [RFC6749].

Table of Contents

1. Introduction

1.1. Warning

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.

1.3. Notational Conventions

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.

2. Message Signing Profile

OIDF FAPI 2.0 is an API security profile based on the OAuth 2.0 Authorization Framework [RFC6749]. This Message Signing Profile aims to reach the security goals laid out in the Attacker Model [attackermodel] plus the non-repudiation goals listed below.

All provisions of the [Security Profile] apply to the Message Signing Profile as well, with the extensions described in the following.

2.1. Profile

In addition to the technologies used in the [Security Profile], the following standards are used in this profile:

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:

  • FAPI2-JAR

  • FAPI2-JARM

  • FAPI2-JIR

  • FAPI2-HTTPSig

2.2. Non-Repudiation

Beyond what is captured by the security goals and the attacker model in [attackermodel], parties could try to deny having sent a particular message, for example, a payment request. For this purpose, non-repudiation is needed.

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]).

This is usually achieved by providing application-level signatures that can be stored together with the payload and meaningful metadata of a request or response.

The following messages are affected by this specification:

  • NR1: Pushed Authorization Requests

  • NR2: Authorization Requests (Front-Channel)

  • NR3: Authorization Responses (Front-Channel)

  • NR4: Introspection Responses

  • NR5: Resource Requests

  • NR6: Resource Responses

2.3. Signing Authorization Requests

To support non-repudiation for NR1, Pushed Authorization Requests can be signed. Because FAPI2 uses [RFC9126], NR2 is achieved by default when the Pushed Authorization request is signed.

2.3.1. Requirements for Authorization Servers

Authorization servers implementing FAPI2 authorization request signing

  1. shall support and verify signed request objects according to JAR [RFC9101] at the PAR endpoint [RFC9126]

  2. shall require the aud claim in the request object to be, or to be an array containing, the OP's Issuer Identifier URL;

  3. shall require the request object to contain an nbf claim that is no longer than 60 minutes in the past; and

  4. shall require the request object to contain an exp claim that has a lifetime of no longer than 60 minutes after the nbf claim;

2.3.2. Requirements for Clients

Clients implementing FAPI2 authorization request signing

  1. shall sign request objects according to JAR [RFC9101] that are sent to the PAR endpoint [RFC9126]

  2. shall send the aud claim in the request object as the OP's Issuer Identifier URL;

  3. shall send a nbf claim in the request object;

  4. shall send an exp claim in the request object that has a lifetime of no longer than 60 minutes;

2.4. Signing Authorization Responses

To support non-repudiation for NR3, Authorization Responses can be signed.

2.4.1. Requirements for Authorization Servers

Authorization servers implementing FAPI2 authorization response signing

  1. shall support and issue signed authorization responses via JWT Secured Authorization Response Mode for OAuth 2.0 [JARM]

NOTE: When using [JARM] an Authorization Server should only include the iss authorization response parameter defined by [RFC9207] inside the JWT. This is because [RFC9207] defines iss to be an authorization response parameter, and [JARM] section 4.1 requires all authorization response parameters to be inside the JWT.

2.4.2. Requirements for Clients

Clients implementing FAPI2 authorization response signing

  1. shall set the response_mode to jwt in the authorization request as defined in [JARM]

  2. shall verify signed authorization responses according to [JARM]

2.5. Signing Introspection Responses

To support non-repudiation for NR4, Introspection Responses can be signed.

2.5.1. Requirements for Authorization Servers

Authorization servers implementing FAPI2 introspection response signing

  1. shall sign introspection responses that are issued in JWT format according to [I-D.ietf-oauth-jwt-introspection-response]

2.5.2. Requirements for Clients

Clients implementing FAPI2 introspection response signing

  1. shall request signed token introspection responses according to [I-D.ietf-oauth-jwt-introspection-response]

  2. shall verify the signed token introspection responses

2.6. HTTP Message Signing

To support non-repudiation for NR5 and NR6, 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.

2.6.1. Requirements for signing and verifying resource requests

2.6.1.1. Clients

Clients sending signed resource requests act in the role of "signer" as defined by [I-D.ietf-httpbis-message-signatures]. The signer has the following requirements:

  1. shall create an HTTP Message Signature as described in [I-D.ietf-httpbis-message-signatures]

  2. shall include @method (the method used in the HTTP request) in the signature

  3. shall include @target-uri (the full request URI of the HTTP request) in the signature

  4. shall include the created parameter (the signature creation time) in the signature

  5. shall include the tag parameter with a value of fapi-2-request in the signature

  6. shall include the Authorization header in the signature

  7. when DPoP is in use, shall include the DPoP header in the signature

  8. when the message contains a request body, shall include the content-digest header as defined in [I-D.ietf-httpbis-digest-headers] in the request, and include that header in the signature. Content-encoding agnostic digest methods (such as sha-256) should be used.

2.6.1.2. Resource Servers

Resource servers receiving signed resource requests act in the role of "verifier" as defined by [I-D.ietf-httpbis-message-signatures]. The verifier has the following requirements:

  1. shall retrieve the valid public key for the client

  2. shall verify the signature received from the Client as described in [I-D.ietf-httpbis-message-signatures].

  3. shall reject requests with missing or invalid signatures using HTTP Status Code 401

  4. shall reject requests which don't have a tag parameter with the value of fapi-2-request in the signature

  5. shall reject requests with signatures that are missing @method, @target-uri, or Authorization in the signature

  6. shall reject requests with signatures that are missing the created parameter or have a created value that is greater than an acceptable range. (1 minute is recommended)

  7. when a DPoP header is present in the request, shall reject requests that are missing DPoP in the signature

  8. when the request contains a request body, shall reject requests that are missing content-digest in the signature

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.

2.6.2. Requirements for signing and verifying resource responses

2.6.2.1. Resource Servers

Resource servers responding with a signed resource response act in the role of "signer" as defined by [I-D.ietf-httpbis-message-signatures]. The signer has the following requirements:

  1. shall create an HTTP Message Signature for the response as described in [I-D.ietf-httpbis-message-signatures].

  2. 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.4 in [I-D.ietf-httpbis-message-signatures] on the signature field of the request that caused the response

  3. shall include @status (the status code of the response) in the signature

  4. shall include the created parameter (the signature creation time) in the signature

  5. shall include the tag parameter with a value of fapi-2-response in the signature

  6. when the response contains a response body, 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. Content-encoding agnostic digest methods (such as sha-256) should be used.

2.6.2.2. Clients

Clients receiving signed resource responses act in the role of "verifier" as defined by [I-D.ietf-httpbis-message-signatures]. The verifier has the following requirements:

  1. shall retrieve the valid public key for the Resource Server.

  2. shall accept and verify the signature in the response as described in [I-D.ietf-httpbis-message-signatures]

  3. shall verify that @status and created are included in the signature

  4. if the response contains a body, shall verify that content-digest is in the signature

  5. shall verify that the signature contains the tag parameter with a value of fapi-2-response

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.

NOTE: As noted in [I-D.ietf-httpbis-message-signatures] section 2.4, the Client will need to keep the request signature value in order to verify the response signature.

2.7. MTLS Protection of all endpoints

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.

2.8. Security Considerations

2.8.1. Authorization Response Encryption

In FAPI2, there is no confidential information in the Authorization Response, hence encryption of the Authorization Response is not required for the purposes of security or confidentiality. In addition, to achieve greater interoperability, it is not recommended to use encryption in this case.

Usage of PKCE in FAPI 2 provides protection for code leakage described in 5.4 [JARM].

3. Normative References

[RFC9126]
Lodderstedt, T., Campbell, B., Sakimura, N., Tonge, D., and F. Skokan, "OAuth 2.0 Pushed Authorization Requests", RFC 9126, DOI 10.17487/RFC9126, , <https://www.rfc-editor.org/info/rfc9126>.
[ISODIR2]
Standardization, I. O. F., "ISO/IEC Directives Part 2 -", , <https://www.iso.org/sites/directives/current/part2/index.xhtml>.
[RFC9101]
Sakimura, N., Bradley, J., and M. Jones, "The OAuth 2.0 Authorization Framework: JWT-Secured Authorization Request (JAR)", RFC 9101, DOI 10.17487/RFC9101, , <https://www.rfc-editor.org/info/rfc9101>.
[JARM]
Lodderstedt, T. and B. Campbell, "Financial-grade API: JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)", , <https://openid.net/specs/openid-financial-api-jarm.html>.
[RFC7662]
Richer, J., Ed., "OAuth 2.0 Token Introspection", RFC 7662, DOI 10.17487/RFC7662, , <https://www.rfc-editor.org/info/rfc7662>.
[NIST.SP.800-133]
Barker, E. and A. Roginsky, "NIST Special Publication 800-133", , <https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-133.pdf>.
[RFC9207]
Meyer zu Selhausen, K. and D. Fett, "OAuth 2.0 Authorization Server Issuer Identification", RFC 9207, DOI 10.17487/RFC9207, , <https://www.rfc-editor.org/info/rfc9207>.
[RFC8705]
Campbell, B., Bradley, J., Sakimura, N., and T. Lodderstedt, "OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens", RFC 8705, DOI 10.17487/RFC8705, , <https://www.rfc-editor.org/info/rfc8705>.
[RFC6749]
Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, , <https://www.rfc-editor.org/info/rfc6749>.
[attackermodel]
Fett, D., "FAPI 2.0 Attacker Model", , <https://bitbucket.org/openid/fapi/src/master/FAPI_2_0_Attacker_Model.md>.

4. Informative References

[I-D.ietf-oauth-jwt-introspection-response]
Lodderstedt, T. and V. Dzhuvinov, "JWT Response for OAuth Token Introspection", Work in Progress, Internet-Draft, draft-ietf-oauth-jwt-introspection-response-12, , <https://www.ietf.org/archive/id/draft-ietf-oauth-jwt-introspection-response-12.txt>.
[I-D.ietf-httpbis-digest-headers]
Polli, R. and L. Pardue, "Digest Fields", Work in Progress, Internet-Draft, draft-ietf-httpbis-digest-headers-10, , <https://www.ietf.org/archive/id/draft-ietf-httpbis-digest-headers-10.txt>.
[I-D.ietf-httpbis-message-signatures]
Backman, A., Richer, J., and M. Sporny, "HTTP Message Signatures", Work in Progress, Internet-Draft, draft-ietf-httpbis-message-signatures-15, , <https://www.ietf.org/archive/id/draft-ietf-httpbis-message-signatures-15.txt>.

Authors' Addresses

Daniel Fett
yes.com
Dave Tonge
Moneyhub Financial Technology