How to use FAPI feature

For Authlete 2.x documentation, see 2.x version.

Overview

This document explains how to use Financial-grade API (FAPI) feature in Authlete.

FAPI feature is available since Authlete 2.0. If you are using Authlete 2.2+, refer to Financial-grade API (FAPI) Basics.

Introduction

FAPI Support in Authlete

Authlete supports both major versions of the Financial-grade API (FAPI): FAPI 1.0 and FAPI 2.0. FAPI 1.0 defines two security profiles:

Read-only API profile (specified in Part 1)
Read-and-write API profile (specified in Part 2)

Each profile has distinct requirements for authorization servers, meaning the behavior of the authorization server will depend on the specific profile in use. To enable FAPI functionality in Authlete, you must configure your service and client to meet the requirements of the desired profile. Authlete supports two modes for applying FAPI conformance checks:

Static Mode: All incoming requests are evaluated for compliance with the configured FAPI level. While strict, this mode may not be suitable in environments where the authorization server needs to support multiple clients with varying conformance levels.
Dynamic (Runtime) Mode: FAPI conformance checks are applied dynamically based on the OAuth scope provided in each request. This mode is more flexible and allows the authorization server to serve clients with different compliance requirements.

This article focuses on enabling FAPI compliance dynamically at runtime. In this mode, the request parameters sent by the client to the authorization server must be configured properly. Important: Authlete determines whether the FAPI feature is enabled for a request based on these runtime parameters. Even if your service and client configurations satisfy the FAPI requirements, the feature will not be activated if the request parameters are misconfigured. The following steps outline how Authlete determines whether to enable FAPI at runtime:

Extract the scopes included in the request or associated with the request.
Check the attributes of each scope (see Appendix 1) and apply the following logic:

Condition	Authlete Behavior
If the scope has a FAPI read-only attribute (`key = fapi` and `value = r`)	Authlete enforces the read-only API profile.
If the scope has a FAPI read-and-write attribute (`key = fapi` and `value = rw`)	Authlete enforces the read-and-write API profile.
Otherwise	Authlete defaults to regular OAuth 2.0/OIDC flows.

In the following sections, we will see more details of how to configure a service, a client and request parameters for both profiles.

Service configurations

This section explains how to configure a service to support FAPI profiles.

Log in to the Management Console.
Click Create New Service.
On the Service Setup screen:
- Enter a Service Name and Description.
- Select FAPI in FAPI Service Profile.

Configurations for read-only API profile

Configure a service as below.

Property	Configuration
Supported Service Profiles	Choose FAPI.
Supported Client Authentication Methods	Choose at least one of the followings: TLS_CLIENT_AUTH, SELF_SIGNED_TLS_CLIENT_AUTH, CLIENT_SECRET_JWT, PRIVATE_KEY_JWT. Note: If all the FAPI clients communicating with this service are public clients, this configuration is not mandatory.
Supported Scopes	Create at least a scope that has an “read-only” attribute.

Configurations for read-and-write API profile

To support read-and-write API profile, you need to configure a service according to the configurations for read-only API profile and the following additional configurations. (Some configurations for read-only API profile are overridden.)

Property	Configuration
Supported Authentication Context Class References	Set an appropriate value.(e.g. urn:mace:incommon:iap:silver)
Supported Response Types	Choose at least one of the followings: CODE_ID_TOKEN, CODE_ID_TOKEN_TOKEN. Note: If all the FAPI clients communicating with this service use JARM (See Appendix 2), this configuration is not mandatory.
Supported Client Authentication Methods	Choose at least one of the followings: TLS_CLIENT_AUTH, SELF_SIGNED_TLS_CLIENT_AUTH, PRIVATE_KEY_JWT. Note: If all the FAPI clients communicating with this service are public clients, this configuration is not mandatory.
TLS Client Certificate Bound Access Tokens	Choose Supported.
Supported Scopes	Create at least a scope that has an “read-and-write” attribute.

Client configurations

This section explains how to configure a client to support FAPI profiles.

Configurations for read-only API profile

Configure a client as below.

Property	Configuration
Client Authentication Method	If this client is a confidential client, choose one of the followings: TLS_CLIENT_AUTH, SELF_SIGNED_TLS_CLIENT_AUTH, CLIENT_SECRET_JWT, PRIVATE_KEY_JWT.
Redirect Uris	Set a URI starting with https.
JWK Set Content	Note: this configuration is not mandatory if “JWK Set URI” is used. If this client uses PRIVATE_KEY_JWT as its client authentication method, the value of this property must contain a public key for verifying assertion signature and the key must satisfy the requirements in Appendix 3.
JWK Set URI	Note: this configuration is not mandatory if “JWK Set Content” is used. If this client uses PRIVATE_KEY_JWT as its client authentication method, the value of the JWK set pointed by this property must contain a public key for verifying assertion signature and the key must satisfy the requirements in Appendix 3.

