SWIFT Security SDK Specification

SWIFT Security SDK Specification
6 January 2022
Confidentiality RESTRICTED - SWIFT User Community

Table of Contents
Introduction ............................................................................................................................................... 3
SWIFT API offering .................................................................................................................................... 3
Installing the Postman Collection........................................................................................................ 5
JSON Web Token and Structure .......................................................................................................... 6
Header ..................................................................................................................................................... 6
Payload .................................................................................................................................................... 6
Signature ................................................................................................................................................. 7
Configuring the Postman Collection .................................................................................................. 8
Establishing a Secure Session with Postman................................................................................ 10
Creating a JWT signed with SWIFTNet PKI for Non-Repudiation ............................................. 12
Postman Runtime Requests and Responses ................................................................................. 13
Request ‘Get Token’ Analysis in Postman ....................................................................................... 13
Response ‘Get Token’ Analysis in Postman .................................................................................... 14
Request NR Signature Analysis in Postman.................................................................................... 14
Calling GPI API Samples ...................................................................................................................... 14
Calling SWIFT Messaging API ............................................................................................................ 16
JWT Debugger Runtime Requests .................................................................................................... 18
Request ‘Get Token’ Assertion in JWT debugger ........................................................................... 18
Request NR Signature in JWT debugger (X-SWIFT-Signature)................................................... 20
Legal Notices........................................................................................................................................... 22
Introduction
SWIFT API offering
To start, we will briefly summarize the four major offerings for SWIFT API connectivity.
1.) SWIFT Microgateway: provides simplified access to SWIFT API services. Known as an API call
concentrator, it enables configuration, management, and monitoring of multiple API
consuming applications. This document will not go into detail about SWIFT Microgateway;
however, more information is available on the Developer Portal: SWIFT Developer Portal |
SWIFT Microgateway
2.) SWIFT Software Development Kit (SDK): Java-based library that hides much of lower-level
application plumbing, including authentication, authorisation, signing and error handling. It
provides a Java-based library to facilitate integration of API-consuming applications. This
document will not go into detail about SWIFT SDK; however, more information is available
on the Developer Portal: SWIFT Developer Portal | SWIFT SDK
3.) SWIFT Security SDK: another Java-based library which is an underlying component of SWIFT
Microgateway and SWIFT SDK offerings. The component is responsible for secure API
session management, non-repudiation and Role-Based Access Control based on SWIFTNet
PKI. This document includes samples that illustrate the order and sequence of steps to
consume APIs. The samples will be the focus of this document. You can find the package on
the Developer Portal: SWIFT Developer Portal | SWIFT SDK
4.) Postman collection: packaged with SWIFT Security SDK containing runnable samples which
enable calls to SWIFT APIs using SWIFTNet PKI channel (software) certificates. It provides a
reference implementation which demonstrates application-level signing, optional non-
repudiation and implementation of oAuth 2.0 session establishment according to RFC 7523.
Understanding the Postman collection provided, similar logic and sequence can be used to
build an interface to SWIFT APIs in any other language or script. This document will explain
the SWIFT Security Specification showcased in the Postman collection.
Overview
We will be looking at the flows necessary for an API client to establish a secure session with the SWIFT
API Gateway and then make API calls. The diagram below highlights the major steps.
The postman collection will create a JSON Web Token claim with a signed assertion and retrieve an
oAuth token from the authorization server (1). This uses the configured software certificate issued by
SWIFT to authenticate and authorize the API client (2). Then the session token will accompany any
further calls to the API endpoints available on the SWIFT API Gateway.
Installing the Postman Collection

Once the SWIFT Security SDK is downloaded from the Developer Portal, the following compressed file is
available: swift-security-sdk-x.x.x.zip. The embedded folder named Postman contains a JSON-formatted
file named “SWIFT Security SDK.postman_collection.” The file can be directly imported into a Postman
installation and will make the SWIFT Security SDK collection available:
Note the directories for ‘sample’, ‘session’ and ‘sandbox’. Also note that the Authorisation Type is set to
Bearer Token for authorisation. This is the method used to acquire an access_token to manage a secure
session with the SWIFT API Gateway.
JSON Web Token and Structure

JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way
for securely transmitting information between parties as a JSON object. In our case, the JWT is used for
authentication between our API client and the SWIFT API Gateway. A JWT is composed of the following
three sections:
Header
The header identifies the object type (in this case a JWT), the algorithm used to sign it, as well as
the x5c that contains the certificate chain to verify the signature.
Payload
The payload contains claims which are the pieces of information that comprise the JWT. There is
an example here with a few brief explanations of the claims that are dynamically handled by the
Postman collection. Those without explanation are covered in more detail in the following
sections, where they require some custom configuration.
Signature
The Header and Payload values are concatenated and Base46-encoded. A signature is calculated
using the privateKey specified and described in the following section. The publicCertificate is
included in the x5c claim in the header of the JWT. This gives the Service Provider everything
necessary to verify the authenticity and integrity of each JWT API request.
For more information about obtaining the privateKey and publicCertificate, see the SWIFT
Microgateway Getting Started Guide in the sections about keystore management and software
certificate creation, or the Developer Portal.
Configuring the Postman Collection

To begin using the collection, several parameters require configuration. Most of them can be found
under the ‘Variables’ tab of the base collection. Some default values are provided; however, most
parameters will be specific to your installation:
The base URL is populated with the address of the API Gateway. This could be in a sandbox
environment, in the Live environment or in a test environment (as shown above).
The session_scope is a mechanism in OAuth 2.0 to limit an application's access to a user's account up to
the granularity of API Services and RBAC roles. A possible value for scope may be ‘swift.apitracker’ or
‘swift.apitracker/FullViewer’.
The consumerKey and consumerSecret are application identifiers used for authentication. They are
available on the SWIFT Developer Portal once an application is created. Creating your own application
enables you to generate a consumerKey and consumerSecret to access the API products in the sandbox
and production environments. Applications can be promoted to other environments. Multiple
applications can be configured for different environments.
The aud is the name for the JSON Web Token (JWT) claim that identifies the recipient of the
authorisation tokens. In this case, it is a URL on the SWIFT API Gateway that will validate the tokens
when establishing a secure session.
The sub identifies the subject of the user. Because the authentication on the API calls uses SWIFTNet PKI
certificates for signing, this value is set to the distinguished name of the certificate obtained from the
SWIFT certificate authority (O2M).
Security officers can use O2M to generate privateKeys and publicCertificates. Once generated, the
privateKey can be configured in the Postman collection. The publicCertificate must be present as SWIFT
maintains multiple CA certificates, and the publicCertificate specified must be the one used when
generating the privateKey. Future enhancements will use Key Management Systems hosted either
locally or in the cloud.
(Important: the fact that Postman keeps a copy of the privateKey in clear text implies that this collection
is for testing purposes and must never be used in a production environment.)
The util-lib does not require any reconfiguration. The value must remain for internal use by the Postman
collection.
The obtain_token_request, refresh_token_request, access_token and refresh_token are placeholder

variables that will be populated and used by the Postman collection during secure session establishment
and subsequent API requests.
In the collection, these variables are duplicated for the sandbox environment. They are configurable in
the same way as the explanations above.
Establishing a Secure Session with Postman

Before an API client (such as Postman) can successfully make API calls, a Secure Session must be
established with the SWIFT API Gateway. Being able to do so will validate the Postman variables that
have been configured in the section ‘Configuring Postman Collection’. The ‘Get Token’ request
additionally requires a session scope variable which maps back to the SWIFTNet service subscriptions
obtained through the ordering of API services.
For more information about using a correct session scope, see the SWIFT Microgateway Getting Started
Guide. The session scope is also sometimes referred to as RBAC Scope.
The grant_type and scope are used to create an assertion which is stored as a Postman variable. These
values are not needed on subsequent API calls after successful session establishment.
To test Secure Session establishment, submit a request to ‘Get Token’ in the session examples of the
Postman collection. The HTTP Response Status will be 200, and the Response Body will resemble the
following:
The access_token is returned with its type and expiry. The Response Body also contains a refresh_token
and its expiry. This token can be used as a parameter to request another access_token within the
validity of the refresh_token.
The tokens are stored in Postman variables. At any time, another API call can be done to ‘Refresh Token’
or ‘Revoke Token’. The refresh will provide another session token. The revoke will unset the token
variables, meaning that it invalidates the Client API Secure Session with the SWIFT API Gateway.
These requests are signed with RS256. The procedure on how to make the request and sign it properly is
outlined in the Postman collection. It is very similar to the following example provided in this document:
‘Creating a JWT signed with SWIFTNet PKI for Non-Repudiation’. The major difference is that the ‘Get
Token’ request creates an assertion with authorisation and scope information, which are not required
for each subsequent API call.
More differences on the JWT used to establish a Secure Session and those used for non-repudiation will
be highlighted in the request and response traces.
The ‘Get Token’ will have a signed assertion in the HTTP Body:
assertion: "eyJ0eXAiOiJKV1QiL……CJhbGciOiJSUzI1Ni”
The NR Signature Request will have an identifiable SWIFT signature in the HTTP Header:
X-SWIFT-Signature: “eyJ0eXAiOiJK…………V1QiLCJhbGciOiJSUzI1NiIsI”
Creating a JWT signed with SWIFTNet PKI for

