APIdays Paris 2019 : Financial-grade API (FAPI) Security Profile

© Hitachi, Ltd. 2019. All rights reserved.
What are protected and secured by security requirements
for APIs providing financial services
< from implementer’s perspective >
APIdays Paris 2019 @ Beffroi de Montrouge, France
Hitachi, Ltd.
OSS Solution Center
10 December 2019
Takashi Norimatsu

1© Hitachi, Ltd. 2019. All rights reserved.
Self Introduction
Engaging in :
◼ providing support services about OSS
◼ implementing and contributing promising features to OSS
The current works :
 contributing WebAuthn support to keycloak
 making keycloak pass FAPI’s conformance tests to get FAPI Certificate
Takashi Norimatsu (tnorimat in github) :
OSS Solution Center, Hitachi, Ltd.
@ Yokohama, Japan
* Yokohama : the 2nd largest city in Japan by population, about 35km south west from Tokyo

1. Security Profiles for APIs Providing Financial Services
2. Topics in Detail about FAPI Security Profile
Contents
2
3. Implementing FAPI Security Profile to OSS (keycloak)

1. Security Profiles
for APIs Providing Financial Services

1-1 Motivation for Securing API
As the use of the fintech has spread, some financial
institutions have begun to provide their financial services via
their APIs to their consumers.
(E.g. OpenBanking in UK)
The caller (third party app) of the API can access and treat
consumers’ properties so that the API should be accessed in
the secure way. There is a case that securing such the API is
required by the law.
(E.g. EU PSD2)

1-2 Security Profile for Securing API
Security Profile :=
Determining proper usage of security standards to meet
the requirements by considered use case.
OAuth 2.0 (RFC 6749)
OAuth 2.0 is a framework rather than a protocol. (protocol for protocol)
-> Various usage is allowed.
E.g. :
Authz code request’s parameter “state” is RECOMMENDED in RFC 6749.
But in some use case, it should be REQUIRED for preventing session
hijacking, XSRF.

1-3 Financial-grade API (FAPI) Security Profile
Financial-grade API(FAPI) Security Profile :=
OAuth 2.0/OpenID Connect(OIDC) based security profile
for securing APIs providing financial services.
Read-Only API Security Profile:
https://openid.net/specs/openid-financial-api-part-1-ID2.html
Read and Write API Security Profile:
https://openid.net/specs/openid-financial-api-part-2-ID2.html
Certificate Program:
https://openid.net/certification/
Certified Financial-grade API (FAPI) OpenID Providers

1-4 Open Banking Security Profile
Open Banking Security Profile :=
FAPI Security Profile based security profile for securing
APIs providing financial services in the context of the
Open Banking Ecosystem.
Redirect-flow (use HTTP redirect for user authentication/consent) :
https://bitbucket.org/openid/obuk/src/master/uk-openbanking-security-profile.md
Decoupled-flow (not use HTTP redirect for user authentication/content) :
https://openid.net/specs/openid-financial-api-ciba.html
Conformance Certificate :
https://openbanking.atlassian.net/wiki/spaces/DZ/pages/126321042/Open+Bankin
g+Security+Profile+Conformance

2. Topics in Detail about FAPI Security Profile

2-1 FAPI Flow for the first API Access
1. Authz Code Request
User/Browser Client App Authz Server API Server
2. User Authentication
(User Consent)
3. Authz Code Response
5. API Access
4. Token Request
(Client Authentication)
redirect
redirect
[Phase]
FAPI Flow for the first API Access :
based on and complies with OAuth 2.0 Authorization Code Grant and OIDC Hybrid Flow.
Phase 3 and 5 are required in this flow,
but out of scope of OAuth 2.0
Authorization Code Grant and OIDC
Hybrid Flow.
Instead of that, FAPI describes its own
security requirements in phase 3 and 5.
Authz Code Request / Response :
Client App receives the authz code
indicating that a user was authenticated
and authorized the API access to Client
App in the range of determined scope.
Token Request / Response :
In return to the authz code, Client App
receives an access token which has the
right to access the API in the range of
determined scope.
authz code
access token
authz code
access token

redirect
redirect
Why pure OAuth 2.0 is not appropriate ?
Because the following problems may arise :
< Fraudulent Token Acquisition & Exercise >
The attacker can get the victim’s access token
and use it for API access. (vise versa)
How to resolve these problems?
Apply FAPI Security Profile. If you want to
know how to do that in detail, please read
the FAPI and its related specifications.
FAPI Read Only, FAPI Read Write, RFC
6749, 6750, 6819, 7521, 7523, 7636, 7515,
7616, 7617, 7618, 7662, BCP195, draft-ietf-
oauth-mtls, OIDC core, X.1254, etc…
…

