FAPI Support

This section provides details about FAPI 1.0 Advanced Profile (FAPI) support in the Akana Platform, designed to meet the highest security and privacy requirements for financial-grade APIs. The Akana OAuth/OIDC Provider has implemented FAPI features to ensure strong customer authentication, data integrity, and confidentiality while complying with industry standards for financial APIs.

Table of Contents

• Overview of FAPI 1.0 Advanced Profile
• FAPI support in the Akana OAuth/OIDC Provider Domain
  • Configure an Akana OAuth/OIDC Provider Domain with a FAPI Security Profile
  • OpenID Connect Discovery Metadata
  • JWT-Secured Authorization Request (JAR)
    • Error Response for Authorization Request
    • Authentication and Authorization Response
    • Authorization Request Response
    • ID Token as Detached Signature
  • Request JWT-Signed and Encrypted Access Tokens
    • JWT Token Request Validation
    • Error Response for JWT Token Request
    • JWT Token Request Response
  • Revoke JWT Token
• FAPI support in the Akana OAuth Policy
• FAPI Support in the External OAuth Provider Domain
• FAPI requirements for Target APIs
• FAPI requirements for Confidential Clients

Additional resource information

• Signature Algorithms Name Mapping
• Impact on OpenID Connect Relying Party domain

Overview of FAPI 1.0 Advanced Profile

The FAPI 1.0 Advanced Profile is an extension of OAuth 2.0 and OpenID Connect designed to address the rigorous security needs of the financial industry. Built on the FAPI 1.0 Baseline, it adds robust protective measures against credential leaks, phishing, man-in-the-middle attacks, and other vulnerabilities that may occur in high-value transactions.

The key features of FAPI 1.0 Advanced Profile:

• OpenID Connect Discovery (OIDD) & Authorization Server Metadata: The authorization server must distribute authorization metadata, such as the authorization endpoint, using the discovery endpoint. The clients should then request the OpenID Discovery Document (OIDD) using the /.well-known/openid-configuration endpoint, and authorization server metadata using the /.well-known/oauth-authorization-server endpoint.
• Authorization and Consent: The FAPI has strict user consent requirements, allowing end users full control over the data and actions they approve. Implicit grant types are not supported.
• Private Key JWT or Mutual TLS (mTLS) for Client Authentication: Using Private Key JWT (PKI-based authentication) provides a secure client authentication method where clients authenticate using a JSON Web Token (JWT) signed with their private key. This ensures that no sensitive credentials are shared or transmitted during the authentication process, reducing the risk of client credentials being stolen and misused. Alternatively, Mutual Transport Layer Security (mTLS) can be used to strengthen the client authentication process. mTLS ensures that both the client and server authenticate each other using digital certificates. This guarantees that only trusted parties can communicate with the API and prevents impersonation attacks by verifying the identity of the client application.
• JWT-Secured Authorization Request (JAR) and optionally Pushed Authorization Request (PAR): The authorization requests are packaged into signed JWTs (request objects) ensuring the integrity and authenticity of the requests, minimizing the risk of an attacker altering the request. Additionally, the Pushed Authorization Requests (PAR) method allows clients to securely submit their authorization requests to the authorization server before interacting with the user, reducing potential risks during the redirection process.
• ID Token as Detached Signature: Detached signatures provide a mechanism where only the signature is sent with the authorization request, while the payload remains separate. This reduces the risk of exposing sensitive information during transmission. Additionally, this mechanism allows the client to verify the integrity of the code without directly including the original data in the signed message. In the case of OpenID Connect Core, the ID token acts as a detached signature of the issuer to the authorization response. This was an explicit design decision, as the ID token includes hash code and state (if present in request) in c_hash and s_hash claim respectively.
• ID Token Security: To enhance security, FAPI 1.0 Advanced mandates that ID tokens be issued with appropriate audience restrictions and expiration periods. Clients must validate the signature and other claims to confirm the token's legitimacy and validity. Encryption of ID tokens may also be necessary in some cases to prevent unauthorized access to the token's contents.
• JARM (JWT Secured Authorization Response Mode): The authorization responses are returned as signed JWTs, ensuring they cannot be tampered with during transmission. This maintains the integrity and confidentiality of the authorization response, thereby enhancing the overall security of the transaction.
• JWT-Signed and Encrypted Access Tokens: The access tokens and refresh tokens issued as JWTs are cryptographically signed to ensure their integrity. Additionally, optional encryption of the tokens prevents sensitive information from being read or tampered with, providing an extra layer of security.
• Token Binding: Token binding ties access tokens to a specific client and connection, preventing misuse even if a token is intercepted. This enhances session security by ensuring intercepted tokens cannot be used by another client or over a different connection, effectively safeguarding against man-in-the-middle attacks.
• Secure Communication: All communications must use TLS version 1.2 or a more recent, secure version. This configuration should include forward secrecy and measures to prevent replay attacks.
• Non-repudiation: Digital signatures ensure data integrity, preventing any party from denying participation in a transaction. For JWS, both clients and authorization servers must support the PS256 or ES256 algorithms exclusively. For JWE, both clients and authorization servers must not use the RSA1_5 algorithm.
• Sender Constraint Access Token: The sender constraint token binding ties access tokens to a specific client and connection, preventing misuse even if a token is intercepted. This enhances session security by ensuring an intercepted token cannot be used by another client or over a different connection, protecting against man-in-the-middle attacks.

