swift microgateway backward compatibility interface

SWIFT Microgateway BCI Version 1.0.5 Getting Started Guide

SWIFT Microgateway Backward Compatibility Interface version 1.0.5 Getting Started Guide


Legal Notices Copyright SWIFT © 2020. All rights reserved.

Restricted Distribution Do not distribute this publication outside your organisation unless your subscription or order expressly grants you that right, in which case ensure you comply with any other applicable conditions.

Disclaimer SWIFT supplies this publication for information purposes only. The information in this publication may change from time to time. You must always refer to the latest available version.

Translations The English version of SWIFT documentation is the only official and binding version.

Trademarks SWIFT is the trade name of S.W.I.F.T. SCRL. The following are registered trademarks of SWIFT: the SWIFT logo, SWIFT, SWIFTNet, Sibos, 3SKey, Innotribe, the Standards Forum logo, MyStandards, and SWIFT Institute. Other product, service, or company names in this publication are trade names, trademarks, or registered trademarks of their respective owners.


Table of Contents Legal Notices ........................................................................................................................................... 2

SWIFT Microgateway Backward Compatibility Interface 1.0.5 Getting Started Guide .......................... 4

Sign up for SWIFT API Services and Create an IAM User .................................................................... 6

Setup Client Application Credentials .................................................................................................. 7

Promote Client Application Credentials to Pilot and Live Environments ........................................... 7

Setting up Business Certificate ........................................................................................................... 7

Setup Firewall and Forward Proxy Infrastructure ............................................................................... 8

Download the SWIFT Microgateway .................................................................................................. 9

Verify JAR file integrity ........................................................................................................................ 9

Applying SWIFT Microgateway Patch Releases ................................................................................ 10

Setting up SWIFT Microgateway ....................................................................................................... 10

Application Properties .................................................................................................................. 10

Encrypt the properties file ............................................................................................................ 12

Decrypt the properties file ............................................................................................................ 12

Set Environment Variable ............................................................................................................. 12

Start the SWIFT Microgateway ..................................................................................................... 13

Configuration Data ........................................................................................................................ 13

Using the SWIFT Microgateway ............................................................................................................ 16

Run the tests using Postman Collections .......................................................................................... 16

Making a business call....................................................................................................................... 17

Stopping the Microgateway .............................................................................................................. 19

Exception Handling ........................................................................................................................... 19

API errors returned by Service Provider Application .................................................................... 19

API requests failing at SWIFT Microgateway ................................................................................ 20

Using Docker for SWIFT Microgateway ............................................................................................ 21

Integrate SWIFT Microgateway with Kubernetes ............................................................................. 23

Security Footprint Models supported by the SWIFT Microgateway .................................................... 25

Data Protection applicable to SWIFT Microgateway Product .......................................................... 26

Java Key Store ............................................................................................................................... 26

Identity and Access Management for accessing SWIFT API services using SWIFT Microgateway

Product .......................................................................................................................................... 27


SWIFT Microgateway Backward Compatibility Interface 1.0.5 Getting Started Guide The SWIFT Microgateway provides an API integration product for SWIFT API Services. Using the SWIFT Microgateway, you can easily build applications that work with SWIFT API services like gpi Tracker, pre-validation, g4c and gCase. We regularly add support for new services to the SWIFT Microgateway. This document is for existing gpi Connector customers migrating to SWIFT Microgateway. SWIFT Microgateway product is fully backward compatible with gpi Connector Interface i.e., back office application can seamlessly interface with SWIFT Microgateway as if it is connecting to gpi Connector with LAU as the application level security. **Please note – the use of SWIFT’s Microgateway products (including but not limited to SWIFT Microgateway and SWIFT Security SDK) are subject to the terms and conditions contained in their applicable license. Such applicable license will be contained in a “license file”. Your use of the SWIFT Microgateway products shall be considered your acceptance of the applicable license terms. The below picture depicts the connectivity topology when using SWIFT Microgateway for doing SWIFT APIs.

Note: You must deploy SWIFT Microgateway in the SWIFT Secure Zone similar to SAG, SNL, HSM and VPN Box. The API flows need not go through SAG, SWIFT Microgateway must be directly connecting though VPN Box without the need of going through SAG.


The SWIFT Microgateway Backward Compatibility Interface aka gpi connector BCI integration options are illustrated below:

