swift microgateway version 1.0.6 getting started guide

SWIFT Microgateway Version 1.0.6 Getting Started Guide

SWIFT Microgateway version 1.0.6 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

Getting Started with SWIFT Microgateway ............................................................................................ 6

Sign up for SWIFT API Services ............................................................................................................ 6

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

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

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

Setup Firewall and Forward Proxy Infrastructure ............................................................................... 7

Download the SWIFT Microgateway .................................................................................................. 8

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

Applying SWIFT Microgateway Patch Releases .................................................................................. 9

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

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

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

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

Set Environment Variables ............................................................................................................ 12

API Sandbox Connectivity ............................................................................................................. 12

Starting the SWIFT Microgateway ................................................................................................ 14

Configuration Data ........................................................................................................................ 14

Configuring Microgateway using Microservices ........................................................................... 26

SAG Switchover ................................................................................................................................. 29

Setting up equivalent or federated DNs for resiliency ..................................................................... 29

Using the SWIFT Microgateway ............................................................................................................ 30

Run the tests using Postman Collections .......................................................................................... 30

Making a business call....................................................................................................................... 31

Creating a secured JWT ................................................................................................................. 32

API Response Processing ............................................................................................................... 33

Stopping the Microgateway .............................................................................................................. 35

Health check and Metrics ................................................................................................................. 35

Exception Handling ........................................................................................................................... 38

API requests failing at SWIFT Microgateway ................................................................................ 38

API errors returned by SWIFT’s API Gateway ............................................................................... 39

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

Using Docker for SWIFT Microgateway ............................................................................................ 41

Integrate SWIFT Microgateway with Kubernetes ............................................................................. 43


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

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

Java Key Store ............................................................................................................................... 46

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

Product .......................................................................................................................................... 46


SWIFT Microgateway 1.0.6 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 without the need for a software upgrade or application restart. SWIFT Microgateway automatically downloads latest API Specifications from SWIFT’s Central API Repository and refreshes itself on a regular basis. This feature ensures SWIFT Microgateway is fully up-to-date with the API services and the versions supported by the API service providers. **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” and applicable to every MGW instance. 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.

Pre-Requisites The SWIFT Microgateway is compatible and qualified 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

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/


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

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

Setup Client Application Credentials

Promote Client Application Credentials to Pilot and Live Environments

Setting up a Business Certificate

Setup Firewall and Forward Proxy Infrastructure

Download the SWIFT Microgateway

Sign up for SWIFT API Services 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 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

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. The earliest implementation date is the second Saturday from the ordering date. For instance, order placed on 2nd Nov 2020 can be requested for provisioning on 14th Nov 2020.


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. Use Reference link on the Developer Portal for promoting your client application. Refer to Step 4 of the Getting Started section for details on Application Promotion to Pilot / Live environment.

Setting up a Business Certificate 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.

5. If you are using a Business certificate that is stored on a disk (soft certificate or channel certificate), then configure the Business certificate alias “and password by creating the Soft Certificate profile c.f. Setting up SWIFT Microgateway.

Setup Firewall and Forward Proxy Infrastructure Communication between the SWIFT Microgateway and the API services is secured. The SWIFT infrastructure only allows incoming communication from a known SWIFTNet Link IP address

https://developer.swift.com/

https://developer.swift.com/reference

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



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.

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 behavior:

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

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

https://developer.swift.com/


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

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.6, whereas a minor version includes a sub-version (fourth digit) at the end as follows 1.0.6.1. 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.6.1, 1.0.6.2, 1.0.6.3 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-1.0.6.jar with swift-mgw-1.0.6.1.jar in the bin directory.

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

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


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 config folder.

Configure following properties within the file

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

o Microgateway Port Information

port It is defaulted to 9003, 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_store_password Password for accessing the key store file. Set swift_microgateway.ssl.key_store_password 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 -genkeypair -keyalg RSA -alias <CERTIFICATE ALIAS> -keystore <KEYSTORE LOCATION>/mykeystore.jks -storepass <PASSWORD> -validity 360 -keysize 2048 -dName cn=<HOSTNAME> <CERTIFICATE ALIAS> should be defined in lower case and < HOSTNAME> must be the actual domain name (not the localhost):


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>] ;AUTO_RECONNECT=TRUE <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.

filePassword Set the passwords for accessing the database file. Set the services/metadata/filePassword attribute.

userPassword Set the database user password. Set the

services/metadata/userPassword attribute.

h2_console_enabled Set the value of this variable to “false” if you would like

to disable H2 configuration console. Set it to “true” if you would like to use H2 console for configuration.

o Logging Properties

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

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

o API Management Properties

Set the elements and attributes required for configuration management using APIs. You need an API keys for using Configuration and Management APIs.

Configuration APIs apikey: You must create a symmetric key that business application and SWIFT Microgateway share for Configuration APIs. You can configure Business Applications, Client Application credentials, Key Store, SAG and HTTP Proxy using the Configuration APIs. Set the services/api/configuration/security/apikey attribute within the application properties file. Management API apikey: You must create a symmetric key that business application and SWIFT Microgateway share for Management APIs. You can activate a SAG instance, get current active SAG instance using the Management APIs. Set the services/api/management/security/apikey attribute within the application

properties file.


Monitoring API apikey: You must create a symmetric key that business application and SWIFT Microgateway share for Monitoring APIs. You can retrieve Healthcheck and other SWIFT Microgateway application metrics using the Management APIs. Set the services/api/monitoring/security/apikey attribute within the application

properties file.

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 script to encrypt the configuration YAML file. Run the encrypt.sh (Linux) or encrypt.cmd (windows) to encrypt the configuration YAML file. The script prompts user to enter password to the secret file: 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. Upon execution, the script creates an encryption file and secret file. The secret file is used for decryption. The original file is deleted from the disk.

Decrypt the properties file

If you have to modify the configuration after encryption, then run the decrypt.sh (Linux) or decrypt.cmd (windows) to decrypt the configuration YAML file.

Set Environment Variables

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.

API Sandbox Connectivity

You can run SWIFT Microgateway in one of the following modes:

Sandbox

