Implementers Guide: FAPI 2.0 Final specification vs. Implementers Draft 2.0

Author: Dima Postnikov, Vice-Chair of OpenID Foundation, FAPI WG member

Contributors: Gail Hodges, Nat Sakimura, Ralph Bragg, Filip Skokan, Joseph Heenan.

Introduction

In a significant milestone for the global Open Banking and Open Data community, on February 22nd, the OpenID Foundation published and approved the new and final version of the FAPI 2 Security profile and its Attacker model.

FAPI 2.0 Security Profile: https://openid.net/specs/fapi-security-profile-2_0-final.html

FAPI 2.0 Attacker Model: https://openid.net/specs/fapi-attacker-model-2_0-final.html

A Final Specification provides intellectual property protections to implementers of the specification and is not subject to further revision.

OpenID Foundation’s FAPI working group and many invited experts have worked extensively on the specification to make it simpler, easier to understand, more secure, and more interoperable. This version has been through formal security analysis by the University of Stuttgart, and the certification test suite is being updated to reflect FAPI 2.0 Final.

Since the last implementer draft, there have been many editorial changes: new introduction sections, formatting, corrected typos, section renumbering, updated references to sections of this document and other specifications, and added acknowledgments.

Note: The previous approved implementer’s draft can be found here: https://openid.net/specs/fapi-2_0-security-profile-ID2.html

Below is a detailed summary of the key changes that can impact existing FAPI 2.0 implementations. These changes should be reviewed by all implementers (live or planning to go live) who had built their implementations against the last implementer’s draft.

If you have questions about the specs, please direct them to the FAPI WG mailing list at openid-specs-fapi-owner@lists.openid.net. If you have certification questions, please direct them to certification@oidf.org.

Summary of changes between FAPI 2.0 Implementer’s Draft 2.0 and Final

The changes below are labeled AS if relevant for Authorization Servers, RP for Relying Parties and Clients, and Ecosystem for Ecosystem operators.

‘aud’ claim value in client authentication assertions (AS, RP).

Why? This additional security control was introduced after the specification's formal security analysis, following the discussion in the FAPI working group.

Impact: If your ecosystem or implementation uses and/or supports client authentication assertions, e.g., private_key_jwt, this impacts your implementation (client or authorization server).

The specification was updated to only allow the issuer identifier value as a value for ‘aud’. Authorization servers are required to enforce this behavior. Note: Previously, other values were allowed for interoperability purposes.

Conformance tests will enforce this.

TLS security deferred to BCP195 (AS)

Why? Instead of repeating the content of BCP195, FAPI will refer all TLS security matters to BCP195.

Impact on Authorization Servers:

• IETF periodically publishes BCP195. FAPI 2 implementers must comply with BCP195 changes within 12 months after publication.
• Some ciphers have recently been removed from the recommended list. Please review BCP195 to ensure you are up to date.

Conformance tests will enforce this.

Elliptic curve keys’ length (AS)

