fapi-http-signing-requirements March 2024
Heenan Standards Track [Page]
Workgroup:
fapi
Published:
Author:
J. Heenan, Ed.
Authlete

Financial-grade API: HTTP Signing Requirements

Abstract

The Financial-grade API Standard provides a profile for OAuth 2.0 suitable for use in financial services and other similar higher risk scenarios. Ecosystems that have Financial-grade APIs often also have a requirement for the signing of HTTP requests or responses, this document covers the likely requirements and potential solutions.

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. Financial-grade API: HTTP Signing Requirements

2.1. Introduction

The Financial-grade API Standard provides a profile for OAuth 2.0 suitable for use in financial services and other similar higher risk scenarios. Ecosystems that have Financial-grade APIs often also have a requirement for the signing of HTTP requests or responses, this document covers the likely requirements and potential solutions.

2.2. Scope

This document specifies the method for an application to:

  • obtain OAuth tokens via a backchannel authentication flow in an appropriately secure manner for financial data access and other similar situations where the risk is higher;
  • use tokens to interact with protected data via REST endpoints.

2.3. Terms and definitions

For the purpose of this standard, the terms defined in [RFC6749], [RFC6750], [RFC7636], [OpenID] and OpenID Connect Client Initiated Backchannel Authentication Core apply.

2.4. Symbols and Abbreviated terms

API – Application Programming Interface

FAPI - Financial-grade API

HTTP – Hyper Text Transfer Protocol

OIDF - OpenID Foundation

REST – Representational State Transfer

TLS – Transport Layer Security

2.5. Typical requirements

2.5.1. Introduction

The section lists the likely requirements that influence the choice of HTTP signing method for ecosystems using Financial-grade APIs.

2.5.2. Non-repudiation

Generally ecosystems look to signing as a method for non-repudiation, meaning that the request or response can be retained by the parties and later used as prove that the message came from a party that had possession of the relevant private key.

Although TLS certificates can be used for instantaneous proof of key possesion, it is essentially impractical to retain all the necessary state such that it is possible to later independently verify key possession.

Any signing scheme must support straightforward serialization for later verification.

2.5.3. JSON payloads

As the primary use-case for Financial-grade APIs is with JSON payloads, it is generally possible to make using of signing methods that are specific to JSON.

2.5.4. Interference with payload

As Financial-grade APIs always use end-to-end encrypted TLS, it is generally possible to assume that the message body will not be tampered with (deliberately or accidentally) during transport.

However many middleware systems come with REST clients that will often parse JSON payloads automatically, making it difficult to reconstruct the original message body to verify the signature. It is often possible to workaround this (for example canonicalisation or base64 encoding of payloads), but the workarounds can reduce simplicity or robustness. It is often possible to access the raw payload by avoiding use of the REST client. In time this would be less of an issue, as the hope is that REST clients would implement support for widely used signature schemes.

2.5.5. Signing of entire message

In REST-like systems, the Request-URI, method and some HTTP headers often include important information that must be within the scope of the signature.

2.5.6. Interoperability

HTTP signing methods must be sufficiently well specified and straightforward to implement such that the signing library does not need to be aware of ecosystem specifics.

Systems must not have high rates of false negatives between difference implementations.

2.6. Security Considerations

There are no additional security considerations beyond those in [FAPI1-PART1], [FAPI1-PART2], [FAPICIBA].

2.7. Privacy Considerations

There are no additional privacy considerations beyond those in [FAPI1-PART1], [FAPI1-PART2], [FAPICIBA].

2.8. Acknowledgements

The following people contributed heavily towards this document:

  • Nat Sakimura (Nomura Research Institute) -- Chair, Editor
  • Anoop Saxana (Intuit) -- Co-chair, FS-ISAC Liaison
  • Anthony Nadalin (Microsoft) -- Co-chair, SC 27 Liaison
  • Dave Tonge (Moneyhub) -- Co-chair, UK Implementation Entity Liaison
  • Brian Campbell (Ping Identity)
  • John Bradley (Yubico)
  • Joseph Heenan (Authlete)

3. Normative References

[FAPI1-PART1]
Sakimura, N., Bradley, J., and I. Illumila, "Financial-grade API Security Profile 1.0 - Part 1: Baseline", , <https://openid.net/specs/openid-financial-api-part-1-1_0.html>.
[FAPI1-PART2]
Sakimura, N., Bradley, J., and I. Illumila, "Financial-grade API Security Profile 1.0 - Part 2: Advanced", , <https://openid.net/specs/openid-financial-api-part-2-1_0.html>.
[FAPICIBA]
Tonge, D., Heenan, J., Lodderstedt, T., and B. Campbell, "Financial-grade API: Client Initiated Backchannel Authentication Profile", , <https://openid.net/specs/openid-financial-api-ciba-ID1.html>.
[ISODIR2]
Standardization, I. O. F., "ISO/IEC Directives Part 2 -", <https://www.iso.org/sites/directives/current/part2/index.xhtml>.
[OpenID]
Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and C. Mortimore, "OpenID Connect Core 1.0 incorporating errata set 1", , <http://openid.net/specs/openid-connect-core-1_0.html>.
[RFC6749]
Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, , <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, , <https://www.rfc-editor.org/info/rfc6750>.
[RFC7636]
Sakimura, N., Ed., Bradley, J., and N. Agarwal, "Proof Key for Code Exchange by OAuth Public Clients", RFC 7636, DOI 10.17487/RFC7636, , <https://www.rfc-editor.org/info/rfc7636>.

Author's Address

Joseph Heenan (editor)
Authlete