FAPI support in the Akana OAuth/OIDC Provider Domain

The following table outlines the FAPI 1.0 Advanced Features currently supported by the Akana OAuth/OIDC Provider Domain.

Configure an Akana OAuth/OIDC Provider Domain with a FAPI Security Profile

The Business Admin can configure the FAPI security profile when setting up an Akana OAuth/OIDC Provider domain. The Akana OAuth/OIDC provider enforces the advanced security specification of the OpenID standard. Akana currently supports the FAPI 1.0 Advanced (UK Open Banking) security profile. For more information, refer to the Financial-grade API Security Profile 1.0 - Part 1: Baseline.

To configure an Akana OAuth/OIDC provider domain with FAPI, go to More > Admin > Domains > Add Domain and select Akana OAuth/OIDC Provider. On the Details page, provide a name and description for your Akana OAuth/OIDC provider, and then select the checkbox to enable the FAPI security profile. To complete the configuration, follow the steps 5 to 11 under the section How do I set up and configure an Akana OAuth/OIDC Provider domain?

When configuring an Akana OAuth/OIDC Provider domain to enforce FAPI 1.0 Advanced protection with the FAPI security profile enabled, consider the following settings under:

Grant Types tab,

• Enable only the Authorization Code and Client Credentials grant types.
• Set the Access Token Timeout (seconds) value to be less than or equal to 10 minutes. Even if it is set to a value above 10 minutes, the effective timeout will be considered 10 minutes.

Token tab,

• Ensure that the token type is exclusively a JWT Bearer Access Token.
• Set the Issuer in URL format with HTTPS scheme and it must be unique across all the OAuth provider domains and all the tenants.
• The Audience field now supports configurable values, which will be included in the "aud" claim of the access token. Currently, only a single audience value can be set.
• Set the JWT Signing Algorithm for access token to either PS256 (SHA256withRSAandMGF1) or ES256 (SHA256withECDSA).
• If you need to generate an encrypted access token, ensure that the JWT Encryption Key Management Algorithm is not RSA1_5.
• If you are using an external keystore such as a Hardware Security Module (HSM) for signing and decryption, specify the JCA provider for the corresponding HSM. For example, you can configure the JCA Provider values as follows:
  • Signing JCA Provider: nCipherKM
  • Verify JCA Provider: BC
  • Encrypt JCA Provider: SunJCE
  • Decrypt JCA Provider: nCipherKM

OpenID Connect tab,

• Set the ID Token Signing Algorithm to use either PS256 (SHA256withRSAandMGF1) or ES256 (SHA256withECDSA).
• If generating encrypted ID tokens, ensure the ID Token Encryption Key Management Algorithm is not RSA1_5.

Branding tab,

• Use only the HTTPS scheme for the Authorization server URL.

The Security Domain service provides APIs that allow you to manage the security profile for the Akana OAuth/OIDC Provider domain on the platform. To learn more, see Security Domain Service.

OpenID Connect Discovery Metadata

With the FAPI security profile enabled on the Akana OAuth/OIDC Provider domain, the discovery endpoint will return metadata about the Akana OAuth/OIDC Provider, in accordance with the FAPI 1.0 Advanced security profile requirements. The OpenID Connect specification defines a discovery mechanism, called OpenID Connect Discovery, where it publishes its OpenID Provider Metadata at a well-known URL:

 https://server.com/.well-known/openid-configuration

The URL returns a JSON response that describes the OpenID endpoints. This includes a list of supported scopes and claims and other relevant details such as:

• The response_types_supported includes code id_token.
• The id_token_signing_alg_values_supported must be configured from the domain configuration to either PS256 or ES256.
• The request_object_signing_alg_values_supported only supports PS256 and ES256.
• The token_endpoint_auth_methods_supported is private_key_jwt only.
• The token_endpoint_auth_signing_alg_values_supported only supports PS256 and ES256.
• The claims_supported returns access_token and id_token claims, including s_hash and openbanking_intent_id claims (but not acr).
• The tls_client_certificate_bound_access_tokens is set to false.