redirect
redirect
… I’ve read them and understood what those are,
but still not sure what can be achieved by them.
Basically, FAPI intends to achieve the following 2 points
to guard against Fraudulent Token Acquisition :
<Authentication>
The only legitimate entities communicate each other
and authenticated in highly credible manner.
<Message Integrity/Authentication>
They confirm that the received message is not
tampered and generated by the legitimate entity in the
current communication context.
OK, as a whole. To do so, what does FAPI check
in each communication phase in the flow?
And, the following 1 points to guard against
Fraudulent Token Exercise :
<Token Sender Constraint>
The only Client App who received the token from
Authz Server can access API by this token.

redirect
redirect
* Request not tampered.
* Request generated by legitimate Client App.
* User authenticated by highly credible way.
* Response not tampered.
* Response generated by legitimate Authz Server.
* Token received by legitimate Client App.
* Token exercised by legitimate Client App.
[What FAPI checks in each phase]
(User Consent)
5. API Access
4. Token Request
[Phase]
* Client App authenticated by highly credible way.

2-5 Phase 1 : Securing Authz Code Request
redirect
redirect
(User Consent)
5. API Access
4. Token Request
[Phase]

2-6 Phase 1 : Securing Authz Code Request
OpenID Connect - Request Object
Authz Server can confirm :
which Client App created the request.
Request Object := JWT including protocol parameters Client App wants to tell to
Authz Server and signed by Client App’s private key in asymmetric cryptography.
User/Browser Client App Authz Server
redirect
Generate parameters
(including client_id).
Enclose them in
request object.
Sign it by client app’s
private key.
Verify it by client
app’s public key.
HTTP redirect is used to
involve the user in the flow for
User Authentication and
Consent so that parameters
from Client App’s are sent as
query parameters indirectly.
E.g. client_id for
Client App’s ID in
OAuth 2.0 context.
Compare query
parameters with
ones in request
object.
[Phase]
scope
query
parameter
scope
state state
query
params request
object
whether the request was not modified.
client_id client_id
client_id
The way to get Client App’s public key by
client_id:
* Client App registers it to Authz Server In
advance.
* Client App provides API and registers its
URI to Authz Server in advance.
Copy
Get client app’s
public key.
FAPI does not permit RSASSA-PKCS1_v1_5
based algorithm (e.g. RS256) for signing.
Instead of it, FAPI allows ECDSA or RSASSA-
PSS based algorithm (e.g. ES256, PS256).
request
object
Tamper-prone Tamper-resistant

2-7 Phase 2 : User Authentication in High Credibility
redirect
redirect
(User Consent)
5. API Access
4. Token Request
[Phase]

User/Browser
Authz Server
(WebAuthn RP)
2-8 Phase 2 : User Authentication in High Credibility
W3C Web Authentication (WebAuthn) - MFA
WebAuthn := Asymmetric Cryptography used Web based authentication standard
by W3C achieving Password-less and Multi-Factor Authentication.
WebAuthn
Authenticator
Authenticate user by 2nd
factor (biometrics) locally.
Generate authenticator assertion
response including user’s public key ID.
Sign it by user’s
private key.
User was authenticated by
multifactor authentication.
[Phase]
(User Consent)
Authenticate user by 1st
factor (password).
user ID
authentication/consent
Need to register user’s public key in
Authz Server in advance by
WebAuthn’s manner (Registration).
FAPI does not require WebAuthn itself.
FAPI requires Level of Assurance (LoA) 3
defined in ITU-T X.1254 (to say shortly, MFA).
WebAuthn is a promising candidate satisfying it.
authenticator
assertion response
user’s
private key
user ID
(handle)
Verify it by user’s
public key. user’s
public key
Compare user ID by 1st factor
authentication with one by
2nd factor authentication.
username/
password
authentication
fingerprint
Due to WebAuthn
Authenticator’s nature, its
authentication factor is
basically “ownership factor”.

2-9 Phase 3 : Securing Authz Code Response
redirect
redirect
(User Consent)
5. API Access
4. Token Request
[Phase]