Test and Training (aka pilot)

Live You can try out any API in the sandbox environment by accessing the sandbox URL https://sandbox.swift.com. Sandbox environment access is free, meaning the Sandbox APIs are

available without API subscription. Sandbox package is present in the packages folder in the MGW package.. The Sandbox Package has following contents:

gpi Tracker v4 Open API Specification

https://sandbox.swift.com/


demo.jks which includes API Gateway public certificate for Sandbox environment and a sample self-signed certificate

Please go through the following steps to enable the SWIFT Microgateway in a Sandbox mode: 1. Copy the OAS spec SWIFT-API-gpi-4.0.1-swagger.json from the package to oas/local-api-

repository of Microgateway. 2. Start the Microgateway using the start command. Refer to Start the Microgateway section for

details. 3. Ensure that the environment in the config-swift-mgw.yaml file is set to “SANDBOX”

4. Please start the Microgateway and follow the steps described in the “Configuration Data” section

to setup other Microgateway configuration objects.

Please note that Sandbox only supports soft PKI certificate (no support for HSM certificate). You must use a self-signed certificate for PKI sign purposes. You can simply use the soft certificate with alias “selfsigned” from demo.jks file or create a self-signed soft certificate of your own.

a. Use the Key Store API to setup Sandbox APIGW certificate. Please use the certificate with alias “sandbox_pub” from demo.jks. Set the password as “Abcd1234”

b. Use the Key Store API to create self-signed Soft Certificate. Please use the certificate with alias “selfsigned” from demo.jks.

c. Update Business Application Soft Certificate Profile – Update the softCertificateprofile values CertificateAlias and keyStorePath

Once you have configured the above, please proceed with following configuration for doing the APIs. Refer to “Configuration Data” section for details.

a. Business Application APIs b. Client Application Credentials APIs for a Business Application


Starting 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).

You should use SWIFT Microgateway configuration and management APIs to setup your Microgateway configuration. The Open API Specifications of which are available in the “/mgw/oas/internal” directory of SWIFT Microgateway package. They are stored as “SWIFT-API-mgw-configuration-api-1.0.3-swagger.json” and “SWIFT-API-mgw-management-api-1.0.3-swagger.json” and “SWIFT-API-mgw-monitoring-api-1.0.0-swagger”.

Business Application APIs

Creating a Business Application Creates the Business Application object. Give the Business Application a unique name and shared secret. Application Name is a free format string identifying your application – “paymentTracker”. Shared Secret is a 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. You can also create one or more application service profiles that are applicable to the Business Application. An application service profile comprises of ProfileId, RBACScope and SAG Service Profile. ProfileId is a literal that must be unique per Business application. RBACScope is session scope that can be requested up to the granularity of API Services, RBAC role Qualifier Name and Qualifier Value(s). Scope must be defined as a list of <Service Name>/<RBAC role>/<QualifierName>/</QualifierValue> pairs with a “/” separating each component. Only <ServiceName> is mandatory. All other components are optional. There are multiple ways to specify RBAC scope: 1. Full access to an API service Specify service name as scope i.e., scope=<serviceName>.


Example, scope=swift.apitracker 2. Restricted access to an API service limited by one or more RBAC role Specify service name and RBAC role as scope i.e., scope=<serviceName>/<RBAC role> Examples, scope=swift.apitracker/FullViewer scope=swift.apitracker/FullViewer swift.apitracker/Update 3. Fine grained access to an API service limited by one or more RBAC role and Qualifier Name and

values Specify service name, RBAC role, QualfierName and Qualifier Value as scope Examples, scope=swift.apitracker/FullViewer/scope/swhqbebb scope=swift.apitracker/FullViewer/scope/swhqbedd scope=swift.apitracker/FullViewer/swhqbebb swift.apitracker/Update/swhqbebb scope=swift.apitracker/FullViewer/swhqbebb/ swhqbedd swift.apitracker/Update/swhqbebb/ swhqbedd 4. Access to multiple API services Specify all the service name with in the scope value with each separated bz a space i.e., scope=<serviceNameA> . <serviceNameB> Example, scope=swift.apitracker swift.preval You can add granularities specified in sections 2, 3 and 4 with each of the service selected above. Example, scope=swift.apitracker/FullViewer swift.preval The above limits session scope for “FullViewer” for gpi API Tracker services whereas provides full access to the gpi pre-validation API service.

SAG Service Profile is the User DN (PKI Certificate) required for establishing an API session with API Gateway or for a Non-Repudiation signature on an API request.

Request Syntax

POST /mgw-configuration-api/1.0.3/business-application HTTP/1.1

Content-type: application/json

X-API-KEY: "string"

{

"applicationName": "string",

"sharedSecret": "string",

"profiles": [

{

"profileId": "string",

"rbacScope": "string",

"sagServiceProfile": [

{

"userDN": "string"

}

]

},

{




{

"userDN": "string"

}

]

}

]

}


Add SAG Application Service Profile to an existing Business Application You can add additional Application service profiles on an existing Business Application by providing Application Name as input parameter. POST /mgw-configuration-api/1.0.3/business-application?applicationName=string

HTTP/1.1


X-API-KEY: "string"

{


"rbacScope": " string ",


{

"userDN": "string"

}

]

}

Update SAG Application Service Profile of an existing Business Application You can add additional SAG service profiles on an existing Business Application by providing Application Name and Application Service Profile Id as input parameters. POST /mgw-configuration-api/1.0.3/business-

application?applicationName=string&profileId=string HTTP/1.1


X-API-KEY: "string"

{

"userDN": "string"

}

Soft Certificate Service Profile is the soft PKI Certificate used for establishing an API session with API Gateway or for a Non-Repudiation signature on an API request.

Request Syntax

POST /mgw-configuration-api/1.0.3/business-application HTTP/1.1


X-API-KEY: "string"

{



"profiles": [

{



"softServiceProfile":

{

"certificateAlias": "string",

"keystorePath": "string"

}

},

{




{



}

}

]


}

Add Soft Certificate Application Service Profile to a Business Application You can add additional Soft Certificate Application service profiles on an existing Business Application by providing Application Name as input parameter. POST /mgw-configuration-api/1.0.3/business-application?applicationName=string