Configurations for read-and-write API profile

To support read-and-write API profile, you need to configure a client according to the configurations for read-only API profile and the following additional configurations. (Some configurations for read-only API profile are overridden.)

Property	Configuration
Response Type	Choose at least one of the followings: CODE_ID_TOKEN, CODE_ID_TOKEN_TOKEN. Note: If this client uses JARM (See Appendix 2), this configuration is not mandatory.
Supported Client Authentication Methods	If this client is a confidential client, choose one of the followings: TLS_CLIENT_AUTH, SELF_SIGNED_TLS_CLIENT_AUTH, PRIVATE_KEY_JWT.
TLS Client Certificate Bound Access Tokens	Choose Enabled.
Authorization Response Signature Algorithm	If this client uses JARM, choose one of the followings: PS256, ES256.
Assertion Signature Algorithm	If this client uses PRIVATE_KEY_JWT as its client authentication method, choose one of the followings: PS256, ES256.
Request Object Signature Algorithm	Choose one of the followings: PS256, ES256.
ID Token Signature Algorithm	If this client asks the authorization server for ID tokens, choose one of the followings: PS256, ES256.
User Info Signature Algorithm	If this client uses user info endpoint, choose one of the followings: PS256, ES256.

Request

This section explains how to configure request parameters (for authorization endpoint and token endpoint) to support FAPI profiles.

Authorization request

Authorization request for read-only API profile

Requirements for request parameters

Parameter	Requirement
redirect_uri	Set a URI that satisfies the following requirements: must exactly match one of the pre-registered redirect URIs; must start with https.
state	Required if ‘openid’ scope is not contained in the ‘scope’ request parameters.
code_challenge	Set a value that complies with PKCE (RFC 7636).
code_challenge_method	Must be ‘S256’.
scope	Must include at least a scope that has an “read-only” attribute.

Example

#
# An example request from a public client.
#
# Note:
#   * scope: 'account' scope has a "read-only" attribute.
#   * state: Optional but recommended (OAuth 2.0).
#   * nonce: Required if the 'response_type' request parameter contains
#      'id_token' (OpenID Connect).
#
GET /api/authorization?

response_type=code+id_token&
client_id=285946231596&
redirect_uri=https://my-client.com/callback&
scope=openid+accounts&
code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&
code_challenge_method=S256&
state=mystate&
nonce=mynonce

Authorization request for read-and-write API profile

Requirements for request parameters To support read-and-write API profile, you need to configure request parameters according to the requirements for read-only API profile and the following additional requirements. (Some requirements for read-only API profile are overridden.)

Parameter	Requirements
request	Note: If ‘request_uri’ parameter is used, this requirement is not mandatory. Set a request object that satisfy the requirements in Appendix 4.
request_uri	Note: If ‘request’ parameter is used, this requirement is not mandatory. Set a URL pointing a request object that satisfy the requirements in Appendix 4.
response_type	Set ‘code id_token’ or ‘code id_token token’. Note: If this client always uses JARM, this requirement is not mandatory.
code_challenge	Set a value that complies with PKCE (RFC 7636) if this client is a public client.
code_challenge_method	Must be ‘S256’ if this client is a public client.
scope	Must include at least a scope that has an “read-and-write” attribute.
claims	Must include the ‘acr’ claim as an essential claim (“essential”:true). See example below.

Example claims structure:

{
  "id_token": {
    "acr": {
      "essential": true,
      "values": ["urn:mace:incommon:iap:silver"]
    }
  }
}

Example

#
# An example request from a confidential client.
#
# Note:
#   * scope: 'account' scope has a "read-and-write" attribute.
#   * state: Optional but recommended (OAuth 2.0).
#   * nonce: Required if the 'response_type' request parameter contains
#      'id_token' (OpenID Connect).
#
GET /api/authorization?

response_type=code+id_token&
client_id=291985138172&
scope=openid+payments&
redirect_uri=https://my-client.com/callback&
state=mystate&
nonce=mynonce&
claims={"id_token":{"acr":{"essential":true,"values":["urn:mace:incommon:iap:silver"]}}}&
request=eyJh...[省略]...nPQ

Token request

Token request for read-only API profile

Requirements for request parameters

Parameter	Requirement
client_assertion	If this client uses PRIVATE_KEY_JWT as its client authentication method, the value of this property must contain a public key for verifying assertion signature and the key must satisfy the requirements in Appendix 3.

Example

#
# An example request from a public client.
#
POST /api/token

client_id=285946231596&
grant_type=authorization_code&
code=_vaXlQ_ItUX4hiWzXgOT-Jp9-oVPKGQ6Q6QZu_P2GXw&
redirect_uri=https://my-client.com/callback&
code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

Token request for read-and-write API profile

