fapi-2-security August 2022
Fett Standards Track [Page]
Intended Status:
Standards Track
D. Fett

FAPI 2.0 Security Profile


The OpenID Foundation (OIDF) promotes, protects and nurtures the OpenID community and technologies. As a non-profit international standardizing body, it is comprised by over 160 participating entities (workgroup participant). The work of preparing implementer drafts and final international standards is carried out through OIDF workgroups in accordance with the OpenID Process. Participants interested in a subject for which a workgroup has been established have the right to be represented in that workgroup. International organizations, governmental and non-governmental, in liaison with OIDF, also take part in the work. OIDF collaborates closely with other standardizing bodies in the related fields.

Final drafts adopted by the Workgroup through consensus are circulated publicly for the public review for 60 days and for the OIDF members for voting. Publication as an OIDF Standard requires approval by at least 50% of the members casting a vote. There is a possibility that some of the elements of this document may be the subject to patent rights. OIDF shall not be held responsible for identifying any or all such patent rights.


The FAPI 2.0 Security Profile is an API security profile based on the OAuth 2.0 Authorization Framework [RFC6749] and related specifications suitable for protecting APIs in high-value scenarios. While the security profile was initially developed with a focus on financial applications, it is designed to be universally applicable for protecting APIs exposing high-value and sensitive (personal and other) data, for example, in e-health and e-government applications.


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.

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.

Table of Contents

1. Scope

This document specifies the requirements for confidential Clients to securely obtain OAuth tokens from Authorization Servers and securely use those tokens to access REST APIs at Resource Servers.

2. Terms and definitions

For the purpose of this document, the terms defined in [RFC6749], [RFC6750], [RFC7636], [OIDC] and ISO29100 apply.

3. Symbols and Abbreviated terms

API - Application Programming Interface

HTTP - Hyper Text Transfer Protocol

REST - Representational State Transfer

TLS - Transport Layer Security

DNS - Domain Name System

DNSSEC - Domain Name System Security Extensions

CAA - Certificate Authority Authorization

URI - Uniform Resource Identifier

4. Security Profile

4.1. Introduction

The FAPI 2.0 Security Profile is an API security profile based on the OAuth 2.0 Authorization Framework [RFC6749], that aims to reach the security goals laid out in the Attacker Model [attackermodel].

This profile is the base of the FAPI 2.0 Framework. Other specifications that are part of this framework and may be used together with this profile include:

  1. FAPI Message Signing is recommended when messages are required to be signed for the purposes of non-repudiation.

  2. FAPI CIBA is recommended when support is required for decoupled or cross device flows.

  3. Grant Management is recommended for ecosystems that require interopable grant management.

  4. OAuth 2.0 Rich Authorization Requests (RAR) [I-D.ietf-oauth-rar] is recommended when the scope parameter is not expressive enough to convey the authorization that a client wants to obtain.

We are not currently aware of any mechanisms that would allow public clients to be secured to the same degree and hence their use is not within the scope of this specification.

4.2. Network Layer Protections

4.2.1. Requirements for all endpoints

TLS connections shall be protected against network attackers. To this end, clients, authorization servers, and resource servers:

  1. shall only offer TLS protected endpoints and shall establish connections to other servers using TLS. TLS connections shall be set up to use TLS version 1.2 or later.

  2. when using TLS 1.2, follow the recommendations for Secure Use of Transport Layer Security in [RFC7525].

  3. should use DNSSEC to protect against DNS spoofing attacks that can lead to the issuance of rogue domain-validated TLS certificates.

  4. shall perform a TLS server certificate check, as per [RFC6125].

NOTE: Even if an endpoint uses only organization validated (OV) or extended validation (EV) TLS certificates, rogue domain-validated certificates can be used to impersonate the endpoints and conduct man-in-the-middle attacks. CAA records [RFC8659] can help to mitigate this risk.

4.2.2. Requirements for endpoints not used by web browsers

  1. when using TLS 1.2, only the following 4 cipher suites shall be permitted:





  2. When using the TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 or TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 cipher suites, key lengths of at least 2048 bits are required.

4.2.3. Requirements for endpoints used by web browsers

Endpoints for the use by web browsers

  1. shall use methods to ensure that connections cannot be downgraded using TLS Stripping attacks. A preloaded [preload] HTTP Strict Transport Security policy [RFC6797] can be used for this purpose. Some top-level domains, like .bank and .insurance, have set such a policy and therefore protect all second-level domains below them.

  2. when using TLS 1.2, shall only use cipher suites allowed in [RFC7525]