HTTP/1.1


X-API-KEY: "string"

{


"rbacScope": " string ",


{


"keystorePath": "string",

}

}

Update Application Service Profile to a Business Application You can Update Soft Certificate Application service profiles on an existing Business Application by providing Application Name and Application Service Profile Id as input parameters. PUT /mgw-configuration-api/1.0.3/business-



X-API-KEY: "string"

"softServiceProfile": {



}

Get Business Application Info You can retrieve full list of Business Applications by invoking the following API. GET /mgw-configuration-api/1.0.3/business-application HTTP/1.1


X-API-KEY: "string"

Get Business Application Info for a Business Application You can retrieve Business Application info by providing Application Name as input parameter. GET /mgw-configuration-api/1.0.3/business-application?applicationName=string

HTTP/1.1


X-API-KEY: "string"

Get Service Profile Info for a Business Application You can retrieve Service Profile info of a business application by providing Application Name and Profile Id as input parameters.


GET /mgw-configuration-api/1.0.3/business-



X-API-KEY: "string"

Update Business Application You can update Business Application using the following API method PUT /mgw-configuration-api/1.0.3/business-application?applicationName=string

HTTP/1.1


X-API-KEY: "string"

{


"profiles": [

{




{

"userDN": "string"

} ]

} {




{



}

}

]

}

Update Soft Certificate Application Service Profile of a Business Application You can update Soft Service Profile of a Business Application and Application Profile using the following API method PUT /mgw-configuration-api/1.0.3/business-



X-API-KEY: "string"


{



}

Delete Business Application You can delete a Business Application using the following API method: This Business Application deletion will cascade delete the associated Application Service Profile and SAG Service Profile. DELETE /mgw-configuration-api/1.0.3/business-application?applicationName=string

HTTP/1.1


X-API-KEY: "string"

Delete Application Service Profile of a Business Application


You can delete Application Service Profile of a Business Application using the following API method: This Application Service Profile deletion will cascade delete the associated SAG Service Profile. DELETE /mgw-configuration-api/1.0.3/business-



X-API-KEY: "string"

Delete SAG Service Profile of a Business Application You can delete SAG Service Profile of a Business Application using the following API method: DELETE /mgw-configuration-api/1.0.3/business-

application?applicationName=string&profileId=string&userDN=string HTTP/1.1


X-API-KEY: "string"

Delete Soft Service Profile of a Business Application You can delete Soft Certificate Service Profile of a Business Application using the following API method: DELETE /mgw-configuration-api/1.0.3/business-



X-API-KEY: "string"

Client Application Credentials APIs for a Business Application

Creating a API Client Application Creates the API Client Application object. Give the Business Application a unique name and shared secret. Consumer Key is the API Key obtained from SWIFT Developer portal while registering an Application. Consumer Secret obtained by the developer from SWIFT Developer portal while registering an Application. POST /mgw-configuration-api/1.0.3/api-client-credentials HTTP/1.1


X-API-KEY: "string"

{


"consumerKey": "string",

"consumerSecret": "string"

}

Get Client Application Info You can retrieve full list of API Client Applications and their credentials by invoking the following API. GET /mgw-configuration-api/1.0.3/api-client-credentials HTTP/1.1


X-API-KEY: "string"

[

{




"consumerSecret": "string "

},

{




}

]

Update API Client Application credentials You can update API Client Application credentials using the following API method: PUT /mgw-configuration-api/1.0.3/api-client-credentials?applicationName=string

HTTP/1.1


X-API-KEY: "string"

{



}

Delete API Client Application Credentials You can delete a API Client Application credentials using the following API method. DELETE /mgw-configuration-api/1.0.3/api-client-credentials?applicationName=string

HTTP/1.1


X-API-KEY: "string"

Key Store APIs

Creating Key Store for SAG or SWIFT API Gateway TLS certifcate Creates the SAG Key store object. If you have multiple SAG infrastructure, you could create one or more SAG instances as depicted below. Path is location of the trust alias for SAG and APIGW TLS certificates. Create separate entries for SAG and APIGW in the Key Store Info object. Type can be set to “SAG” or “APIGW” or “SOFT_CERT”. Use “SAG” for creating storing SAG certificate, “APIGW” for storing SWIFT CA Certificate and “SOFT_CERT” for storing a disk based SWIFT CA issued Software / Channel Business Certificate. Password Password for accessing the Java Key Store file. Certificate Alias Alias name corresponding to the PKI certificate in the java key store. Refer to Key Store Info object. Certificate Alias Password: Password corresponding to the Soft PKI certificate in the java key store. Refer to Key Store Info object. Only Applicable to SOFT_CERT.

API for creating SAG or APIGW certificate in the key store

POST /mgw-configuration-api/1.0.3/keystore HTTP/1.1


X-API-KEY: "string"


{

"path": "string",

"type": "SAG",

"password": "string",

"certificates": [

{

"alias": "string"

},

{

"alias": "string"

},

{

"alias": "string"

}

]

}

API for creating Soft / Channel certificate in the key store POST /mgw-configuration-api/1.0.3/keystore HTTP/1.1


X-API-KEY: "string"

{

"path": "string",

"type": "SOFT_CERT",


"certificates": [

{

"alias": "string",

"password": "string"

}

]

}

Get Key Store Info You can retrieve full list of Key Store Info by invoking the following API. GET /mgw-configuration-api/1.0.3/keystore HTTP/1.1


X-API-KEY: "string"

Update SAG Certificate Alias within a Key Store Info You can update Key Store Info using the following API method. PUT /mgw-configuration-api/1.0.3/keystore?path=/test.jks&type=SAG HTTP/1.1


X-API-KEY: "string"

{


"certificates": [

{

"alias": "string"

},

{

"alias": "string"

}

]

}

Update APIGW Certificate Alias within a Key Store You can update certificate alias within a Key Store using the following API method.


PUT /mgw-configuration-api/1.0.3/keystore?path=/FileName&type=APIGW&alias=string

HTTP/1.1