Pre-Requisites The SWIFT Microgateway is compatible with: Operation system: Red Hat Enterprise Linux release 7.4, AIX 7.2 and Windows 10. Java Runtime Environment – Oracle JRE for Java 8. You can download the Java SE Runtime environment from https://www.oracle.com/java/technologies/javase-jre8-downloads.html for Windows 10 or https://www.ibm.com/support/pages/java-sdk-aix for IBM Java SE Version 8 on AIX or https://openjdk.java.net/projects/jdk8/ for Red Hat Enterprise Linux 7.4 Browsers Compatibility – SWIFT Microgateway configuration database is compatible with IE 11 and Up, FF 66 and Up, Chrome 70 and Up. Minimum Recommended Hardware Requirements – 8GB RAM, 4 CPU and 20GB disk space

https://www.oracle.com/java/technologies/javase-jre8-downloads.html

https://www.ibm.com/support/pages/java-sdk-aix

https://openjdk.java.net/projects/jdk8/


Getting Started with SWIFT Microgateway This section provides information about how to install, set up, and use the SWIFT Microgateway. Topics

Sign up for SWIFT API Services and Create an IAM User

Setup Client Application Credentials

Promote Client Application Credentials to Pilot and Live Environments

Setting up Business Certificate

Setup Firewall and Forward Proxy Infrastructure

Download the SWIFT Microgateway

Sign up for SWIFT API Services and Create an IAM User To use the SWIFT Microgateway to access the SWIFT API Services, you need to order API Service subscription through swift.com.

To sign up for SWIFT API Services Note: If you already have an active subscription to gpi Tracker API and Pre-validation services, the below set of steps are not applicable to you. 1. Open https://www.swift.com/ and click Order Products and Services. 2. Click on the API Service that you are interested in, for instance, gpi Tracker, gpi Pre-validation

Service. 3. Follow the on-screen instructions. Part of the subscription procedure may involve Service

Administrator approval process. 4. The following information should be provided to properly provision your organisation as API

consumer onto the SWIFT API service (Knowledge Base Tip - 5024167)

The 8-character BIC of the institution that you order for.

Whether you want additional 8-character BIC(s) to be subscribed as API consumers. In case additional BICs should be subscribed, please specify their BICs.

Your preferred implementation date.

https://www2.swift.com/knowledgecentre/kb_articles/5024167


Setup Client Application Credentials To use the SWIFT Microgateway to access the SWIFT API Services, you need to register Client Application to receive Consumer Key and Secret. 1. Open https://developer.swift.com/ to create a developer account on SWIFT Developer Portal

Click Create Account to create an account if you do not have a swift.com user account. Follow the on-screen instructions suggested in the account creation page.

Alternatively, you can login using your swift.com user account by clicking “Sign in with swift.com”

2. Create an Application to retrieve API Key and Consumer Secret 3. Next, create an Application by click “My Apps” menu. Click on “+ Add a new App” within the “My

Apps” page. 4. Follow the instructions on the screen

Provide an application name

Select all the applicable API Products

Copy the Consumer Key and Consumer Secret generated in Developer Portal

Configure the client application credentials as configuration data. C.f Configuration Data section.

Promote Client Application Credentials to Pilot and Live Environments

You must request application credentials provisioning after ordering the API Service on swift.com c.f. above section of the document. Make sure you provide the following information to SWIFT for Client Application Credentials provisioning. Use Contact Us link on the Developer Portal to provide this information.

Choose “Request to promote App” as Subject from the Dropdown list

Enter Client Application Name

Click Submit The information is utilized to provision Client Application Consumer Key and Consumer Secret on API Gateway.

Setting up Business Certificate Note: If you already have a Business Certificate for accessing gpi Tracker API and Pre-validation services, the below set of steps are not applicable to you. Next, create a Business certificate and grant API service RBAC role to the subject DN. To create a Business Certificate 1. Your SWIFTNet Security Officer should go to the Online Operations Management (O2M)

application. 2. If you do not have a Business certificate, then create a Business Certificate. 3. Security Officer must assign API Service RBAC role to the newly created Distinguished Name

(DN). For instance, “FullViewer” RBAC role on “swift.apitracker” SWIFTNet Service. Security Officer can only delegate RBAC role if the institution has subscription to the API service. Refer to section “To sign up for SWIFT API Services” for details.

4. If you are using a Business certificate that is stored on a HSM, then configure the subject DN of the Business certificate as “user_dn” by creating the SAG profile c.f. Setting up SWIFT Microgateway.

https://developer.swift.com/

https://developer.swift.com/contact-us

https://www2.swift.com/go/book/book130454