2-10 Phase 3 : Securing Authz Code Response
OIDC Hybrid Flow ID Token as Detached Signature
ID Token as Detached Signature := JWT including hash values of protocol
parameters sent as query parameters and signed by Authz Server’s private
key in asymmetric cryptography.
Client App can confirm :
whether the response was not modified.
redirect
Calculate hash
values of params.
Enclose them in
ID Token.
Sign it by authz
server’s private key.
Verify it by authz
server’s public key.
Compare the hash values
of query parameters with
ones in ID token.
code
query
parameter
c_hash
state s_hash
[Phase]
I. Authz Code Req/Res Mandatory parameters are
code and state
query
params
ID
token
Client App can confirm :
which Authz Server created the response.
Get authz server’s
public key .The way to get Auth Server’s public key by
ID Token :
* Authz Server provides API and advertises it
by Server Metadata (.well-known endpoint).
* Client App can know this endpoint by ID
Token’s “iss” claim.
* Client App can know key ID by ID Token’s
JOSE header’s “kid” claim.
Calculate
hashvalue
Tamper-prone Tamper-resistant
ID
token

2-11 Phase 4 : Securing Token Request / Response
redirect
redirect
(User Consent)
5. API Access
4. Token Request
[Phase]

User/Browser (Public) Client App Authz Server
redirect
Proof Key for Code Exchange (PKCE) for Public Client
Generate temporal credential
(code_verifier).
Calculate its hash value and send it
as Authz code request’s parameter
(code_challenge).
redirect
Generate authz code,
bind with
code_challenge and
send it as authz code
response’s parameter.
Send authz code
along with temporal
credential
(code_verifier).
The sender of the authz code
in Token Request
||
The receiver of the authz code
in Auth Code Response
[Phase]
(User Consent)
4. Token Request
I. Authz Code Req/Res
II. Token Req/Res
bind
authz
code
PKCE:= Method for Public Client to
make Authz Server confirm the
sender of the authz code in Token
Request is the receiver of the auth
code in Authz Code Response in
the context of authz code grant by
cryptographic hash function.
</>
Compare the hash values of received
code_verifier with code_challenge bound
with received authz code.
code_challenge
code_verifier
CC
C
C
can not store
credential
securely…
Leveraging that facts that only
Client App knows code_verifier
and it is impractical to calculate it
from code_challenge.

Mutual TLS for OAuth Client Authentication for Confidential Client
redirect
redirect Generate authz code and bind it with
client_id.
(User Consent)
4. Token Request
II. Token Req/Res
In TLS layer, Client App is
authenticated by client certificate
[Phase]
client_id
bind
C
authz code
client cert
Resolve the ID of Client App in
X.509 context (DN, SAN) to the
one in OAuth 2.0 context (client_id).
Compare client_id resolved
from client cert with the one
bound with authz code.
Leveraging client authentication
by PKI based client certificate
in TLS layer, more credible than
secret based authentication.
DN or
SAN
TLS layer
X.509 cert
OAuth layer
client_id
Client App ID
C
C
C
in Token Request
||
Client App was authenticated
by highly credible way.

OAuth Client Authentication by Signed JWT for Confidential Client
redirect
redirect
client_id
(User Consent)
4. Token Request
II. Token Req/Res
[Phase]
authz code
bind
Generate authz
code and bind it
with client_id.
Generate client assertion
enclosing client_id.
Sign it by client’s
private key
client assertion
Verify it by client
app’s public key
Get client app’s
public key
The way to get Client App’s public key by client_id:
* Client App registers it to Authz Server in advance.
* Client App provides API and registers its URI to Authz
Server in advance.
Compare client_id from client assertion
and the one bound with authz code.
Leveraging asymmetric cryptography based client
authentication, more credible than secret based
authentication.
Same as Request Object
FAPI does not permit RSASSA-PKCS1_v1_5 based
algorithm (e.g. RS256) for signing.
Instead of it, FAPI allows ECDSA or RSASSA-PSS based
algorithm (e.g. ES256, PS256).
C
C
C
C
in Token Request
||
Client App was authenticated by
highly credible way.

2-15 Phase 5 : Securing API Access by Access Token
redirect
redirect
(User Consent)
3. Auth Code Response
5. API Access
4. Token Request
[Phase]

2-16 Phase 5 : Securing API Access
Mutual-TLS Client Certificate-Bound Access Tokens - JWT
Client App Authz Server API Server
C
5. API Access
authz
code
Generate access token as JWT
in return for authz code.client
cert
Client cert’s hash value is
enclosed into the access token
as "cnf" - "x5t#S256" claim
Access token is signed by
authz server’s private key
Access token is verified
by authz server’s public
key
Compare hash value of
client cert enclosed in it
and the one calculated
from the received client
cert here.
4. Token Request
II. Token Req/Res
III. API Access
API Server can confirm :
The sender of the Access Token
||
The receiver of the Access Token
the Authz Server issued it to in
Token Request
Get authz server’s
public key
The way to get Auth Server’s public key by
Access Token :
* API Server can know this endpoint by
Access Token’s “iss” claim.
* API Server can know key ID by Access
Token’s JOSE header’s “kid” claim.
C
FAPI requires Holder-of-Key Token.
This is one way of achieving it.
Same as ID Token as Detached Signature
Same as ID Token as Detached Signature
access token

