Introduction

This document provides the:

• Information and requirements necessary for Clients to integrate to the Paze℠ Service Authorization Server to gain access to Platform APIs (application programming interface) as an authorized Client.
• Information required to onboard Client with credentials.

Process Flow                                                                                

The Paze Platform uses an Authorization Server to authenticate Clients and provide an Access Token to invoke services. The API Client obtains the Access Token from the Paze Authorization Server as seen in the following process flow.

Standards                                                                                     

The PazeSM Authorization Server follows the JSON Web Token (JWT) Profile for OAuth 2.0 ClientAuthentication & Authorization Grants as described in RFC7523 for issuing an Access Token and uses the JWT format. This document provides the information and requirements needed for Clients to integratewith the Paze Authorization Server.

Service Operator Endpoint Definitions

The Paze Authorization Server exposes an endpoint to Clients to allow them to request and obtain an Access Token.

Service Operator Endpoints

• CAT: https://auth.wallet.cat.earlywarning.io/token
• Production: https://auth.wallet.earlywarning.com/token

Request Access Token                                                            

The Client must use bearer authorization to access the service Operator APIs. When using bearer authorization for the Service Operator's APIs, the Client must use the /token endpoint to obtain the Access Token for use.

The Client's API must first authenticate with the OAuth Service using Hypertext Transfer Protocol (HTTP) POST to the /token endpoint. The parameters of the token request are:

Request Parameters

Response Parameters

Error Response

The Authorization Server responds with an HTTP error status code in the event of an error. The response will also include the following parameters with the response:

Client Assertion Example for /Token Endpoint

The following is a JSON sample.

Note: JSON samples are for reference only. Your input will differ from the input seen below.

Content - Type: application / x - www - form - urlencoded Client_assertion:
    < Signed JWT >
    Client_assertion_type: urn: ietf: params: oauth: clientassertion - type: jwt - bearer
Grant_type: client_credentials Scope: profile - search //ZRF
    <
    Signed JWT >
//HEADER
    {
        "kid": "d9a2865e-9e36-11eb-a8b3-0242ac130003",
        "alg": "RS256"
    }.
//PAYLOAD
{
    "iss": "b34c6678-9e36-11eb-a8b3-0242ac130003",
    "sub": "b34c6678- 9e36-11eb-a8b3-0242ac130003",
    "aud": "https://auth.wallet.cat.earlywarning.io",
    "exp": 1616781086,
    "nbf": 1616779276,
    "iat": 1616779276,
    "jti": "e5759732-9e36-11eb-a8b3-1242ac131113",
    "scope": "profile-search"
}.

//SIGNATURE
HS8GyjSiBayr1AvsdPgPJ59ICb4CA2Vefb4P1ggAFape2v20k81Hs5gjqdCUJKwo fJUyr tFxOrs_3PldYp3qfxucHuwKVYWNqq_ ZkpbrC5MbFSEHBH2VGHKmwfErLtfzhRJsFJ8v85gpfLZsWLEtp4J9fdMviP - 7 f - 1 JlrUAaa - TTE060tfDuBvTncndoNtDatI3_HqKgaKeJqBOEMSVll2eXrT5 - WB9Ru8K0idRCiliqZyuRu5eLWRVBKo -
    _ICX3Y96JFQyWnBfwPofTXPAJknWbHJZXjZ_ OqoHS5bm0wVMrNjP10 - KE5TM0bRF9fMNeoEpPmIxVlqjtaH_PW - wHS8GyjSiBayr1AvsdPgPJ59ICb4CA2Vefb4P1ggAFape2v20k81Hs5gjqdCUJKw ofJUy rtFxOrs_3PldYp3qfxucHuwKVYWNqq_ ZkpbrC5MbFSEHBH2VGHKmwfErLtfzhRJsFJ8v85gpfLZsWLEtp4J9fdMviP - 7 f - 1 JlrUAaa - TTE060tfDuBvTncndoNtDatI3_HqKgaKeJqBOEMSVll2eXrT5 - WB9Ru8K0idRCiliqZyuRu5eLWRVBKo -
    _ICX3Y96JFQyWnBfwPofTXPAJknWbHJZXjZ_ OqoHS5bm0wVMrNjP10 - KE5TM0bRF9fMNeoEpPmIxVlqjtaH_PW - w