Setup Firewall and Forward Proxy Infrastructure Communication between the SWIFT Microgateway and the API services are secured. The SWIFT infrastructure only allows incoming communication from a known SWIFTNet Link IP address registered during the customer's on-boarding process. As a consequence, the communication to the infrastructures made available on MV-SIPN network (gpi Tracker, g4c, gCase or gpi Pre-validation) must come from a SWIFTNet Link instance IP address. To allow the SWIFT Microgateway to communicate with services like gpi Tracker, an HTTP proxy installed on the SWIFTNet Link and Alliance Gateway server can be used. This set-up is the same set-up as the one required accessing the SWIFT WebAccess services such as SWIFTNet Online Operations Manager (O2M) service. For more information about the set-up, see the SWIFT Web Access Configuration and Troubleshooting Guide. To allow the communication through the HTTP proxy, customers must use the following proxy settings configuration parameters on the gpi Connector: 1. Make sure your front-end firewall is setup to allow connection to SWIFT API Gateway on port 443

Setup https://api-test.swiftnet.sipn.swift.com URL for Test and Training APIs

Setup https://api.swiftnet.sipn.swift.com URL for Live APIs

Refer Network Configuration Tables Guide for specific IP address and port information.

2. Setup HTTP Forward Proxy as required. Refer to section “Configuration Data” section for defining HTTP Forward Proxies with the SWIFT Microgateway.

https://www2.swift.com/go/book/book97189/book97189/html

https://www2.swift.com/go/book/book97189/book97189/html

https://api-test.swiftnet.sipn.swift.com/

https://api.swiftnet.sipn.swift.com/

https://www2.swift.com/knowledgecentre/rest/v1/publications/conn_s_nw_conf_tbl_guid/5.0/conn_s_nw_conf_tbl_guid.pdf?logDownload=true


Resiliency The SWIFT Microgateway configuration database lets customers configure a proxy that is used whenever a connection to API Gateway is made. Defining multiple proxies increases the resiliency, as the SWIFT Microgateway component will automatically failover on another proxy if the current proxy goes offline. The proxy failover feature implements the following behaviour:

When a proxy is unavailable, SWIFT Microgateway automatically forwards the request to another available proxy.

Once a proxy is used, SWIFT Microgateway uses this proxy as long as it is available. There is no concept of fallback to the primary proxy.

To revert the traffic on one specific proxy, other proxies have to be shut down. If none of the proxies is available, then an exception is propagated back to the back-office

application.

Download the SWIFT Microgateway This topic describes how to download the SWIFT Microgateway.

SWIFT Microgateway is available for download through SWIFT Developer Portal distribution channel – https://developer.swift.com

Pre-requisites o You must be a registered developer on SWIFT Developer Portal o SWIFT approves your account for downloading the SWIFT Microgateway software

Verify JAR file integrity You must import SWIFT CA 2K certificate to your trust store before executing the below verification script. <SWIFTCACertFile> is the path to the SWIFT CA 2K certificate. For example, <keyStorePath> is the path to the trust store. For example, c:\swift\ca.jks You can verify SWIFT Microgateway software integrity by executing the following command:

where <keyStorePath> is the path to the SWIFT CA 2K certificate. For example, c:\swift\ca.jks <jarName> is the name of the Microgateway .jar file. For example, swift-mgw-1.0.6.1.jar The output includes

the X.509 certificate used for signing the .jar files

the certificate validity period

Digest algorithm i.e., SHA-256

Signature algorithm and key length – SHA-256 with RSA and 2048 bits

Outcome of signature verification – verified or invalid

jarsigner -certs -verbose –verify keystore <keystorepath> <jarName>

keytool -import -trustcacerts -alias <aliasName> -file <SWIFTCACertFile> -keystore <ketStorePath>

https://developer.swift.com/


Note: You will see the following warnings on SWIFT CA certificate:

This jar contains entries whose signer certificate will expire within six months.

This jar contains signatures that do not include a timestamp. Without a timestamp, users may not be able to validate this jar after any of the signer certificates expire (as early as 2021-05-16).

Signing certificate renewal and including a timestamp in the signature will be added to the product in the next release.

Applying SWIFT Microgateway Patch Releases SWIFT Microgateway releases are versioned as v<a>.<b>.<c>[.<d>] A major release includes three digits as follows 1.0.5, whereas a minor version includes a sub-version (fourth digit) at the end as follows 1.0.5.3. A minor version typically addresses an emergency fix on a major release. Over a period, there can be multiple minor versions on a major release (1.0.5.1, 1.0.5.2, 1.0.5.4 etc.). A minor version package content is complete, meaning it is equivalent to a major version package with the fix included. If you are an existing customer intending to apply patch on a previous release, then all you need to do is replace the current version of Microgateway jar file with the jar file downloaded with the patch release. However, if you are a new customer or a customer migrating to the major release then you can consume the latest version for implementation. For instance, if you are on SWIFT Microgateway 1.0.6 version looking to migrate to 1.0.6.1 then all you need to do is replace swift-mgw-bci-1.0.5.3.jar with swift-mgw-bci-1.0.5.4.jar in the bin directory.