Non-Repudiation
To begin signing JWTs for the later usage of non-repudiation, the examples provided here and in the
Postman collection aim to provide guidance to the sequence and steps necessary to do so. This makes it
easier to start building API consumer applications in any other programming or scripting language.
For convenience, the following pseudocode is also provided for reference:

Postman Runtime Requests and Responses

Using a sandbox environment, we can easily send ‘Get Token’ requests and responses. The Postman tool
is useful in introspecting them to eventually compare with the requests and responses sent and received
by an application under development. The elements discussed in this document are highlighted for
reference and comparison.
Request ‘Get Token’ Analysis in Postman
Response ‘Get Token’ Analysis in Postman
Request NR Signature Analysis in Postman
Calling GPI API Samples

Once we have a Secure session, the API samples are ready to perform some tests. There are samples for
GPI API, SWIFT Messaging through Alliance Cloud, Transaction Screening API, Payment Pre-Validation
and Cash Management API. We can start with a simple GPI API call to ‘Get Changed Payment
Transactions’ to see which messages that we have in the GPI system. We specify a time window and
click on send:
The result will resemble the following, notice uetr (unique transaction reference) is part of the response:
The uetr refence can be used as a parameter to other GPI API calls for example one to ‘Get Payment
Transaction Details’ on a single transaction
Response:
Calling SWIFT Messaging API

We can use the SWIFT Messaging API to ‘Send an InterAct message to Alliance Cloud.’ We can see the X-
SWIFT-Signature was calculated for us in the Header, and the Request payload contains the original
InterAct message.
The response returns a message_cloud_refence, which confirms that and InterAct message was
accepted by Alliance Cloud.
It closely resembles the use of the FIN messages sample:

JWT Debugger Runtime Requests

The ‘Get Token’ assertion and non-repudiation signatures can be verified by using a debugging tool like
the one freely available at https://jwt.io/. It will reverse the constructions made in the examples and
visualise the content for troubleshooting purposes.
Request ‘Get Token’ Assertion in JWT debugger
Request NR Signature in JWT debugger (X-SWIFT-Signature)

Legal Notices
Copyright
SWIFT © 2023. All rights reserved.
Restricted Distribution
Do not distribute this publication outside your organisation unless your
subscription or orderexpressly grants you that right, in which case ensure
you comply with any other applicable conditions.
Disclaimer
The information in this publication may change from time to time. You must
always refer to thelatest 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. SC. The following are registered
trademarks of SWIFT: 3SKey, Innotribe, MyStandards, Sibos, SWIFT, SWIFTNet,
SWIFT Institute, the Standards Forum logo, the SWIFT logo, SWIFT gpi with logo,
the SWIFT gpi logo, and UETR. Other product, service, or company names in this
publication are trade names, trademarks, or registered trademarks of their
respective owners.

SWIFT Security SDK Specification

Uploaded by

SWIFT Security SDK Specification

Uploaded by

SWIFT Security SDK Specification

Confidentiality RESTRICTED - SWIFT User Community

Installing the Postman Collection

JSON Web Token and Structure

Configuring the Postman Collection

The obtain_token_request, refresh_token_request, access_token and refresh_token are placeholder

Establishing a Secure Session with Postman

Creating a JWT signed with SWIFTNet PKI for

For convenience, the following pseudocode is also provided for reference:

Postman Runtime Requests and Responses

Response ‘Get Token’ Analysis in Postman

Request NR Signature Analysis in Postman

Calling GPI API Samples

Calling SWIFT Messaging API

It closely resembles the use of the FIN messages sample:

JWT Debugger Runtime Requests

Request NR Signature in JWT debugger (X-SWIFT-Signature)

You might also like