Configuring FAPI 1.0

Overview

This page lists the settings a service and a client need for the FAPI 1.0 profiles — Baseline (Part 1) and Advanced (Part 2). Configuring them is not on its own enough: Authlete also has to be told which profile applies to a request. See How to use FAPI feature for that, and Financial-grade API (FAPI) Basics for a tutorial that walks the whole setup end to end.

Service configurations

This section explains how to configure a service to support each FAPI 1.0 profile.

Configurations for Baseline profile

Configure a service as below.

Property	Configuration
FAPI Profile	Enable it.
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 Baseline attribute.

Configurations for Advanced API profile

To support Advanced API profile, you need to configure a service according to the configurations for Baseline API profile and the following additional configurations. (Some configurations for Baseline 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 Advanced attribute.

Client configurations

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

Configurations for Baseline 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 Advanced profile

To support Advanced profile, you need to configure a client according to the configurations for Baseline API profile and the following additional configurations. (Some configurations for Baseline 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 requirements

Once a service and a client are configured, Authlete validates each request against the profile in force. Those checks — what the authorization request, the token request and the request object must carry, for Baseline and for Advanced — are documented as 23 numbered items in Validation in FAPI mode, including:

Topic	Items
Request object: presence, signature, the parameters it must carry, its `exp` and `aud` claims, and its signing algorithm	7–12
`code_challenge` and `code_challenge_method` (PKCE)	13, 14
`acr` as an essential claim	15
Client authentication and the signing algorithm of the client assertion	18, 19
Key size of the client assertion (2048 bits for RSA, 160 for EC)	20
Sender-constrained access tokens	22

Request examples

The requirements above describe what each request has to satisfy. These examples show what they look like on the wire, as the client sends them to the authorization server.

Authorization request, Baseline profile

#
# An example request from a public client.
#
# Note:
#   * scope: 'account' scope has a Baseline 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, Advanced profile

The claims parameter has to carry acr as an essential claim:

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

#
# An example request from a confidential client.
#
# Note:
#   * scope: 'account' scope has an Advanced 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...[omitted]...nPQ

The request parameter above is a signed request object. Its payload has to carry every request parameter, an exp claim, and an aud claim whose value is the service’s issuer identifier:

{
  "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
      }
    }
  }
}

Token request, Baseline profile

#
# 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, Advanced profile

The client also has to present a client certificate to the token endpoint, because TLS Client Certificate Bound Access Tokens is enabled for it.

#
# 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

Topic	See
Scope attributes	Scope attributes
JARM	Enabling JARM

Basic OAuth/OIDC Flows

Advanced Flows

Protocol Extensions

Compliance Profiles

Verifiable Credentials

Overview

Service configurations

Configurations for Baseline profile

Configurations for Advanced API profile

Client configurations

Configurations for Baseline profile

Configurations for Advanced profile

Request requirements

Request examples

Authorization request, Baseline profile

Authorization request, Advanced profile

Token request, Baseline profile

Token request, Advanced profile

​Overview

​Service configurations

​Configurations for Baseline profile

​Configurations for Advanced API profile

​Client configurations

​Configurations for Baseline profile

​Configurations for Advanced profile

​Request requirements

​Request examples

​Authorization request, Baseline profile

​Authorization request, Advanced profile

​Token request, Baseline profile

​Token request, Advanced profile

​Related settings

Overview

Service configurations

Configurations for Baseline profile

Configurations for Advanced API profile

Client configurations

Configurations for Baseline profile

Configurations for Advanced profile

Request requirements

Request examples

Authorization request, Baseline profile

Authorization request, Advanced profile

Token request, Baseline profile

Token request, Advanced profile

Related settings