Setting up SWIFT Microgateway This topic describes how to set up Microgateway Application and Configuration Database in Windows and Linux environments. Note: When setting up Microgateway on Linux, 'root' user account usage is not recommended for security concerns. Instead, use a dedicated user account that has access only to the Microgateway files and database.

Application Properties

Setup the application properties before starting the SWIFT Microgateway.

Unzip the composite SWIFT Microgateway zip

In a terminal window, navigate to the directory where you unzipped the composite SWIFT Microgateway zip

Open the “config-swift-mgw.properties.yaml” file in the root folder.

Configure following properties within the file

o Environment Set the applicable environment – “LIVE” or “TEST”.

o Microgateway Port Information

port It is defaulted to 9007, change this value if applicable.

o Microgateway TLS Information


cert_alias Set the alias name of the MGW TLS certificate. Set the

swift_microgateway.ssl.cert_alias attribute .

key_manager_password Set the optional key manager password for the MGW TLS certificate. When it is not set, the value of key_store_password will be used for the same. Set the swift_microgateway.ssl.key_manager_password attribute.

key_store_type Set the key store type value to either “jks” or “pkcs12”. Set the swift_microgateway.ssl.key_store_type attribute.

key_store_path Path to the key store file. Set the swift_microgateway.ssl.key_store_path attribute. The keystore used by Microgateway for 1-Way TLS between back-office application and Microgateway. The public key stored in the keystore will be exposed to the back-office application to authenticate it via a HTTPS session.

The customer can either generate a self-signed certificate or a certificate signed by their own certificate authority (CA) using keytool command:

keytool.exe -genkey -keyalg RSA -alias <CERTIFICATE ALIAS> -keystore <KEYSTORE LOCATION>/mykeystore.jks -storepass <PASSWORD> -validity 360 -keysize 2048 -dName cn=<HOST HOSTNAME>

key_store_password Password for accessing the key store file. Set swift_microgateway.ssl.key_store_password attribute.

o Microgateway 2-way TLS Information

Set the following attributes only if the client(s) connecting to SWIFT Microgateway require a 2-way TLS connectivity.

client_auth: Set the client_auth to “need” when 2-way TLS connectivity is a mandatory requirement. Set the client_auth to “want” when 2-way TLS connectivity is optional.

trust_store_type: JKS

trust_store_path: Path to the trust store file. Set the swift_microgateway.ssl.trust_store_path attribute The truststore used by Microgateway for 2-Way TLS between back-office application and Microgateway. The truststore contains the trust certificate used to verify the identity of the client certificate connecting to Microgateway.

trust_store_password: Password for accessing the trust store file. Set swift_microgateway.ssl.trust_store_password attribute.

o Database Properties

url Set the location of the database file. The database file constitutes API Metadata and Configuration Data. The value must be formatted as jdbc:h2:[file]:[<Path>]/${name};CIPHER=[<Cipher Value>] <Path> identifies the location of the file. This must be absolute path of the file (not relative path).


<Cipher Value> Can be set as one of the following values: ”AES”, “XTEA” and “FOG”. For example, in a Windows environment spring.datasource.url=jdbc:h2:file:C:/SWIFT/MGW/db/mgwdb;CIPHER=AES Set the services/metadata/url attribute.

username Set the user name for accessing the database. Set the services/metadata/username attribute.

password Set the passwords for accessing the database file and database itself. The two password values have to be separated by a space. Do not use spaces within the individual password while defining them. Set the services/metadata/password attribute.

o Logging Properties

level Set the log Level (INFO here). The root level can be set to one of these

values - "OFF", "TRACE", "DEBUG", "INFO", "WARN", "ERROR" and "FATAL". Set the services/logging/level attribute.

Encrypt the properties file

Update the configuration attributes in the YAML file with the custom values applicable to your environment. Before starting the Microgateway application, from the command line run the following encryption command to encrypt the configuration YAML file. Run the encrypt.sh or the encrypt.cmd in the bin folder of the MGW BCI package. Password rules for the secrets file: 1. Password needs to be 16 characters 2. Allowed list of characters include alphanumeric, numbers, special characters 3. Spaces are not allowed. For example, ( edit for new commands)

cd c:\mgwbci\bin && encrypt.cmd

Decrypt the properties file

If you have to modify the configuration after encryption, then execute decrypt command passing the encrypted file and secrets file as input parameters.

cd c:\mgwbci\bin && decrypt.cmd

Set Environment Variable

Create an environment variable named “enable_secure_jwt”. Set the value of this variable to “false”. The environment variable is meant for future purposes when signed jwt support is supported centrally. Note: You must stop and restart Microgateway if you reset the environment variable value.


Start the SWIFT Microgateway