X-API-KEY: "string"

{

"alias": "string"

}

Update Soft Certificate Alias within a Key Store You can update Soft certificate alias within a Key Store using the following API method.

PUT /mgw-configuration-api/1.0.3/keystore?path=/FileName&type=SOFT_CERT HTTP/1.1


X-API-KEY: "string"

{

“password”:”string”,

“certificates”:

[

{

"alias": "string",


},

{

"alias": "string",


}

]

}

or PUT /mgw-configuration-

api/1.0.3/keystore?path=/FileName&type=SOFT_CERT&alias=string HTTP/1.1


X-API-KEY: "string"

{


}

Delete Certificate Alias from Key Store You can delete a certificate alias within a Key Store using the following API method.

DELETE /mgw-configuration-

api/1.0.3/keystore?path=\Filename&type=<SAG|APIGW|SOFT_CERT>&alias=string HTTP/1.1


X-API-KEY: "string"

SAG Configuration and Management with APIs

Creating a New SAG Instance: Use the SWIFT Microgateway Configuration API to create new SAG instances – “POST /sag”. Using the API, you to define a new SAG instance and 1 or more Message Partners corresponding to the SAG instance. You must have setup “Key Store Info” objects already in order to use APIs for creating SAG Instances. POST /mgw-configuration-api/1.0.3/sag HTTP/1.1



X-API-KEY: "string"

{

"hostname": "string",

"port": number,

"messagePartner": [

{

"userDN": "string",

"messagePartnerName": "string"

}

],

"lauKey": "string",

"sslDN": "string",

"active": boolean,

"trustStorePath": "string",

"certificateAlias": "string"

}

Get existing SAG Instances: Use the SWIFT Microgateway Configuration API to retrieve existing SAG instances – “GET /sag”. The API returns all SAG instances and their corresponding Message Partners. GET /mgw-configuration-api/1.0.3/sag HTTP/1.1


X-API-KEY: "string"

Update an existing SAG Instance: Use the SWIFT Microgateway Configuration API to update

existing SAG instances – “PUT /sag”. Using the API you can modify SAG instance parameters like

lauKey and sslDN. You can also add Messaging Partners to the SAG instance.

PUT /mgw-configuration-api/1.0.3/sag?hostname=string&port=string HTTP/1.1


X-API-KEY: "string"

{

"messagePartner": [

{

"userDN": "string",

"messagePartnerName": "string"

}

],

"lauKey": "string",

"sslDN": "string",

"trustStorePath": "string",


"active": boolean

}

Delete an existing SAG Instance: Use the SWIFT Microgateway Configuration API to delete an existing SAG instance including the Message Partner – “DELETE /sag” by providing SAG host name and port as input parameters. DELETE /mgw-configuration-api/1.0.3/sag?hostname=string&port=string HTTP/1.1


X-API-KEY: "string"

Delete an existing SAG MessagePartner: Use the SWIFT Microgateway Configuration API to delete an existing Messaging Partner of a SAG instance – “DELETE /sag” by providing SAG host name, port and userDN as input parameters. DELETE /mgw-configuration-api/1.0.3/sag?hostname=string&port=string&userDN=string

HTTP/1.1


X-API-KEY: "string"


Get current active SAG Instance: Use the SWIFT Microgateway Management API to retrieve existing active SAG instance – “GET /sag/active”. GET /mgw-management-api/1.0.3/sag/active HTTP/1.1


X-API-KEY: "string"

Activate SAG Instance: Use the SWIFT Microgateway Management API to activate SAG instance – “PUT /sag/active”. PUT /mgw-management-api/1.0.3/sag/active HTTP/1.1


X-API-KEY: "string"

{

"hostname":"string",

"port": Number

}

HTTP Proxy APIs

If you are using HTTP Forward Proxy(s), create separate entries for each HTTP Proxy instance applicable to API environment. Creating a HTTP Proxy: Use the SWIFT Microgateway Configuration API to create HTTP Proxy instances – “POST /sag”. Using the API, you to define a new SAG instance and 1 or more Message Partners corresponding to the SAG instance. User name and Password for connecting to HTTP Proxy. Only required if a HTTP Proxy is protected with User name and password. PUT /mgw-configuration-api/1.0.3/forward-proxy HTTP/1.1


X-API-KEY: "string"

{

"hostname": "string",

"port": Number,

"user": "string",


}

Get existing HTTP Proxies: Use the SWIFT Microgateway Configuration API to retrieve existing HTTP Proxy instances – “GET /forward-proxy”. The API returns all HTTP Proxy instances. GET /mgw-configuration-api/1.0.3/forward-proxy HTTP/1.1


X-API-KEY: "string"

Update an existing Forward Proxy Instance: Use the SWIFT Microgateway Configuration API to

update existing SAG instances – “PUT /forward-proxy”. Using the API you can modify forward proxy

instance. PUT /mgw-configuration-api/1.0.3/forward-proxy?hostname=string&port=string HTTP/1.1


X-API-KEY: "string"

{

"user": "string",


}


Delete an existing Forward Proxy Instance: Use the SWIFT Microgateway Configuration API to delete an existing SAG instance including the Message Partner – “DELETE /forward-proxy” by providing host name and port as input parameters. DELETE /mgw-configuration-api/1.0.3/forward-proxy?hostname=string&port=string

HTTP/1.1


X-API-KEY: "string"

Open API Specification (OAS) Repository APIs

SWIFT Microgateway at regular intervals automatically downloads latest API Specifications from SWIFT’s Central API Repository and refreshes itself on a regular basis. This feature ensures SWIFT Microgateway is fully up-to-date with the API services and the versions supported by the API service providers. Microgateway also provides an option to force an update to the OAS repository with the following management API: GET /mgw-management-api/1.0.3/oas-repository

HTTP/1.1


X-API-KEY: "string"

SWIFT Microgateway provides an alternative means for manually inputting Open API Specifications through a Local API Repository when the centrally downloaded specifications do not include the desired APIs. By default, the folder is empty. Add API specifications to the Local API Repository folder as illustrated below.

