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.
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.
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 participants). 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 has 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.
Financial-grade API consists of the following parts:
Future parts may follow.
These parts are intended to be used with [RFC6749], [RFC6750], [RFC7636], and [OIDC].
Fintech is an area of future economic growth around the world and Fintech organizations need to improve the security of their operations and protect customer data. It is common practice of aggregation services to use screen scraping as a method to capture data by storing users' passwords. This brittle, inefficient, and insecure practice creates security vulnerabilities which require financial institutions to allow what appears to be an automated attack against their applications and to maintain a whitelist of aggregators. A new draft standard, proposed by this workgroup would instead utilize an API model with structured data and a token model, such as OAuth [RFC6749, RFC6750].
The Financial-grade API aims to provide specific implementation guidelines for online financial services to adopt by developing a REST/JSON data model protected by a highly secured OAuth profile. The Financial-grade API security profile can be applied to online services in any market area that requires a higher level of security than provided by standard OAuth or OpenID Connect.
This document is Part 1 of FAPI that specifies the Financial-grade API and it provides a profile of OAuth that is suitable to be used in the access of read-only financial data and similar use cases.
A higher level of security profile is provided in Part 2, suitable for read and write financial access APIs and other similar situations where the risk is higher.
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. Implementors are encouraged to understand the security considerations contained in section 7.6 before embarking on a 'from scratch' implementation.
The key words "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 key words are not used as dictionary terms such that any occurrence of them shall be interpreted as key words and are not to be interpreted with their natural language meanings.
2. Normative references
3. Terms and definitions
4. Symbols and abbreviated terms
5. Read-only API security profile
5.2. Read-only API security provisions
5.2.2. Authorization server
220.127.116.11. Returning authenticated user's identifier Authorization server
5.2.3. Public client
5.2.4. Confidential client
6. Accessing Protected Resources
6.2. Read-only access provisions
6.2.1. Protected resources provisions
6.2.2. Client provisions
7. Security considerations
7.1. TLS considerations
7.2. Message source authentication failure
7.3. Message integrity protection failure
7.4. Message containment failure
7.4.1. Authorization request and response
7.4.2. Token request and response
7.4.3. Resource request and response
7.5. Native Apps
7.6. Incomplete or incorrect implementations of the specifications
8. Privacy considerations
8.1. Privacy by design
8.2. Adhering to privacy principles
§ Authors' Addresses
This document specifies the method for an application to:
The following referenced documents are indispensable for the application of this document. For dated references, only the edition cited applied. For undated references, the latest edition of the referenced document (including any amendments) applies.
[ISODIR2] - ISO/IEC Directives Part 2 [ISODIR2]: http://www.iso.org/sites/directives/2016/part2/index.xhtml
[RFC4122] A Universally Unique IDentifier (UUID) URN Namespace [RFC4122]: https://tools.ietf.org/html/rfc4122
[RFC6749] - The OAuth 2.0 Authorization Framework [RFC6749]: https://tools.ietf.org/html/rfc6749
[RFC6750] - The OAuth 2.0 Authorization Framework: Bearer Token Usage [RFC6750]: https://tools.ietf.org/html/rfc6750
[RFC7636] - Proof Key for Code Exchange by OAuth Public Clients [RFC7636]: https://tools.ietf.org/html/rfc7636
[RFC6125] - 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) [RFC6125]: https://tools.ietf.org/html/rfc6125
[BCP212] - OAuth 2.0 for Native Apps [BCP212]: https://tools.ietf.org/html/bcp212
[RFC6819] - OAuth 2.0 Threat Model and Security Considerations [RFC6819]: https://tools.ietf.org/html/rfc6819
[BCP195] - Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS) [BCP195]: https://tools.ietf.org/html/bcp195
[OIDC] - OpenID Connect Core 1.0 incorporating errata set 1 [OIDC]: https://openid.net/specs/openid-connect-core-1_0.html
[X.1254] - Entity authentication assurance framework [X.1254]: https://www.itu.int/rec/T-REC-X.1254
[MTLS] - OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access Tokens [MTLS]: https://tools.ietf.org/html/draft-ietf-oauth-mtls
For the purpose of this document, the terms defined in [RFC6749], [RFC6750], [RFC7636], [OpenID Connect Core][OIDC] apply.
API – Application Programming Interface
CSRF - Cross Site Request Forgery
FAPI - Financial-grade API
HTTP – Hyper Text Transfer Protocol
REST – Representational State Transfer
TLS – Transport Layer Security
The OIDF Financial-grade API (FAPI) is a REST API that provides JSON data. These APIs are protected by the OAuth 2.0 Authorization Framework that consists of [RFC6749], [RFC6750], [RFC7636], and other specifications.
Read-only access is generally viewed to pose a lower risk than the write access and as such, the characteristics required of the tokens are different and the methods to obtain tokens are explained separately.
Read-only access is a lower risk scenario compared to the write access; therefore the protection level can also be lower. However, since the FAPI can provide potentially sensitive information, it requires more protection level than a basic [RFC6749] requires.
As a profile of the OAuth 2.0 Authorization Framework, this document mandates the following to the read-only API of the FAPI.
The authorization server
Further, if it is desired to provide the authenticated user's identifier to the client in the token response, the authorization server:
A public client
In addition to the provisions for a public client, a confidential 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 resource server with the FAPI endpoints
The client supporting this document
As confidential information is being exchanged, all interactions shall be encrypted with TLS (HTTPS).
The recommendations for Secure Use of Transport Layer Security in [BCP195] shall be followed, with the following additional requirements:
Authorization request and response are not authenticated. For higher risk scenarios, they should be authenticated. See Part 2, which uses request object to achieve the message source authentication.
The authorization request does not have message integrity protection and hence request tampering and parameter injection are possible. Where such protection is desired, Part 2 should be used.
The response is integrity protected when the ID Token is returned from the authorization endpoint.
In this document, the authorization request is not encrypted. Thus, it is possible to leak the information contained if the web browser is compromised.
Authorization response can be encrypted as ID Token can be encrypted.
It is possible to leak the information through the logs if the parameters were recorded in the logs and the access to the logs are compromised. Strict access control to the logs in such cases should be enforced.
It is possible to leak information through the logs if the parameters were recorded in the logs and the access to the logs are compromised. Strict access control to the logs in such cases should be enforced.
Care should be taken so that the sensitive data will not be leaked through the referrer.
If the access token is a bearer token, it is possible to exercise the stolen token. Since the access token can be used against multiple URIs, the risk of leaking is much larger than the refresh token, which is used only against the token endpoint. Thus, the lifetime of the access token should be much shorter than that of the refresh token. Refer to section 16.18 of [OIDC] for more discussion on the lifetimes of access tokens and refresh tokens.
When native apps are used as either public clients, dynamically registered confidential clients or user-agents receiving the authorization response for a server based confidential client, the recommendations for OAuth 2.0 for Native Apps in [BCP212] shall be followed, with the following additional requirements:
When registering redirect URIs, authorization servers
These requirements mean that FAPI compliant implementations can only support native apps through the use of "Claimed https Scheme URI Redirection".
Note: nothing in this document seeks to disallow fixed urls in the form https://localhost:port-number/callback, as these are particularly useful in non-production systems or in clients used in development, to facilitate faster and easier development.
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.
** NOTE ** The following only has a boiler plate text specifying the general principles. More specific text will be added towards the Final specification.
Stakeholders should follow the privacy principles of ISO/IEC 29100. In particular:
The following people contributed to this document:
|Nomura Research Institute, Ltd.|