1. In a terminal window, navigate to the directory where you unzipped the composite SWIFT

Microgateway zip. 2. Go to bin folder. 3. Run the SWIFT Microgateway executable by executing the start-swift-mgw.sh for Linux or start-

swift-mgw.cmd command for Windows.

Configuration Data

Pre-requisites To use the SWIFT Microgateway, you must have:

A SWIFT Developer Portal registered consumer key and consumer secret. For instructions, see above (p. 6).

PKI certificates set in your environment. For more information, see Setup Client Application Credentials above (p. 6).

Database Configuration The database configuration is equivalent of SwAP Proxy Configuration file in gpi Connector configuration. If Microgateway BCI is configured for 2-way TLS and client_auth is set to “need” in config-swift-mgw.properties.yaml then you MUST import the client certificate in the browser for accessing the configuration database. Open the database GUI by accessing the following URL using your browser - [hostname]:[port]/mgw-config-console/login.jsp

For example, https://<hostname>:9007/mgwbci-config-console/login.jsp

Create the following objects using the browser. 1. Create Business Application object.

o APPLICATION_ID Unique Business Application identifier. It must be an integer value.

You can use sequence numbers as Application Identifiers – 1, 2, 3 etc.,

o APPLICATION_NAME Name of the business application. A free format string identifying your application, example “BO1”.

This is defined as <BackOfficeApplications>.<BackOfficeApplication>. <ApplicationId> in the SwAP Proxy Configuration file.

o SHARED_SECRET A shared secret key for establishing authenticity of the API

exchanged between BackOffice Application (BO) and SWIFT Microgateway (MGW). The shared secret key must be at least 32 characters long. Shared secret is the LAU key using which the data is signed. It is equivalent to the concatenation of LAU Left Key and Right Key identified by the following XML elements in the SwAP Proxy Configuration file. <BackOfficeApplications>.<BackOfficeApplication>.<LauKeyLeftPart> and <BackOfficeApplications>.<BackOfficeApplication>.<LauKeyRightPart>.

2. Create API Gateway Connectivity Info object


For each Business Application object created above, configure Consumer Key and Consumer Secret registered in SWIFT Developer Portal.

o APPLICATION_ID Business Application identifier.

o CONSUMER_KEY Consumer Key (aka API Key), which is obtained from SWIFT Developer portal while registering the Business Application.

o CONSUMER_SECRET Consumer Secret obtained by the developer from SWIFT Developer portal while registering the Business Application.

3. Create Application Service Profile object

Create an API Service Profile for establishing an API session with API Gateway.

o APPLICATION_ID Business Application identifier.

o PROFILE_ID A unique name given to the Application Service Profile. A free format string identifying your application profile. For example, “gpiTracker-P1”.

o RBAC_SCOPE OAuth token session scope.

A session scope can be requested up to the granularity of API Services. The possible values are “swift.apitracker!p”, “swift.apitracker”, “swift.preval!p” and “swift.preval”. Defining scope is mandatory. If you want to replicate SWAP Proxy configuration file Business Application configuration then set the RBAC Role equivalent to <BackOfficeApplications>.<BackOfficeApplication>.<ServiceName> of the SWAP Proxy Configuration file. There is no need to define an Application Service profile for each version of the API service.

4. Create Service Profile Users

API Service Profile Users capture User DN (PKI Certificate) required for establishing an API session with API Gateway.

o PROFILE_ID A unique name for Application service profile. Reference to Application Service Profile object.

o APPLICATION_ID Business Application Identifier.

o USER_DN Subject DN of the PKI certificate on the HSM. This is equivalent to <BackOfficeApplications>.<BackOfficeApplication>.<PkiSignatureDN> of SwAP Proxy configuration file.

5. Create Key Store Info object Setup your Key Store Info with SAG PKI details.

o KEY_STORE_FILE_PATH Location of the trust alias for SAG and APIGW TLS certificates. Create separate entries for SAG and APIGW in the Key Store Info object. Setup the SWIFT CA Public Certificate as Trust Alias for 1-way TLS between SWIFT Microgateway and API Gateway. The instructions for downloading SWIFT CA Certificate is detailed in the following Knowledge Tip 5022832.

o KEY_STORE_TYPE Set the value to ‘SAG’ or ‘APIGW’.

https://www2.swift.com/kb/#/tip/5022832


o KEY_STORE_PASSWORD Password for accessing the Java Key Store file.

6. Create PKI Certificate Info object

Setup SAG and APIGW PKI (SWIFT CA) certificate Info. Create separate entries for SAG and APIGW.

o ALIAS Alias name corresponding to the PKI certificate in the java key store. Refer to Key

Store Info object.

o KEY_STORE_FILE_PATH Location of the Java Key Store file.