4.3. Profile

In the following, a profile of the following technologies is defined:

  • OAuth 2.0 Authorization Framework [RFC6749]

  • OAuth 2.0 Bearer Tokens [RFC6750]

  • Proof Key for Code Exchange by OAuth Public Clients (PKCE) [RFC7636]

  • OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens (MTLS) [RFC8705]

  • OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer (DPoP) [I-D.ietf-oauth-dpop]

  • OAuth 2.0 Pushed Authorization Requests (PAR) [RFC9126]

  • OAuth 2.0 Authorization Server Metadata [RFC8414]

  • OAuth 2.0 Authorization Server Issuer Identification [RFC9207]

  • OpenID Connect Core 1.0 incorporating errata set 1 [OIDC]

4.3.1. Requirements for Authorization Servers General Requirements

Authorization servers

  1. shall distribute discovery metadata (such as the authorization endpoint) via the metadata document as specified in [OIDD] and [RFC8414]

  2. shall reject requests using the resource owner password credentials grant or the implicit grant described in [RFC6749] or the hybrid flow as described in [OIDC]

  3. shall support confidential clients as defined in [RFC6749]

  4. shall only issue sender-constrained access tokens,

  5. shall use one of the following methods for sender-constrained access tokens:

  6. shall authenticate clients using one of the following methods:

    • MTLS as specified in section 2 of [RFC8705]

    • private_key_jwt as specified in section 9 of [OIDC]

  7. shall not expose open redirectors (see section 4.10 of [I-D.ietf-oauth-security-topics])

  8. shall accept its issuer identifier value (as defined in [RFC8414]) in the aud claim received in client authentication assertions.

  9. shall not use refresh token rotation unless, in the case a response with a new refresh token is not received and stored by the client, retrying the request (with the previous refresh token) will succeed.

  10. if using DPoP, may use the server provided nonce mechanism (as defined in section 8 of [I-D.ietf-oauth-dpop]).

NOTE: In order to facilitate interoperability the authorization server should also accept its token endpoint URL or the URL of the endpoint at which the assertion was received in the aud claim received in client authentication assertions.

NOTE: Refresh token rotation is an optional feature defined in [RFC6749] section 6 where the Authorization Server issues a new refresh token to the client as part of the refresh_token grant. This specification discourages the use of this feature as it doesn't bring any security benefits for confidential clients, and can cause significant operational issues. However to allow for operational agility, Authorization Servers may implement it providing they meet the requirement in clause 20.

NOTE: Other grants as appropriate may be supported, for example the client credentials grant, the Client Initiated Backchannel Authentication grant, etc. Authorization Code Flow

For the Authorization Code flow, Authorization servers

  1. shall support the authorization code grant (response_type=code & grant_type=authorization_code) described in [RFC6749]

  2. shall support client-authenticated pushed authorization requests according to [RFC9126]

  3. shall reject authorization requests sent without [RFC9126]

  4. shall reject pushed authorization requests without client authentication

  5. shall require PKCE [RFC7636] with S256 as the code challenge method

  6. shall require the redirect_uri parameter in pushed authorization requests

  7. shall return an iss parameter in the authorization response according to [RFC9207]

  8. shall not transmit authorization responses over unencrypted network connections, and, to this end, shall not allow redirect URIs that use the "http" scheme except for native clients that use Loopback Interface Redirection as described in [RFC8252], Section 7.3,

  9. shall reject an authorization code (section 1.3.1 of [RFC6749]) if it has been previously used

  10. shall not use the HTTP 307 status code when redirecting a request that contains user credentials to avoid forwarding the credentials to a third party accidentally (see section 4.11 of [I-D.ietf-oauth-security-topics]);

  11. should use the HTTP 303 status code when redirecting the user agent using status codes;

  12. shall issue pushed authorization requests request_uri with expires_in values of between 5 and 600 seconds.

NOTE: If replay identification of the authorization code is not possible, it is desirable to set the validity period of the authorization code to one minute or a suitable short period of time. The validity period may act as a cache control indicator of when to clear the authorization code cache if one is used Returning Authenticated User's Identifier

If it is desired to provide the authenticated user's identifier to the client in the token response, the authorization server shall support OpenID Connect [OIDC].