Format the specification file names as: SWIFT-API-<service-name>-<version>-swagger.json Use the following management API to enable the API service consumption through SWIFT Microgateway: GET /mgw-management-api/1.0.3/oas-repository?source=LOCAL

HTTP/1.1


X-API-KEY: "string"


Configuring Microgateway using Microservices

Please note that configuring Application Properties and Starting the SWIFT Microgateway are pre-requisites for bootstrapping Microgateway configuration. Use the configure-mgw.sh to bootstrap the “Configuration Data” mentioned in the above section. The script file includes a list of CURL commands using which you can setup Microgateway configuration data. The command sequence complies with the database schema definition; hence, the sequence is important to configure data correctly. The script includes CURL commands for creating:

Business Application

Business Application Client Credentials

Keystore Configuration for SAG

Keystore Configuration for API Gateway

SAG Configuration

HTTP Proxy Please note that the CURL command must be run by configuring SWIFT Microgateway in 1-way TLS mode. At the end of the script file, there is a CURL command for testing the connectivity to SWIFT API Platform. The command performs a heartbeat test to gpi Tracker application. Copy the script and the jar to the Microgateway bin directory. Open the script file; replace the attribute values with the values applicable to your environment. Update the other CURL commands with appropriate values in the script file similarly. Once you completed editing the script file, execute the script passing Application Name, Profile Id, Configuration API Version and Shared Secret as input parameters. Application Name and Profile Id are “applicationName”, “profileId” of Business Application object and “sharedSecret” is the key assigned to the Business Application (attribute values from the first CURL command in the script file). Here is the script populated with example values: #Creating a business application and SAG Service Profile.

curl -k -X POST \

https://localhost:9003/swift/mgw/mgw-configuration-api/1.0.4/business-application

\

-H 'Content-Type: application/json' \

-H 'cache-control: no-cache' \

-H 'X-API-KEY: Abcd1234Abcd1234Abcd1234Abcd1234' \

-d '{

"applicationName": "BO1",

"sharedSecret": " PoWeTp4ebM3pzq5ZQBqD5ObVSFTC78lt", "profiles": [

{

"profileId": "trackerProfile1",

"rbacScope": "swift.apitracker!p",


{

"userDN": "cn=tom,o=citius33,o=swift"

}

]

bash configure-mgw.sh <ApplicationName> <profileId> <sharedSecret> <MGW host> <MGW port>


},

{

"profileId": "trackerProfile2",

"rbacScope": "swift.apitracker!p/FullViewer",


{

"userDN": "cn=harry,o=citius33,o=swift"

}

]

}

]

}'

#Creating consumer key and secret of a business application.

curl -k -X POST \

https://localhost:9003/swift/mgw/mgw-configuration-api/1.0.4/api-client-

credentials \




-d '{

"applicationName": "BO1",

"consumerKey": "wPw08RotyIn0T0Ir00xxnA0PNqv5h1O7",

"consumerSecret": "AhQqeDUtuLyBjGZg"

}'

#Creating keystore for SAG.

curl -k -X POST \

https://localhost:9003/swift/mgw/mgw-configuration-api/1.0.4/keystore \




-d '{

"path": "/opt/mgw/keystore/keystore.jks",

"type": "SAG",

"password": "I887B9078@13!",

"certificates": [

{

"alias": "mawx6027"

}

]

}'

#Creating keystore for APIGW.

curl -k -X POST \

https://localhost:9003/swift/mgw/mgw-configuration-api/1.0.4/keystore \




-d '{

"path": "/opt/mgw/keystore/keystore.jks",

"type": "APIGW",

"password": "I887B9078@13!",

"certificates": [

{

"alias": "swift2kca"

}

]

}'

#Creating a SAG instance.

curl -k -X POST \

https://localhost:9003/swift/mgw/mgw-configuration-api/1.0.4/sag \




-d '{

"hostname": "mawx6027",

"port": 48002,

"messagePartner": [

{

"userDN": "cn=tom,o=citius33,o=swift",


"messagePartnerName": "sni_relaxed_sdk"

}

],

"lauKey": "Abcd1234Abcd1234Abcd1234Abcd1234",

"sslDN": "CN=SWIFTAlliance Gateway SAG1",

"trustStorePath": "/opt/mgw/keystore/keystore.jks",

"certificateAlias": "mawx6027",

"active": true

}'

#Creating a HTTP Proxy.

curl -k -X POST \

https://localhost:9003/swift/mgw/mgw-configuration-api/1.0.4/forward-proxy \




-d '{

"hostname": "10.8.15.130",

"port": 48002,

"user": "fptest",

"password": "W9ht76”34mJio4543@!"

}’

You can verify the results of the CURL commands printed on the screen. The script can also be used to setup multiple instances of objects. This can be done with multiple executions of the script with each execution creating a new instance of the data object i.e., data must conform to the unique constraint principle.


SAG Switchover You can take benefit of building resilient SAG infrastructure by configuring multiple SAG instances using the SAG Configuration API c.f. SAG Configuration and Management with APIs. SWIFT Microgateway

Setting up equivalent or federated DNs for resiliency Each Alliance Gateway instance has its own set of security DNs that the applications use to sign and authorise messages. Each security DN is stored in a PKI profile. From an application point of view, this creates a dependency between a security DN and an Alliance Gateway instance. In some configurations it may be necessary to share a security DN between different Alliance Gateway instances. The DN equivalence Alliance Gateway feature makes it possible to set up such configurations, by hiding the Alliance Gateway instance-specific security DNs. An application that uses this feature can work with several Alliance Gateway instances in a transparent way. Please refer to the Alliance Gateway – Administration and Operations Guide documentation for setting up DN equivalence. Rules for security DN equivalence Security DNs are equivalent when the following conditions are fulfilled:

Each DN must share the same Role-Based Access Control (RBAC) role. An application that requires this role can use any of these DNs.

Each DN must share all the nodes except the last (deepest) one. The syntax of this last node must be: cn=%i where: i is an integer This syntax complies with the certificate equivalence scheme presented in the SWIFTNet PKI Certificate Administration Guide.

The PKI profile corresponding to each DN must be present in only one Alliance Gateway instance.

