SPI Implementation Workflow
Working with SPIs requires you to implement the resource server that complies to the SPI specification. Following the introduction of the SPI Model in a previous section, in this section the general implementation workflow of a FusionFabric.cloud SPI is described.
Register the SPI
You start by registering an application on FusionCreator that include the SPIs you want to implement.
Follow the Application Wizard, and, at the SPI registration step, you must provide the SPI base URL. When your SPI implementation will go live, this URL must be accessible over the internet.
Register the SPIs
Write Your SPI Implementation
You write your SPI implementation based on the SPI specification that is published on FusionCreator in OpenAPI format. You find the SPI specification in the SPI reference documentation.
To see an implementation example, you are provided with a sample client application on GitHub - ffdc-sample-spi. It implements a server compliant with the Sample SPI.
Test the Implementation
You should be able to validate your implementation of the SPI contract. Your server will receive a synchronous REST call from FusionFabric.cloud complying with the SPI input format, and must return a response complying with the output format. The set of tests defined in Postman should offer a validation of request/response handling.
Furthermore, you should be able to validate a security mechanism that needs to be handled in your SPI implementation. This is achieved by delegating the authentication to the FusionFabric.cloud Authorization Server that will issue the access token.
It is your responsibility to validate and use this access token to allow the access to the resources exposed at the endpoints of your SPI implementation. See the next section for more details.
During development, you request an access token from FusionFabric.cloud Authorization Server, that you use to call your own SPI implementation, with the purpose of testing your token validation logic.
Generate the Credentials
After you registered the application and registered an SPI, generate the credentials that you will use to retrieve the access token. The details on how to generate them are given in the Secret Key section.
Application credentials are generated from your FusionCreator dashboard.
With the application credentials, you request the access token through the OAuth2 client credentials grant flow. To learn how to do that with Postman, check out the Client Credentials Postman tutorial of the Get Started guide. Be aware, however, that, at the step 1 of the Postman tutorial, you will call an endpoint of your own SPI implementation.
Validate Access Token
FusionFabric.cloud Authorization Server uses JSON Web Tokens compliant with RFC7519.
The access tokens issued by the FusionFabric.cloud Authorization Server are exclusively signed using RS256 asymmetric encryption, advertised in the alg claim of the JOSE header - for details, see RFC7515, section 4.1.1.
The public keys are exposed in a JSON Web Key Set, compliant with RFC7517 at the JWKS URL:
The JWKS URL can also be retrieved using the OIDC Discovery service by querying the jwks_uri metadata.
The key to use for token validation is specified in the JOSE header kid claim - for details, see RFC7515, section 4.1.4.
With this information, you can now use any library that supports RS256 and JSON Web Key Sets to verify the origin of the access token in your SPI implementation.
Further validation is required for the following access token claims:
| Claim | Specification | Typical Usage | Description |
|---|---|---|---|
iss |
RFC7519, section 4.1.1 OIDC Core, section 2 OIDC Discovery, section 4 |
validation | The base URL of FusionFabric.cloud Authorization Server login endpoint. This is also used to expose the Discovery service, that you use to retrieve the OIDC metadata, most notably the URL of the JSON Web Key Set that stores the public key to validate the access tokens. |
|
RFC7519, section 4.1 | validation | Claims used for token validation, typically parsed by a JWT library. |
aud |
RFC7519, section 4.1.3 | authorization | This claim identifies the reciepients that the access token is intended for. It contains the list APIs/SPIs that this token provides access to. These are registered to your application in the corresponding API channel type. |
tenant |
FusionFabric.cloud platform specific | server context | Tenant unique identifier. It is notably used in the URL for OAuth2/OpenID Connect authentication. |
Host the SPI Implementation
You are the owner of the SPI implementation. Therefore, you must take care of hosting it and make it reachable by the financial institutions that will use it through FusionFabric.cloud.
Finastra will not host your SPI implementation. It will only keep track of the base URL registered in your application.
Here’s a summary of the process:
- You define the SPI base URL during the registration of your application, as described in Register the SPI section. The SPI base URL points to the location where you host your SPI implementation.
- Use SPI structure as below while testing the implementation hosted at your end:
https://{base-url}/<remaining part of SPI URL as in documentation>
For example:https://fraudanalysis.com/payment/fraud/v1/fraud-risk-analysis
Follow the steps to test the implementation as described in SPI Implementation Workflow.
Please make sure to follow the request/response payload structure as given in any SPI specification documentations.
While testing with base URL as mentioned above, you can retrieve a token using sandbox tenant as described in client credentials tutorial. Requests with URL structure as above will not go through FusionFabric.cloud server but your application will receive the retrieved token so you can verify access token validation at your end. - When there will be a contract with FI - the tenant, backend instance, and consent setup will be considered so that routing is established properly.
- Financial institutions core systems will make requests to the SPI through FusionFabric.cloud as
https://api.fusionfabric.cloud/<remaining part of SPI URL as in documentation>. - FusionFabric.cloud server will check the fintech application for which consent has been granted for the request-making financial institution’s tenant and redirect the request to the base URL as registered in the fintech application.
- To validate the received request, fintech application needs to check certain fields from the received token such as “audience” and “issuer”.
For details regarding validation required for the access token claims, please check the documentation on below link:
- Post validating the request, your application should process the request and provide a response. It is expected that fintech shall send back the response in structure as given in any SPI specification documentations.
Sample SPI project here.