|February 14, 2024
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 subject to patent rights. OIDF shall not be held responsible for identifying any or all such patent rights.
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. They are all in lower case to rule out the dictionary meaning use of these words so that they can be translated easily. Following is a summary of the keywords.
|shall, shall not
|should, should not
FAPI 1.0 consists of the following parts:
These parts are intended to be used with RFC6749, RFC6750, RFC7636, and OIDC.
FAPI is a highly secured OAuth profile that aims to provide specific implementation guidelines for security and interoperability. The FAPI security profile can be applied to APIs in any market area that requires a higher level of security than provided by standard OAuth or OpenID Connect. Among other security enhancements, this specification provides a secure alternative to screen scraping. Screen scraping accesses user’s data and functions by impersonating a user through password sharing. This brittle, inefficient, and insecure practice creates security vulnerabilities which require institutions to allow what appears to be an automated attack against their applications.
This document is Part 2 of FAPI Security Profile 1.0 that specifies an advanced security profile of OAuth that is suitable to be used for protecting APIs with high inherent risk. Examples include APIs that give access to highly sensitive data or that can be used to trigger financial transactions (e.g., payment initiation). This document specifies the controls against attacks such as: authorization request tampering, authorization response tampering including code injection, state injection, and token request phishing. Additional details are available in the security considerations section.
Although it is possible to code an OpenID provider and relying party from first principles using this specification, the main audience for this specification is parties who already have a certified implementation of OpenID Connect and want to achieve a higher level of security. Implementers are encouraged to understand the security considerations contained in Section 8.7 before embarking on a ‘from scratch’ implementation.
This part of the document specifies the method of
This document is applicable to higher risk use cases which includes commercial and investment banking and other similar industries.
The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.
Part1 FAPI Security Profile 1.0 - Part 1: Baseline
RFC6749 - The OAuth 2.0 Authorization Framework
RFC7636 - Proof Key for Code Exchange by OAuth Public Clients
OIDC - OpenID Connect Core 1.0 incorporating errata set 1
RFC8705 - OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access Tokens
JARM - JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)
PAR - OAuth 2.0 Pushed Authorization Requests
JAR - OAuth 2.0 JWT Secured Authorization Request
For the purpose of this document, the terms defined in RFC6749, RFC6750, RFC7636, OpenID Connect Core and ISO29100 apply.
API – Application Programming Interface
CSRF - Cross Site Request Forgery
FAPI - Financial-grade API
HTTP – Hyper Text Transfer Protocol
OIDF - OpenID Foundation
REST – Representational State Transfer
TLS – Transport Layer Security
API resources may contain sensitive data and/or have increased security requirements. In order to fulfill different security needs, FAPI Security Profile 1.0 defines an advanced profile that is beyond the baseline security requirements defined in the Part 1: Baseline document.
As a profile of the OAuth 2.0 Authorization Framework, this document mandates the following for the advanced profile of the FAPI Security Profile 1.0.
A confidential client shall support the provisions specified in clause 5.2.3 and 5.2.4 of FAPI Security Profile 1.0 - Part 1: Baseline, except for RFC7636 support.
In addition, the confidential client
parameter as defined in Section 6 of OIDC in
the authentication request;
scope parameters/values using the OAuth 2.0 request syntax
as required by Section 6.1 of the OpenID Connect specification if not
aud claim in the request object as the
OP’s issuer identifier URL;
exp claim in the request object that has
a lifetime of no longer than 60 minutes;
nbf claim in the request object;
S256 as the code challenge method if using PAR; and
parameter/value using the OAuth 2.0 request syntax to the authorization
endpoint, as required by Section 5 of JAR, if using PAR.
In addition, if the
code id_token is used, the client
openid into the
scope parameter in order to activate OIDC
s_hash value is equal to the value
calculated from the
state value in the authorization
response in addition to all the requirements in 184.108.40.206 of OIDC;
and NOTE: This enables the client to verify that the
authorization response was not tampered with, using the ID Token as a
In addition, if the
code is used in conjunction with the
jwt, the client
The FAPI endpoints are OAuth 2.0 protected resource endpoints that return protected information for the resource owner associated with the submitted access token.
The protected resources supporting this document
The client supporting this document shall support the provisions specified in clause 6.2.2 of FAPI Security Profile 1.0 - Part 1: Baseline.
As a profile of the OAuth 2.0 Authorization Framework, this specification references the security considerations defined in Section 10 of RFC6749, as well as RFC6819 - OAuth 2.0 Threat Model and Security Considerations, which details various threats and mitigations. The security of OAuth 2.0 has been proven formally - under certain assumptions - in OAUTHSEC. A detailed security analysis of FAPI Security Profile 1.0 can be found in FAPISEC.
There is no way that the client can find out whether the resource access was granted for a bearer or sender-constrained access token. The two differ in the risk profile and the client may want to differentiate them. The protected resources that conform to this document differentiate them. The protected resources that conform to this document shall not accept a bearer access token. They shall only support sender-constrained access tokens via RFC8705.
As confidential information is being exchanged, all interactions shall be encrypted with TLS (HTTPS).
Section 7.1 of FAPI Security Profile 1.0 - Part 1: Baseline shall apply, with the following additional requirements:
authorization_endpoint, the authorization
server MAY allow additional cipher suites that are permitted by the
latest version of BCP195, if necessary to
allow sufficient interoperability with users’ web browsers or are
required by local regulations. NOTE: Permitted cipher
suites are those that BCP195 does not explicity
say MUST NOT use.
TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 cipher suites, key
lengths of at least 2048 bits are required.
For JWS, both clients and authorization servers
For JWE, both clients and authorization servers
To achieve the full security benefits, it is important the implementation of this specification, and the underlying OpenID Connect and OAuth specifications, are both complete and correct.
The OpenID Foundation provides tools that can be used to confirm that an implementation is correct:
The OpenID Foundation maintains a list of certified implementations:
Deployments that use this specification should use a certified implementation.
An attacker could prepare an authorization request URL and trick a victim into authorizing access to the requested resources, e.g. by sending the URL via e-Mail or utilizing it on a fake site.
OAuth 2.0 prevents this kind of attack since the process for obtaining the access token (code exchange, CSRF protection etc.) is designed in a way that the attacker will be unable to obtain and use the token as long as it does not control the victim’s browser.
However, if the API allows execution of any privileged action in the course of the authorization process before the access token is issued, these controls are rendered ineffective. Implementers of this specification therefore shall ensure any action is executed using the access token issued by the authorization process.
For example, payments shall not be executed in the authorization process but after the client has exchanged the authorization code for a token and sent an “execute payment” request with the access token to a protected endpoint.
This profile requires both clients and authorization servers to
verify payloads with keys from the other party. The AS verifies request
private_key_jwt assertions. The client verifies
ID Tokens and authorization response JWTs. For AS’s this profile
strongly recommends the use of JWKS URI endpoints to distribute public
keys. For clients 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 AS
jwks_uri can be found in RFC8414, while the
definition of the client
jwks_uri can be found in RFC7591.
In addition, this profile
jwks_uri endpoints shall be served over
jku should not be used; and
The use of RFC8705 for client authentication and sender constraining access tokens brings significant security benefits over the use of shared secrets. However in some deployments the certificates used for RFC8705 are issued by a certificate authority at an organization level rather than a client level. In such situations it may be common for an organization with multiple clients to use the same certificates (or certificates with the same DN) across clients. Implementers should be aware that such sharing means that a compromise of any one client, would result in a compromise of all clients sharing the same key.
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
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:
kid that matches the
in the JOSE header;
crv that corresponds
to the message being verified.
There are many factors to be considered in terms of privacy when implementing this document. However, since this document is a profile of OAuth and OpenID Connect, all of them are generic and applies to OAuth or OpenID Connect and not specific to this document. Implementers are advised to perform a thorough privacy impact assessment and manage identified risks appropriately.
NOTE: Implementers can consult documents like ISO29100 and [ISO29134] for this purpose.
Privacy threats to OAuth and OpenID Connect implementations include the following:
policy_url or by other means can be inappropriate.
These can be mitigated by choosing appropriate options in OAuth or
OpenID, or by introducing some operational rules. For example, “Attacker
observing personal data in authorization request” can be mitigated by
either using authorization request by reference using
request_uri or by encrypting the request object. Similarly,
“Attacker observing personal data in authorization endpoint response”
can be mitigated by encrypting the ID Token or JARM response.
The following people contributed to this document:
This specification adds the following values to the “JSON Web Token Claims” registry established by RFC7519.
The following are non-normative examples of various objects compliant with this specification, with line wraps within values for display purposes only.
The examples signed by the client may be verified with the following JWK:
The examples signed by the server may be verified with the following JWK:
which when decoded has the following body:
"scope": "openid payments",
"response_type": "code id_token",
which when decoded has the following body:
which when decoded has the following body:
Copyright (c) 2023 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.