2-17 Phase 5 : Securing API Access
Mutual-TLS Client Certificate-Bound Access Tokens - Introspect
Client App Authz Server API Server
C
5. API Access
authz
code
Generate access token as JWT
in return for authz code.client
cert
Client cert’s hash value is
enclosed into the access token
as "cnf" - "x5t#S256" claim
Access token is signed by
authz server’s private key
Compare hash value of
client cert returned
from authz server and
the one calculated from
the received client cert
here.
4. Token Request
II. Token Req/Res
III. API Access
The way to know Auth Server’s Token
Introspect Endpoint :
* API Server can know this endpoint by
Access Token’s “iss” claim.
C
Token Introspection
Verify access
token and return
hash value
enclosed in it.
access token
Send access token to authz server
to get hash value enclosed it.
Not want to verify and parse JWT…
Delegate this work to Authz Server!
API Server can confirm :
The sender of the Access Token
||
The receiver of the Access Token
the Authz Server issued it to in
Token Request

3. Implementing FAPI Security Profile to OSS

3-1 What is keycloak
An OSS for Identity Management, community is led by Red Hat: www.keycloak.org
LDAP
Active
Directory
RDB
Identity Federation
OpenID Connect, OAuth2.0, SAML
Social Login
(Identity Brokering)
Identity Management
Authentication
can work as Authz Server!

3-2 Support FAPI for keycloak
(*) managed and presented by OpenID Foundation
Develop
✓ Clarify FAPI’s requirements keycloak does not satisfy
✓ Implement features satisfying such FAPI’s requirements to keycloak
Merged
✓ Issue pull requests to keycloak to be reviewed and approved
✓ Make them merged onto keycloak
Certified
◼ Pass all FAPI conformance tests against keycloak
 Get certificate confirming that keycloak complies with Financial- grade API
(FAPI) OpenID Providers (*)
Hitachi, Ltd. has been working for it, and Nomura Research Institute, Ltd. joined it from
“Certified” step.
We are now already in “Certified” step, working in https://github.com/jsoss-sig/keycloak-fapi.
We are happy if you could contribute to it.

3-3 FAPI: Created and Merged Pull Requests to keycloak
# JIRA Ticket Description Pull Request Included Version
1 KEYCLOAK-2604 Support RFC 7636 Proof Key for Code Exchange (PKCE) 3831 3.1.0
2 KEYCLOAK-5661 Return the list of allowed scopes with the issued access token 4527 3.4.0
3 KEYCLOAK-5811 Support client authentication in client_secret_jwt 4835 4.0.0
4 KEYCLOAK-6700 Support s_hash 5022 4.0.0
5 KEYCLOAK-6771 Support Holder of Key mechanism for tokens 5083 4.0.0
6 KEYCLOAK-7451 Support server metadata for PKCE 5228 4.0.0
7 KEYCLOAK-7959 Support Holder of Key mechanism for tokens in reverse proxy deployed
environment
5418 4.2.0
8 KEYCLOAK-6770 Support signature algorithm ES256/384/512 for tokens 5533 4.5.0
9 KEYCLOAK-8460 Support signature algorithm ES256/384/512 for request object 5603 4.7.0
10 KEYCLOAK-9756 Support signature algorithm PS256/384/512 for tokens and request object 5974 6.0.0
11 KEYCLOAK-10747 Explicit Proof Key for Code Exchange Activation Settings 6135 7.0.0
12 KEYCLOAK-6768 Support signed and encrypted ID token 6237 7.0.0
13 KEYCLOAK-9360 Two factor authentication with W3C Web Authentication - WIP 1st impl phase 6248 8.0.0
14 KEYCLOAK-11743 Update to webauthn4j 0.9.14.RELEASE and add apache-kerby-asn1:2.0.0
dependency
6401 8.0.0
15 KEYCLOAK-11372 Support for attestation statement verification 6449 8.0.0