Parameter	Requirement
client_assertion	If this client uses PRIVATE_KEY_JWT as its client authentication method, the value of this property must be signed with the algorithm specified as ‘Assertion Signature Algorithm’.

Client certificate The client needs to present a client certificate to the token endpoint as ‘TLS Client Certificate Bound Access Tokens’ is enabled for the client. Example

#
# An example request from a confidential client.
#
# Note:
#   * The client uses PRIVATE_KEY_JWT as its client authentication method.
#   * The client needs to present a client certificate to the token endpoint,
#      as 'TLS Client Certificate Bound Access Tokens' is enabled for the client.
#
POST /api/token

client_id=291985138172&
grant_type=authorization_code&
code=YG-gD9v-vmnuKaHkRHcvWq1UxlxT_9vgj28ffxIAX40&
redirect_uri=https://my-client.com/callback&
client_assertion=eyJh...[omitted]...OWg&
client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer

Appendix

1. Scope attributes

See this article.

2. JARM

See this article.

3. Requirements for key size

FAPI Part1 says

Financial Services – Financial API - Part 1, 5.2.2. Authorization Server The authorization server,
…
5. shall require a key of size 2048 bits or larger if RSA
algorithms are used for the client authentication;
6. shall require a key of size 160 bits or larger if elliptic
curve algorithms are used for the client authentication;

Then, a public key for signing a client assertion (JWS) and a private key for verifying the signature must satisfy the following requirements.

Client assertion algorithm type	Requirements for key size
RSA algorithm	The key size must be equal to or larger than 2048 bits.
EC algorithm	The key size must be equal to or larger than 160 bits.
Otherwise	No requirements.

4. Requirements for request objects

FAPI Part2 says

Financial Services – Financial API - Part 2, 5.2.2. Authorization Server The authorization server,
…
1. shall require the request or request_uri parameter to be passed as a JWS signed JWT as in clause 6 of [OIDC];
…
10. shall require that all parameters are present inside the signed request object passed in the request or request_uri parameter;
…
13. shall require the request object to contain an exp claim;
…
15. shall require the aud claim in the request object to be, or to be an array containing, the OP’s Issuer Identifier URL;

Additionally, the following requirements for JWS signature must be satisfied.

Financial Services – Financial API - Part 2, 8.6 JWS algorithm considerations Both clients and authorization servers:
1. shall use PS256 or ES256 algorithms;
2. should not use algorithms that use RSASSA-PKCS1-v1_5 (e.g. RS256);
3. shall not use none;

In summary, in order to support read-and-write API profile, request objects:

Must be signed with the algorithm specified as ‘Request Object Signature Algorithm’.
Must include all the request parameters.
Must include the ‘exp’ claim
Must include the ‘aud’ claim and the value must be the value of ‘Token Issuer Identifier’.

The following example shows the payload of a request object that satisfies the requirements.

{
  "response_type": "code id_token",
  "exp": 1554973000,
  "aud": "https://my-authz-server.com/",
  "client_id": "291985138172",
  "scope": "openid payments",
  "redirect_uri": "https://my-client.com/callback",
  "state": "mystate",
  "nonce": "mynonce",
  "claims": {
    "id_token": {
      "acr": {
        "values": ["urn:mace:incommon:iap:silver"],
        "essential": true
      }
    }
  }
}

Basic OAuth/OIDC Flows

Advanced Flows

Protocol Extensions

Compliance Profiles

Verifiable Credentials

Overview

Introduction

FAPI Support in Authlete

Service configurations

Configurations for read-only API profile

Configurations for read-and-write API profile

Client configurations

Configurations for read-only API profile

Configurations for read-and-write API profile

Request

Authorization request

Authorization request for read-only API profile

Authorization request for read-and-write API profile

Token request

Token request for read-only API profile

Token request for read-and-write API profile

Appendix

1. Scope attributes

2. JARM

3. Requirements for key size

4. Requirements for request objects

​Overview

​Introduction

​FAPI Support in Authlete

​Service configurations

​Configurations for read-only API profile

​Configurations for read-and-write API profile

​Client configurations

​Configurations for read-only API profile

​Configurations for read-and-write API profile

​Request

​Authorization request

​Authorization request for read-only API profile

​Authorization request for read-and-write API profile

​Token request

​Token request for read-only API profile

​Token request for read-and-write API profile

​Appendix

​1. Scope attributes

​2. JARM

​3. Requirements for key size

​4. Requirements for request objects

Overview

Introduction

FAPI Support in Authlete

Service configurations

Configurations for read-only API profile

Configurations for read-and-write API profile

Client configurations

Configurations for read-only API profile

Configurations for read-and-write API profile

Request

Authorization request

Authorization request for read-only API profile

Authorization request for read-and-write API profile

Token request

Token request for read-only API profile

Token request for read-and-write API profile

Appendix

1. Scope attributes

2. JARM

3. Requirements for key size

4. Requirements for request objects