Example Call and Response from the Client to the Paze /Token Endpoint

The following is a JSON sample.

Note: JSON samples are for reference only. Your input will differ from the input screen below.

POST / token HTTP / 1.1 Host: < bank - hostname >: 443 Timestamp: 1572358410
Date: Fri, 29 Apr 2022 14: 13: 30 GMT
Content - type: application / x - www - form - urlencoded

client_assertion = eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJodHRwczovL3Rlc 3 QuZW50aXR5LmNvbTo3NDQzL2F1dGgvcmVhbG1zL2djcCIsInN1YiI6InhJRC13 ZWIiLCJhdWQiOiJodHRwczovL2F1dGguZXdzaW5ub3ZhdGlvbnMuY29tL2F1dGg vcmVhbG1zL2JhbmtpZ C9wcm90b2NvbC9vcGVuaWQtY29ubmVjdC90b2tlbiIsImV4cCI6IjE1ODUzMTcw NzUiLC JuYmYiOiIxNTg1MzE1MjY1IiwiaWF0IjoiMTU4NTMxNTI3NSIsImp0aSI6IjE0O WE0ZDM 5 LWI0MzQtNGRlYy1hZTg5LTUxNmFhMGI5YmMyZiJ9.YOnSi6M9to8 -
    pc0fECaRcRLvi_Xt8SuFFA6t37zDdyhXc97aFBYYu63VszuInmiKM7F16BwjuFY EHY5whDxUe4qHp1u1aVgw3K67LI5yWqkw8OO5kG - fFAPlUcbpcv8j7ZTY6jvLqq41xkb_hSfcFP0YriFLamXWDb8m09aWdL9P9YRbYd v1UlMBdopoMIJ4VGcWn_boWyiG8yRdtalYm8wtSsf0kelFJXzAaTNi8h45aswYW DimEXc8aCTP25S0g7aSRu8AeEXD4CxnHJV5galEcuWKbRs5NxDZ8EsVYVwvqbB6 Lv7pHT3bTOByaTBK9q4KCH0fp8QUa4wbT9xw & client_assertion_type = urn: ietf: params: oauth: client - assertiontype: jwt - bearer & grant_type = client_credential

HTTP / 1.1 200 OK
Content - Type: application / json;
charset = UTF - 8 Content - Length: 653
Date: Tue, 29 Oct 2019 14: 13: 29 GMT {
    "access_token": "FmbyEeRFwAfDKVu7DXhFqEHIa8Q",
    "token_type": "bearer"
    "expires_in": 3600
}

Example Error Response:
    HTTP / 1.1 400 Bad Request
Content - Type: application / json;
charset = UTF - 8 Content - Length: 68
Date: Fri, 29 Apr 2022 14: 13: 29 GMT {
    "error": "invalid_request"
}

Onboarding Requirements

This section details out the connectivity and onboarding process details for Clients.

Connectivity                                                                                 

Connectivity between the Service and Clients will be via public internet facing endpoints. These endpointswill be secured with Transport Layer Security (TLS) or optionally with Mutual Transport Layer Security (mTLS).

Authentication

The Service Operator exposed APIs can be mutually authenticated via TLS (mTLS) and should be securedusing either signed JWT, private_key_jwt, or the Access Token issued by the Service Operator This requires an onboarding step of exchanging certificates and establishing the Open ID Connect (OIDC) client_id between the Service and the Client

For the Service Operator endpoints, the Service Operator will support API authentication using OAuth2 (2-legged OAuth). This involves the Service issuing a client_id to the Client during onboarding.