3-4 FAPI: Issues to pass Conformance Test
# JIRA Ticket Description Pull Request Included Version
1 KEYCLOAK-11251 ES256 or PS256 support for Client Authentication by Signed JWT 6414 8.0.0
2 KEYCLOAK-11252 Implement Server Metadata of OAuth 2.0 Mutual TLS Client Authentication 6351 8.0.0
3 KEYCLOAK-11253 Advertise "acr" claim in "claims_supported" Server Metadata 6354 8.0.0
4 KEYCLOAK-11254 Enforce some types of OIDC Hybrid Flow to a client TBD TBD
5 KEYCLOAK-11255 Request Object : check "exp" claim and return an appropriate error if not TBD TBD
6 KEYCLOAK-11256 Request Object : check “scope" claim and return an appropriate error if not TBD TBD
7 KEYCLOAK-11257 Request Object : check “state" claim and return an appropriate error if not TBD TBD
8 KEYCLOAK-11258 Request Object : check “nonce" claim and return an appropriate error if not TBD TBD
9 KEYCLOAK-11259 Request Object : check whether a request object includes "redirect_uri" claim
and return an appropriate error if not
TBD TBD
10 KEYCLOAK-11260 Request Object : check whether a request object has expired based on "exp"
claim and return an appropriate error if so
TBD TBD
11 KEYCLOAK-11261 Request Object : check whether a request object's "aud" indicates keycloak
and return appropriate error if not
TBD TBD
12 KEYCLOAK-11262 Request Object : check whether "nonce" as a query parameter matches
"nonce" claim in a request object and return appropriate error if not match
TBD TBD
13 KEYCLOAK-11263 401 Status Response on OAuth 2.0 Mutual TLS Client Authentication Error TBD TBD

3-5 Consideration on Implementation - from Client App side
 Client App needs to register its public key (or an endpoint providing it) to Authz
Server for a request object and client authentication by a signed JWT. What
happens if this registration is compromised?
→ It impairs the protection of FAPI totally. Client Registration Process must also
be secured.
 In Authz Code Request phase, only a request object seems to be adequate and
query parameters seems not to be sent. Why these are still sent?
→ To conform to OAuth 2.0 and OIDC. FAPI Security Profile has been developed
to conform to OAuth 2.0 and OIDC strictly.
 In Authz Code Response phase, it seems to be adequate that all parameters are
enclosed in ID token. Why these parameter are still sent as query parameters?
→ The same above.

3-6 Consideration on Implementation - Holder-of-Key Token
 Should a refresh token be Holder-of-Key token the same as an access token?
→ I’ve implemented so. If not, an attacker might get the refreshed access token.
 Should JWT based Holder-of-Key token be signed by Authz Server?
→ Yes. If not, an attacker can modify “x5t#S256” to pass verification on API Server.
 How to achieve Holder-of-Key token if a reverse proxy sit in front of Authz Server?
→ I’ve implemented that Authz Server receives the client cert from the reverse proxy.
 What happens if the client cert is invalidated (expired, revoked) ?
→ The access token becomes useless. The user needs to retry the long journey of
the flow, which annoys the user.
→→ Another idea : Client ID bound token (OB Security Profile style)
The client ID(DN/SAN) is invariant against updating the client cert.

Concluding Remarks
✓ Accessing API providing financial services need to be secure.
✓ FAPI Security Profile realizes it.
✓ FAPI Security Profile standard documents describe mainly what to do.
Here explained what can be achieved by that in detail.
✓ Told Insights gained by implementing FAPI Security Profile to keycloak.

Takashi Norimatsu
10 December 2019
Hitachi, Ltd.
OSS Solution Center
END
APIdays Paris 2019 @ Beffroi de Montrouge, France
What are protected and secured by security requirements for APIs
providing financial services < from implementer’s perspective >
34

Trademarks
• OpenID is a trademark or registered trademark of OpenID Foundation in the
United States and other countries.
• GitHub is a trademark or registered trademark of GitHub, Inc. in the United
States and other countries.
• Red Hat is a trademark or registered trademark of Red Hat, Inc. in the United
• Twitter is a trademark or registered trademark of Twitter,Inc. in the United
• Facebook is a trademark or registered trademark of Facebook,Inc. in the
United States and other countries.
• Other brand names and product names used in this material are trademarks,
registered trademarks, or trade names of their respective holders.

APIdays Paris 2019 : Financial-grade API (FAPI) Security Profile

APIdays Paris 2019 : Financial-grade API (FAPI) Security Profile

More Related Content

What's hot

Similar to APIdays Paris 2019 : Financial-grade API (FAPI) Security Profile

More from Hitachi, Ltd. OSS Solution Center.

Recently uploaded

APIdays Paris 2019 : Financial-grade API (FAPI) Security Profile