Each DN must have a corresponding real PKI profile in the Alliance Gateway database. SWIFT Microgateway Configuration Create Business Application Service Profile with the Security DN (User DN) value set as common DN. For instance, configure common DN cn=sign,o=bic8,o=swift if you have following equivalent DNs configured on Alliance gateway instances.


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-1.0.6.3.postman_collection.json” into Postman.

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

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

ProfileId – Session ProfileId setup for API business service within the Application Service

Profile object of configuration database.

SharedSecret - Shared Secret Key setup for the Business Application in the Business

Application object of the configuration database.


6. 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 following HTTP Headers with the business API Authorization Set it to “Bearer <token>”. Refer to Creating a secured JWT section for more details. X-SWIFT-Signature A boolean indicating whether a Non-Repudiation signature is required on API call or not. Set it to “true” for secure API methods and “false” when using simple API methods.


Creating a secured JWT To arrive at the compact representation from the JSON versions of the header and the payload, perform the following steps:

Take the header as a byte array of its UTF-8 representation. The JWT spec does not require the JSON to be minified or stripped of meaningless characters (such as whitespace) before encoding.

Encode the byte array using the Base64-URL algorithm, removing trailing equal signs (=).

Take the payload as a byte array of its UTF-8representation. The JWT spec does not require the JSON to be minified or stripped of meaningless characters (such as whitespace) before encoding.

Encode the byte array using the Base64-URL algorithm, removing trailing equal signs (=).

Concatenate the resulting strings, putting first the header, followed by a “.” character, followed by the payload. Validation of both the header and the payload (with respect to the presence of required claims and the correct use of each claim) must be performed before encoding.

<token>:=base64URLEncode(<Header>).base64URLEncode(<Payload>).<Signature>

<Header>:= {

"alg": "HS256",

"typ": "JWT"

}

<Payload>:= {

"iss":<Backoffice Application Identifier>

"profileId": <BO ProfileId>,

"exp":<Expiry Datetime>,

"iat": <Issue At Datetime value>,

"absPath": <absPath value complying to RFC 2616>,

"digest": <base64 URL encoded optional Digest Value of payload – applicable to POST/PUT operations>,

"jti": <Unique identifier for the JWT>,

"nr": <Optional Non-Repudiation claim, only set when making a Non-Repudiation API Call. Value must be set to true.>

}

<Signature>:= HMACSHA256(base64URLEncode(<Header>) + "." + base64URLEncode(<payload>),<sharedSecret>)

The below java code snippet illustrates JWTcreation and verification logic which is available in the com.swift.api.mg.utils.security.jws. AuthorizationJWSService.java file.


Sample Client Application Code

API Response Processing SWIFT Microgateway upon receiving API response from the API service provider creates a compact and self-contained JSON object (JWT) for securely transmitting the response to the Back Office application. SWIFT Microgateway adds the bearer token in the Authorization Header when sending the response to the Back Office Application. The JWT is formatted as following:

<token>:=base64URLEncode(<Header>).base64URLEncode(<Payload>).<Signature>

<Header>:= {

"alg": "HS256",

"typ": "JWT"

}

public String buildPayload(String busAppName, String profileId, String path, Object payload) {

JwtClaims claims = new JwtClaims();

claims.setGeneratedJwtId();

claims.setIssuer(busAppName);

claims.setClaim("profileId", profileId);

claims.setIssuedAtToNow();

claims.setExpirationTimeMinutesInTheFuture(30);

claims.setClaim("absPath", path);

String digest = calculateDigestValue(payload);

if (digest != null) {

claims.setClaim("digest", digest);

}

return claims.toJson();

}

