ISO 20022 API - How to use

Impel ISO 20022 platform has a distributed architecture, meaning that each platform participant has to have its own gateway service (node) in a platform with dedicated identity provider (Keycloak).

New platform participant has to complete onboarding process:

1. Request for a dedicated node in a platform.

2. Generate API credentials (clientId/clientSecret).

Generate API credentials

Gateway service (node) exposes API which can be used to send messages and get information about them. It uses dedicated Identity Provider (Keycloak) to authenticate and authorize API requests. Gateway service requires JWT token on every requests, which can be obtained from Keycloak, from OpenID Connect token endpoint. In order to get JWT access token we need to first generate clientId/clientSecret.

To secure whole process, we use Keycloak Client Registration feature. That means that platform participants will generate API client credentials.

When new dedicated Gateway service is setup in a network, an email will be sent with Initial Access Token.

With Initial Access Token we need to create Keycloak client by running below command:

curl --request POST "$KEYCLOAK_URL/auth/realms/BBBBCAXXXXX/clients-registrations/openid-connect" \
--header "Authorization: Bearer $INITIAL_ACCESS_TOKEN" \
--header "Content-Type: application/json" \
--data-raw '{
    "redirect_uris": [],
    "client_name": "gateway-client",
    "grant_types": ["client_credentials"],
    "response_types": ["none"]
}'

Response example:

{
    "redirect_uris": [],
    "token_endpoint_auth_method": "client_secret_basic",
    "grant_types": [
        "client_credentials"
    ],
    "response_types": [],
    "client_id": "1d4fa4dc-7883-4964-b9a1-2c29849f2719",
    "client_secret": "j8PD1ZO9E9MAFSPzp0IXwOjIowSJ9frY",
    "client_name": "gateway-client",
    "subject_type": "public",
    "request_uris": [],
    "tls_client_certificate_bound_access_tokens": false,
    "client_id_issued_at": 1666016078,
    "client_secret_expires_at": 0,
    "registration_client_uri": "http://localhost:8081/auth/realms/BBBBCAXXXXX/clients-registrations/openid-connect/1d4fa4dc-7883-4964-b9a1-2c29849f2719",
    "registration_access_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI0MTg3ZjdmOS1kMzEwLTQzMTQtOWE5YS0wMjdkYjM0YjI0YmMifQ.eyJleHAiOjAsImlhdCI6MTY2NjAxNjA3OCwianRpIjoiY2RkNTM4MzktOTJiNC00NmNiLThmYjAtZDdiNmYzNTcyYjQ0IiwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgxL2F1dGgvcmVhbG1zL0JCQkJDQVhYWFhYIiwiYXVkIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgxL2F1dGgvcmVhbG1zL0JCQkJDQVhYWFhYIiwidHlwIjoiUmVnaXN0cmF0aW9uQWNjZXNzVG9rZW4iLCJyZWdpc3RyYXRpb25fYXV0aCI6ImF1dGhlbnRpY2F0ZWQifQ.QZMXkInEB_-4e8Pjzd0lkIpPQqRL662S-1kcdWTNWgU",
    "backchannel_logout_session_required": false,
    "require_pushed_authorization_requests": false
}

Extract client_id and client_secret fields. From now we can use these credentials to get OAuth2 JWT token from Identity Provider (Keycloak).

When you create a client through the Client Registration Service the response will include a registration access token. The registration access token (registration_access_token) provides access to retrieve the client configuration later, but also to update or delete the client. The registration access token is included with the request in the same way as a bearer token or initial access token. Registration access tokens are only valid once, when it’s used the response will include a new token.