4.3.2. Requirements for Clients General Requirements


  1. shall support sender-constrained access tokens using one of the following methods:

  2. shall support client authentication using one of the following methods:

    • MTLS as specified in section 2 of [RFC8705]

    • private_key_jwt as specified in section 9 of [OIDC]

  3. shall send access tokens in the HTTP header as in Section 2.1 of OAuth 2.0 Bearer Token Usage [RFC6750]

  4. shall not expose open redirectors (see section 4.10 of [I-D.ietf-oauth-security-topics])

  5. if using private_key_jwt, shall use the Authorization Server's issuer identifier value (as defined in [RFC8414]) in the aud claim sent in client authentication assertions. The issuer identifier value shall be sent as a string not as an item in an array.

  6. shall support refresh tokens and their rotation.

  7. if using MTLS client authentication or MTLS sender-constrained access tokens, shall support the mtls_endpoint_aliases metadata defined in [RFC8705]

  8. if using DPoP, shall support the server provided nonce mechanism (as defined in section 8 of [I-D.ietf-oauth-dpop]).


This profile may be used by Confidential Clients on a user-controlled device where the system clock may not be accurate, this may cause private_key_jwt client authentication to fail. In such circumstances a Client should consider using the HTTP Date header returned from the server to synchronise it's own clock when generating client assertions. Authorization Code Flow

For the Authorization Code flow, Clients

  1. shall use the authorization code grant described in [RFC6749]

  2. shall use pushed authorization requests according to [RFC9126]

  3. shall use PKCE [RFC7636] with S256 as the code challenge method

  4. shall check the iss parameter in the authorization response according to [RFC9207] to prevent Mix-Up attacks

4.3.3. Requirements for Resource Servers

The FAPI 2.0 endpoints are OAuth 2.0 protected resource endpoints that return protected information for the resource owner associated with the submitted access token.

Resource servers with the FAPI endpoints

  1. shall accept access tokens in the HTTP header as in Section 2.1 of OAuth 2.0 Bearer Token Usage [RFC6750]

  2. shall not accept access tokens in the query parameters stated in Section 2.3 of OAuth 2.0 Bearer Token Usage [RFC6750]

  3. shall verify the validity, integrity, expiration and revocation status of access tokens

  4. shall verify that the authorization represented by the access token is sufficient for the requested resource access and otherwise return errors as in section 3.1 of [RFC6750]

  5. shall support and verify sender-constrained access tokens using one of the following methods:

4.4. Cryptography and Secrets

  1. Authorization Servers, Clients, and Resource Servers when creating or processing JWTs shall

    1. adhere to [RFC8725]

    2. use PS256, ES256, or EdDSA (using the Ed25519 subtype) algorithms

    3. not use or accept the none algorithm

  2. RSA keys shall have a minimum length of 2048 bits.

  3. Elliptic curve keys shall have a minimum length of 160 bits.

  4. Credentials not intended for handling by end-users (e.g., access tokens, refresh tokens, authorization codes, etc.) shall be created with at least 128 bits of entropy such that an attacker correctly guessing the value is computationally infeasible. Cf. Section 10.10 of [RFC6749].

4.5. Differences to FAPI 1.0

Table 1
FAPI 1.0 Read/Write FAPI 2.0 Reasons
JAR, JARM PAR integrity protection and compatibility improvements for authorization requests; only code in response
- shall adhere to Security BCP
s_hash - state integrity is protected by PAR; protection provided by state is now provided by PKCE
pre-registered redirect URIs redirect URIs in PAR pre-registration is not required with client authentication and PAR
response types code id_token or code response type code improve security: no ID token in front-channel; not needed
ID Token as detached signature - ID token does not need to serve as a detached signature
potentially encrypted ID Tokens encryption not required ID Tokens only exchanged in back channel
nbf & exp claims in request object request_uri has lifetime under 300 seconds Prevents pre-generation of requests.
x-fapi-* headers - Removed pending further discussion
MTLS for sender-constrained access tokens MTLS or DPoP

4.6. Security Considerations

4.6.1. JWKS URIs

This profile supports the use of private_key_jwt and in addition allows the use of OpenID Connect. When these are used Clients and Authorization Servers need to verify payloads with keys from another party. For Authorization Server's this profile strongly recommends the use of JWKS URI endpoints to distribute public keys. For Client's key management this profile recommends either the use of JWKS URI endpoints or the use of the jwks parameter in combination with [RFC7591] and [RFC7592].

The definition of the Authorization Server jwks_uri can be found in [RFC8414], while the definition of the Client jwks_uri can be found in [RFC7591].

In addition, this profile

  1. requires that jwks_uri endpoints shall be served over TLS;

  2. recommends that JOSE headers for x5u and jku should not be used; and

  3. recommends that the JWK set does not contain multiple keys with the same kid.