Why: The FAPI2 specification aligns with TLS BCP requirements (https://www.rfc-editor.org/rfc/rfc9325.html ) and NIST Guidelines [NIST.SP.800–56A], which have been updated recently.

Impact: Elliptic curve keys used by AS shall have a minimum length of 224 bits.

Conformance tests will enforce this minimum length.

Clock skew (AS)

Why: Clock skew causes many interoperability issues: even a few hundred milliseconds of clock skew can cause JWTs to be rejected by AS as “issued in the future.” This new specification provides additional guidance for dealing with clock skews.

Impact: Authorization servers are required to accept JWTs with an iat or nbf timestamp between 0 and 10 seconds in the future and to reject JWTs with an iat or nbf timestamp greater than 60 seconds in the future.

Conformance tests will test this.

MTLS ecosystems (AS, RP, Ecosystem)

Why? Some ecosystems have implemented MTLS as an additional security control at the transport layer for all server-to-server endpoints requiring transmitting sensitive data. For example, private_key_jwt is sometimes used for client authentication in conjunction with MTLS connectivity.

FAPI 2 recognizes this existing deployment practice and provides additional guidance to improve interoperability.

Key impacts (for ecosystems that choose to use it):

• Authorization server implementations may utilize mtls_endpoint_aliases authorization server metadata to provide a discovery mechanism for endpoints that might have both MTLS and non-MTLS endpoints;
• New client metadata use_mtls_endpoint_aliases was introduced for clients to indicate that they will be using mutual-TLS endpoint aliases [@RFC8705] declared by the authorization server in its metadata even beyond the Mutual-TLS Client Authentication and Certificate-Bound Access Tokens use cases. Client implementations shall use client metadata use_mtls_endpoint_aliases, if present.

Conformance tests will test this.

One-time use of request_uri (AS)

Why? Recent implementation experience of x2app with PAR highlighted that some operating systems pre-load authorization URLs and, in some cases, invalidate request_uri before an intended recipient app can use it.

Impact: Authorization servers are provided with additional guidance on enforcing one-time use of request_uri values: enforcement should occur at the time of authorization(where an authenticated user is presented with the consent details), not at the point of loading an authorization page. Once a user has been presented with consent details, request_uri should be invalidated independently of what the user chooses to do (accept, reject, or ignore/close a browser window or an application).

Refresh token rotation prohibition (Ecosystem)

Why? Refresh token rotation has traditionally been used as a security control. Still, it is known to cause significant operational issues and user experience degradation, with clients losing access to their existing consents. FAPI2 doesn’t require this security control because of the use of confidential clients and sender-constrained access tokens.

Impact: Ecosystems using refresh token rotation should require Authorisation Servers to remove it unless used for infrastructure migration or other extraordinary circumstances.

Some other items we knew already but needed to clarify

• Authorization servers only support confidential clients (Ecosystem).
• Authorization servers shall not support CORS for the authorization endpoint. If this occurs, it means that the clients are not accessing this endpoint correctly (AS).
• As accepted best practice, Authorization Servers should restrict the privileges associated with an access token to the minimum required for the particular application or use case (AS).
• Authorization servers should not allow clients to influence their client_id so that it can be mistaken for an end-user subject identifier. This control prevents a new attack that has been added to security considerations: Client Impersonating Resource Owner (AS, Ecosystem).
• Clients shall only send client_id and request_uri request parameters to the authorization endpoint (all other authorization request parameters are sent via PAR (RFC9126). Clients will fail if they don’t conform to this behavior. AS will fail if they don’t ignore other request parameters sent to the authorization endpoint (AS, RP, Ecosystem).
• Clients are required to use code as the value for response_type. Used to say shall support the authorization code grant (response_type=code & grant_type=authorization_code) described in [@!RFC6749] (AS, RP, Ecosystem).
• Clients shall generate the PKCE challenge specifically for each authorization request and securely bind the challenge to the client and the user agent in which the flow was started (RP).
• For interoperability reasons, clients using authorization code flow and OpenID Connect should not use nonce longer than 64 characters (RP).
• Additional guidance is provided to limit the impact of key compromises in the security considerations section (AS, Ecosystem).

About the OpenID Foundation

The OpenID Foundation (OIDF) is a global open standards body committed to helping people assert their identity wherever they choose. Founded in 2007, we are a community of technical experts leading the creation of open identity standards that are secure, interoperable, and privacy-preserving. The Foundation’s OpenID Connect standard is now used by billions of people across millions of applications. In the last five years, the Financial Grade API has become the standard of choice for Open Banking and Open Data implementations, allowing people to access and share data across entities. Today, the OpenID Foundation’s standards are the connective tissue to enable people to assert their identity and access their data at scale, the scale of the internet, enabling “networks of networks” to interoperate globally. Individuals, companies, governments and non-profits are encouraged to join or participate. Find out more at openid.net.