o KEY_STORE_TYPE Set the value as ‘SAG’ or ‘APIGW’. o PASSWORD Password for accessing the Java Key Store file.

7. Create HTTP Proxy Info object

If you are using HTTP Forward Proxy(s), create separate entries for each HTTP Proxy instance applicable to API environment.

o HOST HTTP Proxy hostname. Mandatory attribute. o PORT HTTP Proxy port. . Mandatory attribute. o USER & PASSWORD User name and Password for connecting to HTTP Proxy. Only

required if a HTTP Proxy is protected with User name and password.

8. Create SAG object

o HOSTNAME SAG server hostname.

o PORT SAG Port. Defaulted to 48002. o LAU_KEY LAU Key to be used with SAG. It is a concatenation of LAU left key and LAU

right key without any spaces between them.

o SSL_DN Distinguished Name corresponding to the SAG public certificate, which is used by Microgateway in the context of establishing a 1-way TLS connection with SAG.

o Active If you are using a resilient SAG infrastructure then identify the current active SAG

instance.

o ALIAS Alias name corresponding to the PKI certificate in the java key store. Refer to Key Store Info object.

o KEY_STORE_FILE_PATH Location of the Java Key Store file.

9. SAG Message Partner o MESSAGE_PARTNER Name of the SAG message partner. A free format string

identifying SAG Message Partner. o USER_DN Subject DN of the PKI certificate on the HSM.


Using the SWIFT Microgateway

Run the tests using Postman Collections 1. In a terminal window, navigate to the directory where you unzipped the composite SWIFT

Microgateway zip 2. Go to front-end folder 3. In order to run tests using Postman collections, install Postman on your local machine. Current

Postman collection has been tested on 7.10.0 and 7.24 versions. 4. Import the JSON collection file “swift-mgw-bci-1.0.5.postman_collection.json” into Postman.

5. Set the following collection variables for running tests using Postman collections.


applicationID – Business Application Name setup within the Business Application object of configuration database.

version – LAU version (1.0)

lauKey – key used to compute LAU signature

6. If Microgateway is configured for 2 way TLS please follow the Postman documentation for adding the client certificate and key files before making the API calls.

7. Execute API requests using Postman collections. Note: When running on Linux, the request in Postman should refer to the hostname or host IP where Microgateway is running instead of "localhost". Screenshot of a sample Postman Collection:

Making a business call In order to make the business call you need to implement following logic in your back-office application: 1. Add SWIFT Microgateway TLS certificate to your trust store for the 1-way TLS. 2. Include LAU HTTP Headers with the business API It is mandatory to use LAU security and TLS one-way for the connectivity between backoffice applications and the SWIFT Microgateway. The necessary PKI material is stored in Java keystore files. LAU security LAU security is mandated between the caller application at the back-office side and the SWIFT Microgateway. The LAU key is associated to the back-office application setup as configuration in SWIFT Microgateway. Based on this configuration, when an HTTP request is received from the back-office


application, SWIFT Microgateway will analyse the request to match the back-office application from which the request originates. The LAU key associated with that back-office application will then be used to verify the signature of the request. The signature must cover the JSON request or response payloads, the API specific part of the URI and the http headers. The algorithm to compute LAU signature must use HMAC SHA-256 and UTF-8 encoding. For more information about LAU, see the gpi API Specification documentation on the Knowledge Centre (User Handbook).

https://www2.swift.com/uhbonline/books/a2z/swift_gpi.htm




Stopping the Microgateway Use the following steps for stopping a Microgateway Process. 1. In a terminal window, navigate to the directory where you unzipped the composite SWIFT

Microgateway zip 2. Go to bin folder 3. Run the SWIFT Microgateway executable by executing the stop-bci.sh for Linux or stop-bci.cmd

command for Windows.

Exception Handling Understanding how and when the SWIFT Microgateway throws exceptions is important for building high quality applications using the SWIFT Microgateway. The following sections describe the different cases of exceptions that are thrown by the SWIFT Microgateway and how to handle them appropriately.

API errors returned by Service Provider Application

Service Provider Exceptions are the most common exceptions that you experience when using the SWIFT Microgateway. This exception represents an error response from an API Provider like gpi Tracker, gpi Pre-validation or g4c. This can be because of errors in the request’s parameters, request payload or because of issues on the service side. For example, if you try to execute a Get Payment Changed Transactions API by providing invalid parameters, from_date_time value greater than to_date_time value in this scenario then Service Provider returns an exception in the following JSON format: Service Provider provides information such as:

Returned status code

Returned Severity