public String sign(byte[] jwtPayload, Object sharedKey) throws AuthorizationException {

logger.debug("Start JWS generation.");

if (sharedKey == null) {

logger.error("JWS generation failed. Shared key is not provided.");

throw new AuthorizationException("JWS generation failed. Shared key is not provided.");

}

if (!(sharedKey instanceof String)) {

logger.error("JWS generation failed. Provided shared key is not string object: " +

sharedKey.getClass());

throw new AuthorizationException("JWS generation failed. Provided shared key is not String

object: " + sharedKey.getClass());

}

try {

return sign(new String(jwtPayload), (String) sharedKey);

} catch (JoseException e) {

logger.error("JWS generation failed.", e);

throw new AuthorizationException("JWS generation failed.", e);

}

}

private static String sign(String jwsPayloadStr, String sharedKey) throws JoseException {

JsonWebSignature jws = new JsonWebSignature();

jws.setPayload(jwsPayloadStr);

jws.setAlgorithmHeaderValue(AlgorithmIdentifiers.HMAC_SHA256);

jws.setHeader("typ", "JWT");

Key key = new HmacKey(sharedKey.getBytes());

jws.setKey(key);

jws.sign();

return jws.getCompactSerialization();

}


<Payload>:= {

"iss":<Original Backoffice Application Identifier>,

"profileId": <Original Back Office ProfileId>,

"exp":<Expiry Datetime>,

"iat": <Issue At Datetime value>,

"absPath": <absPath as received in the request>,

"digest": <Optional Digest Value of response payload when present>,

"jti": <jti received in the request>,

"nr": <Optional Non-Repudiation flag as sent with the API Request>

}

<Signature>:= HMACSHA256(base64URLEncode(<Header>) + "." + base64URLEncode(<payload>),<sharedSecret>)

Sample Client Application Code for verifying JWT

public boolean verify(AuthDataContainer authContainer, Object sharedKey, String busAppName,

String profileId, String absPath, String requestBody) throws AuthorizationException {

……

}

public boolean verify(String jwsPayload, Object sharedKey) throws AuthorizationException {

logger.debug("Start JWS signature verification.");

if (sharedKey == null) {

logger.error("JWS validation failed. Shared key is not provided.");

throw new AuthorizationException("JWS validation failed. Shared key is not provided.");

}

if (!(sharedKey instanceof String)) {

logger.error("JWS validation failed. Provided shared key is not string object: " +

sharedKey.getClass());

throw new AuthorizationException("JWS generation failed. Provided shared key is expected to

be String object but received: " + sharedKey.getClass());

}

try {

JsonWebSignature jws = new JsonWebSignature();

jws.setCompactSerialization(jwsPayload);

jws.setAlgorithmConstraints(new

AlgorithmConstraints(AlgorithmConstraints.ConstraintType.WHITELIST, AlgorithmIdentifiers.HMAC_SHA256));

Key key = new HmacKey(((String) sharedKey).getBytes());

jws.setKey(key);

return jws.verifySignature();

} catch (JoseException e) {

logger.error("Authorization validation failed.", e);

throw new AuthorizationException("Authorization validation failed.", e);

}

}


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-swift-mgw.sh for Linux or stop-

swift-mgw.cmd command for Windows.

Health check and Metrics You should use SWIFT Microgateway monitoring APIs to retrieve application performance, availability and usage metrics. The Open API Specifications of which are available in the “/mgw/oas/internal” directory of SWIFT Microgateway package. They are stored as “SWIFT-API-mgw-monitoring-api-1.0.0-swagger.json”. Health

Shows application health information. The response includes API Gateway, Disk Space and SAG health information.

GET /mgw-monitoring-api/1.0.0/health HTTP/1.1


X-API-KEY: "string"

Application Information Shows the application information. The response includes

TLS Certificate Expiry Info of applications SWIFT Microgateway, API Gateway and SAG instances

Java Runtime and Build versions

Current Log Level configuration GET /mgw-monitoring-api/1.0.0/info HTTP/1.1


X-API-KEY: "string"

Request Trace Displays HTTP trace information (by default, the last 100 HTTP request-response exchanges). GET /mgw-monitoring-api/1.0.0/httptrace HTTP/1.1


X-API-KEY: "string"

http.server.requests The metric provides following types of information:

Number of requests

Total time taken to process requests

Maximum Response Time

Summary of HTTP Requests and their response status codes GET /mgw-monitoring-api/1.0.0/metrics/http.server.requests HTTP/1.1


X-API-KEY: "string"


Jetty threads pool metrics

jetty.threads.busy The number of busy threads in the pool jetty.threads.config.max Maximum number of threads in the pool jetty.threads.config.min Minimum number of threads in the pool jetty.threads.current The total number of threads in the pool jetty.threads.idle The number of idle threads in the pool jetty.threads.jobs Number of jobs queued waiting for a thread

Buffer info jvm.buffer.memory.used An estimate of the memory that the Java virtual machine is using for this buffer pool. jvm.buffer.total.capacity An estimate of the total capacity of the buffers in this pool.

jvm.buffer.count

An estimate of the number of buffers in the pool.

Class load information

jvm.classes.loaded

The number of classes that are currently loaded in the Java virtual machine

jvm.classes.unloaded

The total number of classes unloaded since the Java virtual machine has started execution

JVM garbage collection Metrics for getting insights into how the JVM is managing memory. jvm.gc.live.data.size Live old generation pool size. jvm.gc.memory.allocated Memory pool size increases of the young generation memory pool. jvm.gc.memory.promoted Size increases of the old generation jvm.gc.pause Gives information about how long garbage collection took

JVM memory metrics jvm.memory.committed Dedicated memory per area (for ex. heap, nonheap areas)


jvm.memory.max Shows how much memory is available jvm.memory.used Shows how much memory has been used.

JVM memory metrics These metrics allow to see active threads in a JVM jvm.threads.daemon Total number of daemon threads jvm.threads.live Current total number of live threads including both daemon and non-daemon threads jvm.threads.peak The peak total number of threads since the JVM started jvm.threads.states Shows how many threads are in each thread state

Logging info

logback.events Number of trace level events that made it to the logs

Process information process.cpu.usage The recent CPU usage for JVM process

process.start.time Start time of the process since unix epoch

process.uptime The uptime of the Java virtual machine

System information system.cpu.count Total number of processors available to the JVM system.cpu.usage Current number of processors are used.


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 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 JWS authentication failure between API Client Application and SWIFT Microgateway. SWIFT Microgateway provides information such as:

HTTP status code – 401 for Authentication failures, 400 for Bad Requests, 500 for all other errors

Error – Defaulted to “MGW”

Detailed error message The errors returned on a Business API request shall conform to the following:

Error Scenario Severity Description Text

401 UnAuthorized FATAL JWS validation failed. Absolute paths from JWS and http request mismatch.

Authorization failed. JWS is not provided.

Authorization failed. Auth header is not Bearer token.

Authorization failed. JWS structure is invalid.

JWS validation failed. Required claims can't be extracted.

JWS generation failed. Provided shared key is not String object: {class name}.

JWS generation failed. Shared key is not provided.

JWS validation failed. Shared key is not provided.

JWS generation failed. Provided shared key is expected to be String object but received:{className}

JWS validation failed. Profile ID for specified Application ID is invalid. Check Microgetaway configuration.

JWS validation failed. Expiration time can't be extracted.

JWS validation failed. Token has been expired.

JWS validation failed. Payload digest is invalid.

JWS validation failed. Absolute paths from JWS and http request mismatch.

JWS validation failed. JWS type is unexpected.

JWS validation failed. JWS is not provided.

JWS validation failed. Provided auth container is expected to be JWS but received:{className}.

500 Temporary FATAL Requested service path is not allowed! Request is blocked!

Combination of requested service name and version is not allowed! Request is blocked!

Business Application Profile configuration not found in database by business application name:{name}


Error Scenario Severity Description Text

There is no active SAG in persistence storage.

Key storage configuration for SAG is missed. Check MGW persistence storage set up.

"Key storage configuration for API Gateway is missed. Check MGW persistence storage set up.

NR signature calculation failed. HSM context can't be created.

Failed to sign NR request using SAG: {hostname} +{message}

Failed to extract PEM certificate. 1-way TLS connection with SAG can't be established.

Get OAuth token failed :{reason}

Some examples of errors returned by the SWIFT Microgateway are: 400 Bad Request { "status": { "severity": "FATAL", "code": "MGW", "text": "Requested service path is not allowed! Request is blocked!" } } The above error indicates the requested API service or API method is not supported by SWIFT Microgateway i.e., the API service or method is not part of the list of API specifications downloaded from Central API Repository or added from Local API Repository. See section “Configuration Data” for API Specification Repository details. 401 Unauthorized { "error_code": "MGW", "error_description": "Authentication Failed. JWS is invalid", } 500 Internal Server Error { "error_code": "MGW", "error_description": "java.net.SocketTimeoutException: timeout", } Note: SWIFT Microgateway does not add JWT token in the HTTP response for those API requests failing at SWIFT Microgateway.

API errors returned by SWIFT’s API Gateway

A SWIFT API Gateway exception are generally technical exceptions, it indicates a problem with API Request received from the API client. This exception represents an API Gateway processing error. This can be because for the following reasons: API request is malformed, Authotisation Token (OAuth Token) provided is invalid, API Service in unreachable etc., API Gateway returns an exception in the following JSON format: SWIFT API Gateway provides information such as:

Returned status code

Returned Severity

Detailed error message from the service provider


Some examples of errors returned by the API Gateway are: { "status": { "severity": "Fatal", "code": "SwAP503", "text": "OAuth access token has insufficient scope for the requested service." } } { "status": { "severity": "Fatal", "code": "SwAP506", "text": "Resource does not exist." } } { "status": { "severity": "Fatal", "code": "SwAP510", "text": "The API method does not support non-repudiation." } } Note: SWIFT Microgateway creates JWT token and adds it as Authorization header in the HTTP response. You must refer to the API Open API Specification (OAS) on SWIFT Developer Portal for the full list of errors returned by SWIFT API Gateway.

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

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


{ "status": { "severity": "Fatal", "code": "INVA/X001", "text": "Syntax error" } } Note: SWIFT Microgateway creates JWT token and adds it as Authorization header in the HTTP response. You must refer to the API Open API Specification (OAS) on SWIFT Developer Portal for the full list of errors returned by a Service Provider Application.

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 Docker documentation.

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, 9003

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>/mgw-config-console/login.jsp

You can setup SAG infrastructure by accessing the relevant APIs on following URL

Configuration APIs - https://<dockerhost>:<port>/swift/mgw/mgw-configuration-api/1.0.0/ Management APIs - https://<dockerhost>:<port>/swift/mgw/mgw-management-api/1.0.0/

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/mgw/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>/mgw-config-console/login.jsp

You can setup SAG infrastructure by accessing the relevant APIs on following URL

Configuration APIs - https://<public-node-ip>:<node-port>/swift/mgw/mgw-configuration-api/1.0.0/

Management APIs - https://<public-node-ip>:<node-port>/swift/mgw/mgw-management-api/1.0.0/

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/mgw/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 Business Certificate 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 recommended 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

4. Setup software certificate in your Java Key Store (JKS) if you are accessing SWIFT provided API service using a disk-based certificate.

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.

Software Certificate

o Setup the Software Certificate alias (User DN) for establishing a secure session with API Gateway.

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

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




PKI Certificate Type

SWIFT Interfaces

HSM Certificate SWIFT Microgateway utilizes SAG / SNL integration layer

Software Certificate SWIFT Microgateway directly access the Software Certificate that is available on the disk

Creating a Software Certificate 1. The BIC8 on which the Software (Channel) Certificate is created must have subscription to swift.channel

SWIFTNet service 2. Log in to O2M and access "Certificate Management - User" screen. 3. Select parent DN from the hierarchy under which the User DN is created (for example:

o=bossus33,o=swift). 4. Click New on the bottom right corner. 5. Enter the USER DN name (for example: cn=gpi-app-cert). 6. Click Certify OK. 7. Click Sign 8. Click OK to proceed with certification 9. Select “Channel” as certificate class. 10. Click Sign 11. Click OK to obtain the “Reference Code” and “AuthCode”

Certificate Signing Request and Adding certificate to JKS 1. Certificate Signing Request

Run the following command in order to create a Certificate Signing Request. $JAVA_HOME/jre/bin/keytool -genkeypair -alias USER1 -keyalg RSA -keysize 2048 -dname “<USER 1 DN >” -keypass <keystore password> -keystore <keystore file name>-storepass <keystore password> -storetype JKS

2. Adding certificate to JKS Run the following command to add the Java Key Store.

$JAVA_HOME/jre/bin/keytool -certreq -alias USER1 -file <Certificate Request File Name> -keypass < keystore password> -keystore <keystore file name> -storepass < keystore password>

Downloading a Software Certificate 1. To download a software certificate for production use, use one of the following addresses:

• https://wbcl01.swiftnet.sipn.swift.com:49171/cda-cgi/clientcgi?action=start • https://wbcl02.swiftnet.sipn.swift.com:49171/cda-cgi/clientcgi?action=start

2. Press enter. The browser then displays the page Entrust Authority Enrollment Server for Web.

3. In the area To create user certificates, select one of the following options, click Create Web Server Certificate from PKCS#10 Request. The browser then displays the page Web Server PKCS#10 Certificate Request.

4. Make sure that you have the reference number and the authorisation code that you received from the security officer.

5. In the Options drop-down list, select displayed as PEM encoding of certificate in raw DER. 6. Paste the certificate-signing request in the text box and Click Submit Request. A certificate is

returned. 7. Save the PEM encoded certificate in a text file (e.g. C:\\SWIFT\\User1DN.pem to install). Import certificate to Java Keystore (JKS) 1. $JAVA_HOME/jre/bin/keytool -import -trustcacerts -alias SWIFTCA -file C:\\SWIFT\\CACertificate.pem –

keystore <keystore file name> –storepass <keystore password>

2. $JAVA_HOME/jre/bin/keytool -import -alias <USER1> -file C:\\SWIFT\\sdk-pilot.pem -cert -keystore <keystore file name> -storepass <keystore password>

https://wbcl01.swiftnet.sipn.swift.com:49171/cda-cgi/clientcgi?action=start

https://wbcl02.swiftnet.sipn.swift.com:49171/cda-cgi/clientcgi?action=start

swift microgateway version 1.0.6 getting started guide

Documents