The following is an example of the OpenID provider configuration response.

{
  "issuer" : "https://server.example.com",
  "authorization_endpoint" : "https://server.example.com/oauth/auz/authorize",
  "token_endpoint" : "https://server.example.com/oauth/token",
  "userinfo_endpoint" : "https://server.example.com/oauth/userinfo",
  "jwks_uri" : "https://server.example.com/oauth/jwks",
  "scopes_supported" : [ "openid", "scope", "profile", "email", "address", "accounts" ],
  "response_types_supported" : [ "code id_token" ],
  "response_modes_supported" : [ "query", "fragment", "form_post" ],
  "grant_types_supported" : [ "authorization_code", "password", "client_credentials" ],
  "subject_types_supported" : [ "public" ],
  "id_token_signing_alg_values_supported" : [ "PS256" ],
  "id_token_encryption_alg_values_supported" : [ "none" ],
  "id_token_encryption_enc_values_supported" : [ "A128CBC-HS256" ],
  "request_object_signing_alg_values_supported" : [ "PS256", "ES256" ],
  "token_endpoint_auth_methods_supported" : [ "private_key_jwt" ],
  "token_endpoint_auth_signing_alg_values_supported" : [ "PS256", "ES256" ],
  "claims_supported" : [ "iss", "sub", "aud", "iat", "exp", "jti", "nonce", "client_id", "given_name", "family_name", "email", "profile", "phone_number", "updated_at", "at_hash", "c_hash", "state", "s_hash", "scope", "azp", "nbf", "openbanking_intent_id" ],
  "claims_parameter_supported" : true,
  "request_parameter_supported" : true,
  "request_uri_parameter_supported" : false,
  "require_request_uri_registration" : false,
  "tls_client_certificate_bound_access_tokens" : false
}

JWT-Secured Authorization Request (JAR)

If the FAPI profile is enabled, the Akana OAuth/OIDC provider requires the request object to be included in the authorization request. The authorization endpoint validates the incoming authorization requests from the client. If any validations fail, the endpoint responds with the appropriate error responses.

The following table outlines the authorization request validations performed on the authorization requests from a client.

Error Response for Authorization Request

If the validation is successful, the resource owner is redirected first to the authentication screen and then to the consent screen. However, if there are validation errors, an error response is returned in the redirect URL sent in the request in the following format:

{{redirectURL}}/#error=<errorcode>&error_description=<details>

The most common HTTP status codes are 307 Temporary Redirect, 400 Bad Request, and 500 Server Error. The following table summarizes the error response for an authorization request.

Authentication and Authorization Response

The Akana OAuth server authenticates the end-user or determine if the end-user is already authenticated, based on the provided request parameters. If the end-user is successfully authenticated, the Akana OAuth server will obtain an authorization decision before releasing any information to the relying party. For more information, see Authorization Server Authorization Service.

Authorization Request Response

Upon successful user authentication and the user's consent for the requested scope, the authorization endpoint returns the following response to the redirect URL provided in the request's fragment in the following format:

 {{redirectURL}}/#code=<code>&state=<state>&id_token=<id token>

However, if the tokens are encrypted, the response may be longer to include in the redirect URL. In that case, the response will be sent in a form post instead.

The following table summarizes the successful response to an authorization request.

ID Token as Detached Signature

In the FAPI 1.0 Advanced specification, it is explained that the name "ID Token" used in the OpenID Connect Hybrid Flow might suggest that it provides the identity of the resource owner (subject). However, in this case, the ID Token acts as a detached signature of the issuer to the authorization response. This was an explicit design decision of OpenID Connect Core to make the ID Token act as a detached signature.

The id_token returned from the authorization endpoint does not contain any personally identifiable information (PII). Instead, it includes the following claims that clients can use to verify the authorization response was not tampered with, using the id_token as a detached signature.

Request JWT-Signed and Encrypted Access Tokens

If FAPI profile is enabled, the Akana OAuth/OIDC provider domain must be configured to generate JWT tokens exclusively. Depending on the security requirements, the generated token can be encrypted. For more information, see What are the settings on the Akana OAuth/OIDC Provider Token page and what options should I choose?

JWT Token Request Validation

With the FAPI profile enabled, the Akana OAuth/OIDC provider will only accept token requests using the Authorization Code and Client Credentials grant types. The provider then performs the following validations on any incoming token requests.

Error Response for JWT Token Request

If the token request validation fails, the server responds with an HTTP 400 (Bad Request) status code. However, in some cases, the error codes 404 or 500 may also be returned. The following table summarizes the error response for the JWT token request.