CAT Public Endpoint Information

• TLS: https://auth.wallet.cat.earlywarning.io/token
• mTLS: https://mtls.auth.wallet.cat.earlywarning.io/token

The Customer Acceptance Testing (CAT) environment is an upper environment with endpoints that must beexposed to the internet. The Service conducts penetration testing and threat modeling to ensure proper controlsare in place prior to opening up the endpoints to the internet. Until those controls are in place, Clients wishingto integrate need their external Service Operator Address Translation (NAT) to be whitelisted. In addition, during this period, testing must be conducted on devices coming from the Client Service Operator.

Production Public Endpoint Information

• TLS: https://auth.wallet.earlywarning.com/token
• mTLS: https://mtls.auth.wallet.earlywarning.com/token

TLS Specifics                                                                                

All endpoints exposed by the Paze Service will require Client side support of TLS 1.2.

TLS CIPHERS

The following table lists all the ciphers supported by the Service.

TLS Certificates

The Service will provide certificate details upon request for each of the environments. These will be signed bya trusted public root Certification Authority (CA) (e.g. Digicert).

Client Requirements                                                                

In order to integrate with the Paze CAT and production environments, Clients must provide JWKS keys orendpoint for each of the two environments. Production will be provisioned after successful connectivity in CAT.

Authentication Credentials

The Service will provision the Client into the Platform. The Service will provide a client_id for the Client to be used in the JWT. The Service require either a public JWKS endpoint for the Client (preferred), or alternatively The Service See Appendix A: Creating a JWKS Public Key Structure in JSON for details on howto create the required JWKS keys.

Certificates

If the optional mTLS from the Client to the Platform is to be used, the Client must provide their supporting certificate.

Abbreviations and Acronyms

Definitions

Creating a JWKS Public Key Structure in JSON

To enable access to JWKS-formatted information, a Client will provide a public key structure to PazeSM Service to host. The key structure is a set of public keys that are used to sign or encrypt/decrypt JWK-formatted information.

Considerations                                                                           

• The JWKS keys must be derived from certificates obtained from a recognized certificate authority, such asDigiCert. Self-signed certificates are not supported for production environments.
• The Paze Customer Acceptance Testing (CAT) environment is considered the same as the Production (Prod) environment from a security point of view.
• The certificates must be in a .pem format.
• Two certificates are required in the JWKS structure, one for signing and one for encryption.

The following steps can be used to create a key structure in the required JSON format:

1. Extract the public key from the .pem file using:
   opensslx509 -in certificate.pem -pubkey - noout
2. Access the website https://russelldavies.github.io/jwk-creator/ to create the JWK
   for each of the two required certificates, including:
   • The signing certificate
   • The encryption certificate
3. Using the JWK Creator site, populate the following fields to create an encryption
   public key:
   • Public Key Use: select Encryption
   • Algorithm: select RS256
   • Key ID: Enter a unique key to be used to lookup this certificate in the
     structure. A GUID or UUID is often used for this purpose and can be
     obtained from https://www.guidgenerator.com/.
   • PEM encoded key: Enter the public key found in the .pem file.

Note: Copy/Paste can be used to populate this field. The key field does not appear to be editable, but it will allow pasting in the contents of the public key.

4.     Click Convert. The resulting JWK is displayed.

where the:

• 'n' value is the public key.
• 'alg' is 'RS256'
• 'use' is 'enc' for encryption

Public Key Use field.

5. To create a signing public key, perform Steps 3 and 4, selecting Public Key Use: Signing.

Prepare the JSON Code                                                          

The encryption and signing JSON elements are combined into a single JSON array using the following format:

Note: There are separate array elements for the encryption key and the signing key.

{
    "keys": [{
            "use": "enc"
        },
        {
            "use": "sig"
        }
    ]
}

Note: There are separate array elements for the encryption and signing key.

The JSON code syntax can be checked using https://jsonlint.com/.