Detailed error message from the service provider Some examples of errors returned by the API Provider are: { "status": { "severity": "Fatal", "code": "Sw.gpi.InvalidField", "text": "to_date_time is greater than sysdate: [2020-05-25T23:59:59.000Z]" } } { "status": { "severity": "Fatal", "code": "INVA/X001", "text": "Syntax error" } } SWIFT Microgateway adds LAU headers to the HTTP response sent to the Back Office Application.

https://localhost:9003/swift/mgw/swift-apitracker-pilot/v3/payments/changed/transactions


API requests failing at SWIFT Microgateway A client exception is generally more severe than a Service Provider Exception, and indicates a major problem that is preventing the client from making service calls to API service provider. For example, the SWIFT Microgateway throws a client exception if a network connection is unavailable when you try to call an operation on one of the clients or a LAU authentication failure between API Client Application and SWIFT Microgateway. SWIFT Microgateway provides information such as:

HTTP status code – 400 for Bad Request, 401 for Authentication failures, 500 for internal error, 502 for proxy error and 508 for timeout.

Severity – “Transient|Logic|Fatal”

Code – Formatted as

Detailed error message Some examples of errors returned by the Microgateway are: 400 Bad Request

{

"status": {

"severity": "Logic",

"code": "SwAPProxy001",

"text": "Missing mandatory HTTP headers:LAUApplicationID"

}

} 400 Bad Request { "status": { "severity": "Logic", "code": "SwAPProxy003", "text": "LAU Error:LAU Version is incorrect" } } Note: SWIFT Microgateway does not add LAU headers in the HTTP response for those API requests failing at SWIFT Microgateway.


Using Docker for SWIFT Microgateway This topic explains how to run SWIFT Microgateway in a Docker container. The steps covered in this topic assume a basic understanding of Docker, Docker commands, and SWIFT Microgateway setup and configuration. For more information, refer to the document for Docker.

Prerequisites Before running SWIFT Microgateway in a Docker Container, you must do the following tasks:

Configure SWIFT Microgateway for your application environment i.e., Pilot or Live For more details on configuration, see “Application Properties” and “Encrypt the properties file” sections of “Setting Up Microgateway” section.

Configure the java key store. See “Data Protection applicable to SWIFT Microgateway Production” section for details.

Run SWIFT Microgateway as a Docker container 1. Copy SWIFT Microgateway package to the working directory on the Docker host. 2. Create Docker File

Unzip SWIFT Microgateway package

Copy application properties and jks files to mgw directory

Copy the H2 DB

Start the MGW application, make the application available on a registered port. For example, 9007

3. Build the Docker Image

$ docker build . –t <nametoimage>

4. Run the SWIFT Microgateway as container.

$ docker run –it –d –p <port>:<port> <imagename/id>

5. To check that the container is running.

$ docker ps

You should see output similar to the following (swiftmicrogateway used as image name in the below example): CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES a188693c8741 swiftmicrogateway "/sbin/entrypoint ..." 4 seconds ago Up 3 seconds 0.0.0.0:9004->9004/tcp boring_euler

Setting up Configuration Data Before you begin, make sure you have setup configuration data for doing API calls. See “Configuration Data” section of the document. You can open the database GUI by accessing the following URL using your browser – https://<dockerhostIP>:<port>/mgwbci-config-console/login.jsp

Testing an API call After you start the Swift Microgateway in the container, you can make API calls to the instantiated SWIFT Microgateway instance. For example,


https://<dockerhost>:<port>/swift/mgwbci/swift-apitracker-pilot/v3/payments/{uetr}/transactions

Stopping SWIFT Microgateway Use the following Docker command to stop SWIFT Microgateway:

$ docker stop <imagename>

Restarting SWIFT Microgateway After stopping the SWIFT Microgateway, you can restart it with this Docker command:

$ docker start <imagename>


Integrate SWIFT Microgateway with Kubernetes You can run SWIFT Microgateway instances in a Kubernetes cluster. This topic explains why you might want to deploy SWIFT Microgateway on Kubernetes, and it describes how to deploy SWIFT Microgateway to Kubernetes. 1. Push the SWIFT Microgateway Docker Image to your Docker Registry.

2. Create a yaml file for deploying the Docker Image.

apiVersion: apps/v1 # version of the API kind: Deployment metadata: name: mgw # Name of the application namespace: microgateway spec: replicas: 2 # tells kubernetes to run 2 pods matching the template selector: app: mgw # reference the deployment deploymentconfig: mgw template: metadata: labels: app: mgw spec: containers: # which docker container to use - image: docker.swift.com:5000/swift/microgateway:v1 name: mgw ports: - containerPort: 9004 # port that was used in the image protocol: TCP volumeMounts: # for mounting the SWIFT Microgateway database - mountPath: /opt/h2db/ name: mgw-1 - mountPath: /opt/mgw/db name: volume-dgv10 volumes: - emptyDir: {} name: mgw-1 - name: volume-dgv10 persistentVolumeClaim: claimName: mgwdb