JWT Token Request Response

Upon receiving and validating an authorized token request from the client, the authorization server responds with an access token and id_token. The successful response includes the following parameters.

Revoke JWT Token

The Akana OAuth/OIDC Provider supports revoking the refresh tokens. To learn more, see Authorization Server Token Admin Service.

FAPI support in the Akana OAuth Policy

The APIs hosted on the Akana API gateway are secured using the Akana OAuth Policy. The Akana OAuth Policy validates the authorization token in each incoming request. If the FAPI profile is enabled for the Akana OAuth/OIDC provider or an External OAuth Provider, the OAuth Policy will expect certain requirements to be met by the access token.

• Clients invoking these resource APIs must include an access token, which can be provided in the authorization header. For example, Authorization: Bearer <token_value>.
  • Access tokens passed in the query parameters or as form post parameters are not supported.
  • The authorization header must not contain a null or blank token value.
• The token must be signed using either the PS256 or ES256 algorithm.
• The token is not encrypted using the RSA1_5 algorithm.
• The "iss" claim is an HTTPS URL that matches the issuer identifier URL configured in the domain settings.
• The token must not be expired as this validation accounts for the configured clock skew within the security domain.
• The scopes on the resource must be a subset or the same to those associated with the access token configured in API's OAuth details.
• If a token is issued by the Akana OAuth/OIDC provider and the "Verify JWT with authorization server" option is enabled in the domain configuration, then you must verify that the token or related grant is not revoked.
• Validate that the "aud" claim in the token matches with the audience specified in the domain configuration.

If the token is found to be valid, the policy will then process the request further.

When the token is deemed invalid, the policy responds with the appropriate HTTP status code (typically 400, 401, 403, or 500) and includes one of the following error codes in the response.

FAPI Support in the External OAuth Provider Domain

The Business Admin can configure the FAPI security profile when setting up an External OAuth Provider domain. The External OAuth provider enforces the advanced security specification of the OpenID standard while validating the incoming access token. Akana currently supports the FAPI 1.0 Advanced (UK Open Banking) security profile. For more information, refer to the section Protected resources provisions under the Financial-grade API Security Profile 1.0 - Part 1: Baseline.

To configure an External OAuth Provider domain with FAPI, go to More > Admin > Domains > Add Domain and select External OAuth Provider. On the Details page, provide a name and description for your external OAuth provider, and then select the checkbox to enable the FAPI security profile. To complete the configuration, follow the steps 5 to 9 under the section How do I add an External OAuth Provider domain?

When the FAPI security profile is enabled, the Akana OAuth Policy performs additional validation on the access token included with the API request, as detailed in the FAPI support in the Akana OAuth Policy.

If you are using an external keystore such as a Hardware Security Module (HSM) for signing and decryption, specify the JCA provider for the corresponding HSM. For example, you can configure the JCA Provider values as follows:

• Verify JCA Provider: BC
• Decrypt JCA Provider: nCipherKM (if the token is encrypted)

FAPI requirements for Target APIs

The FAPI specifications outline certain requirements for resource servers that downstream APIs must meet. These requirements are separate from the Akana OAuth features, some can be addressed through other capabilities within the Akana Platform.

The resource server with the FAPI endpoints:

For more details, refer to the following links:

• FAPI 1.0 Baseline- Section 6.  Accessing Protected Resources
• FAPI 1.0 Advanced- Section 6.  Accessing Protected Resources

FAPI requirements for Confidential Clients

When accessing FAPI-protected APIs through the Akana platform, consider the following settings for the App OAuth Profile.

Additionally, the confidential clients must meet the following requirements:

• Include all required parameters within the signed request object (JAR) of the authorization request, as specified in the JWT-Secured Authorization Request (JAR).
• Verify that the authorization response has not been tampered with using the c_hash, s_hash, and at_hash claims in the id_token, if applicable.

Additional resource information

Signature Algorithms Name Mapping

The platform supports both asymmetric and symmetric signature algorithms for encryption. However, when the FAPI security profile is enabled, only asymmetric signature algorithms are supported, and the allowed options are limited to PS256 and ES256. For more information, see What are the options for signing and encryption of JWT access tokens? and What JWT signing algorithms are supported?

The following table provides details on the nomenclature used for signature algorithms across the Akana Platform, including Akana OAuth/OIDC Provider, External OAuth Provider, and App OAuth profile.

Impact on OpenID Connect Relying Party domain

To use as the OpenID Connect Relying Party domain, create a separate Akana OAuth/OIDC Provider domain without the FAPI profile enabled.

Related Topics