4.6.2. Duplicate Key Identifiers

JWK sets should not contain multiple keys with the same kid. However, to increase interoperability when there are multiple keys with the same kid, the verifier shall consider other JWK attributes, such as kty, use, alg, etc., when selecting the verification key for the particular JWS message. For example, the following algorithm could be used in selecting which key to use to verify a message signature:

  1. find keys with a kid that matches the kid in the JOSE header;

  2. if a single key is found, use that key;

  3. if multiple keys are found, then the verifier should iterate through the keys until a key is found that has a matching alg, use, kty, or crv that corresponds to the message being verified.

5. Privacy considerations


6. Acknowledgements

We would like to thank Takahiko Kawasaki, Filip Skokan, Dave Tonge, Nat Sakimura, Stuart Low, Dima Postnikov, Torsten Lodderstedt, Joseph Heenan, Travis Spencer, Brian Campbell, Ralph Bragg and Lukasz Jaromin for their valuable feedback and contributions that helped to evolve this specification.

7. Normative References

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>.
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>.
Fett, D., "FAPI 2.0 Attacker Model", , <https://bitbucket.org/openid/fapi/src/master/FAPI_2_0_Attacker_Model.md>.
Saint-Andre, P. and J. Hodges, "Representation and Verification of Domain-Based Application Service Identity within Internet Public Key Infrastructure Using X.509 (PKIX) Certificates in the Context of Transport Layer Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, , <https://www.rfc-editor.org/info/rfc6125>.
Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 Authorization Server Metadata", RFC 8414, DOI 10.17487/RFC8414, , <https://www.rfc-editor.org/info/rfc8414>.
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>.
Richer, J., Ed., Jones, M., Bradley, J., and M. Machulak, "OAuth 2.0 Dynamic Client Registration Management Protocol", RFC 7592, DOI 10.17487/RFC7592, , <https://www.rfc-editor.org/info/rfc7592>.
Standardization, I. O. F., "ISO/IEC Directives Part 2 -", , <https://www.iso.org/sites/directives/current/part2/index.xhtml>.
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>.
Fett, D., Campbell, B., Bradley, J., Lodderstedt, T., Jones, M., and D. Waite, "OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer (DPoP)", Work in Progress, Internet-Draft, draft-ietf-oauth-dpop-10, , <https://www.ietf.org/archive/id/draft-ietf-oauth-dpop-10.txt>.
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>.
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>.
Hodges, J., Jackson, C., and A. Barth, "HTTP Strict Transport Security (HSTS)", RFC 6797, DOI 10.17487/RFC6797, , <https://www.rfc-editor.org/info/rfc6797>.
Sheffer, Y., Hardt, D., and M. Jones, "JSON Web Token Best Current Practices", BCP 225, RFC 8725, DOI 10.17487/RFC8725, , <https://www.rfc-editor.org/info/rfc8725>.
Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", RFC 7591, DOI 10.17487/RFC7591, , <https://www.rfc-editor.org/info/rfc7591>.
Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0 Rich Authorization Requests", Work in Progress, Internet-Draft, draft-ietf-oauth-rar-12, , <https://www.ietf.org/archive/id/draft-ietf-oauth-rar-12.txt>.
Sheffer, Y., Holz, R., and P. Saint-Andre, "Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, , <https://www.rfc-editor.org/info/rfc7525>.
Hallam-Baker, P., Stradling, R., and J. Hoffman-Andrews, "DNS Certification Authority Authorization (CAA) Resource Record", RFC 8659, DOI 10.17487/RFC8659, , <https://www.rfc-editor.org/info/rfc8659>.
Sakimura, N., Bradley, J., Jones, M., and E. Jay, "OpenID Connect Discovery 1.0 incorporating errata set 1", , <https://openid.net/specs/openid-connect-discovery-1_0.html>.
Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps", BCP 212, RFC 8252, DOI 10.17487/RFC8252, , <https://www.rfc-editor.org/info/rfc8252>.
Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, , <https://www.rfc-editor.org/info/rfc6749>.

8. Informative References

Anonymous, "HSTS Preload List Submission", , <https://hstspreload.org/>.
Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett, "OAuth 2.0 Security Best Current Practice", Work in Progress, Internet-Draft, draft-ietf-oauth-security-topics-20, , <https://www.ietf.org/archive/id/draft-ietf-oauth-security-topics-20.txt>.

Appendix A. Notices

Copyright (c) 2021 The OpenID Foundation.

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.

Author's Address

Daniel Fett