3. Upload the yaml to kubernetes kubectl apply –f <name of deployment yaml file>

4. Define the service as a yaml file

apiVersion: apps/v1 # version of the API kind: Service metadata: name: mgw-service # Name of the service spec: selector: app: mgw # reference the deployment ports: - protocol: TCP # port that was used in the image port: 80 targetport: 9004


5. Upload the service yaml to kubernetes

kubectl apply –f <name of the service yaml file>

6. Display Information about the service kubectl describe services <name of the service yaml file>

From the output, make a note of the NodePort value for the service.

7. Identify the pods that are currently running the SWIFT Microgateway application. kubectl get pods --selector=”app=mgw” --output=wide

8. Get the public IP address of one of your nodes that is running a mgw pod. How you get this address depends on how you set up your cluster. For example, if you are using Minikube, you can

see the node address by running kubectl cluster-info.

9. Use the node address and node port to access the SWIFT Microgateway application

You can open the database GUI by accessing the following URL using your browser:

https://<public-node-ip>:<node-port>/mgwbci-config-console/login.jsp

After you start the Swift Microgateway in the container, you can make API calls to the instantiated SWIFT Microgateway instance. For example, https://<public-node-ip>:<node-port>/swift/mgwbci/swift-apitracker-pilot/v3/payments/{uetr}/transactions


Security Footprint Models supported by the SWIFT Microgateway Security at SWIFT is the highest priority. As an SWIFT customer, you benefit from a data center and network architecture that is built to meet the requirements of the most security-sensitive organizations. Security of the SWIFT Infrastructure – SWIFT is responsible for protecting the infrastructure that runs all of the services offered in the SWIFT Data Centres and providing you with services that you can use securely. Our security responsibility is the highest priority at SWIFT, and the effectiveness of our security is regularly tested and verified by third-party auditors as part of the SWIFT Compliance Programs. API Security Footprint Models – The security is determined by the API service you are using and other factors including the sensitivity of the data supported by the API service and your organization’s requirements. Topics

Data Protection applicable to SWIFT Microgateway Product

Identity and Access Management for this


Data Protection applicable to SWIFT Microgateway Product For data protection purposes, we recommend that you protect Client Application account credentials and set up individual user accounts with SWIFT Online Operations Management (O2M), so that each user is given only the permissions necessary to fulfil their job duties. We also recommend that you secure your data in the following ways: 1. Setup 1-way TLSv1.2 for communication between Back Office Application and SWIFT

Microgateway. TLS cipher suite supported for secure communication are TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 and TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256.

2. Setup 1-way TLSv1.2 for communication between SWIFT Microgateway and SWIFT API Gateway

3. Setup 1-way TLSv1.2 for communication between SWIFT Microgateway and SWIFT Alliance Gateway (SAG) in case you are using a HSM-based PKI credential to access SWIFT API Services

Java Key Store 1. Setup Java Key Store for the above mentioned PKI credentials 2. Open Configuration database file to configure

Java Key Store properties o Absolute path to the Java Key Store file. o Password for accessing the Java Key Store file.

SWIFT Alliance Gateway (SAG) Trust Alias (if applicable) o Setup SAG TLS certificate alias for 1-way TLS with SAG.

API Gateway Trust Alias

o Setup the SWIFT CA Public Certificate as Trust Alias for 1-way TLS with API Gateway. Please make sure you download SWIFT CA 2K certificate for Live environment and SWIFT CA 4K certificate for the Pilot environment. The instructions for downloading SWIFT CA 2K and 4K Certificates are detailed in the following Knowledge Tip 5024117.

https://www2.swift.com/kb/#/tip/5024117


Identity and Access Management for accessing SWIFT API services using SWIFT Microgateway Product

SWIFT Online Operations Manager is an application that helps an institution Security Officer to control access to SWIFT API Services through Role Based Access Control (RBAC) mechanism. Security Officer administers control who can be authenticated (signed in) and authorized (have permissions) to use resources SWIFT API services within their organisation. For details about working with SWIFT Online Operations Manager (O2M), see Online Operations Management (O2M). To use SWIFT Microgateway to access SWIFT API Services, you need Client Application credentials - Consumer Key and Secret. For details about setting up Client Application credentials on SWIFT Developer Portal, see section Configuring Client Application Credentials for more details. Security Footprints

PKI Certificate Type

SWIFT Interfaces

HSM Certificate SWIFT Microgateway utilizes SAG / SNL integration layer



swift microgateway backward compatibility interface

Documents