Authorization to Gateway

Overview

Prahsys Gateway API uses SSL/TLS client certificate authentication to ensure secure and authenticated communication. This method provides a high level of security and is ideal for server-to-server communication. We use HTTPS with client certificates (mutual TLS) for authentication. This method offers several advantages:

  1. Strong Security: Client certificates provide a more robust form of authentication compared to API keys or basic auth.
  2. Mutual Authentication: Both the client and server authenticate each other, preventing man-in-the-middle attacks.
  3. Non-repudiation: Each request is cryptographically signed, providing proof of the sender's identity.

Requirements to Start

Before you can get started, you need these prerequisites below. You must also follow the best security practices to ensure your client certificate is secure. If at anytime you feel that your certifcate is compromised, please contact the Prahsys Team immediately and we will issue another certifcate and disable the other.

1. PFX File

2. Obtain KEY for PFX File

Security Best Practices

1. Protect the Certificate

2. Use Environment Variables

3. Enforce TLS Version

Getting Started

Once you have completed the above requirements, test your client certificate via openssl:

Test the client certificate


openssl pkcs12 -info -in path/to/your/certificate.pfx -noout -passin pass:your_password

Example Outputs

MAC: [REDACTED], Iteration [REDACTED]
MAC length: [REDACTED], salt length: [REDACTED]
PKCS7 Encrypted data: PBES2, PBKDF2, AES-[REDACTED]-CBC, Iteration [REDACTED], PRF [REDACTED]
Certificate bag
Certificate bag
Certificate bag
PKCS7 Data
Shrouded Keybag: PBES2, PBKDF2, AES-[REDACTED]-CBC, Iteration [REDACTED], PRF [REDACTED]

How to Authenticate the Request

What's happening here?

Unlike traditional Bearer token authentication, this approach uses a client certificate - think of it as a secure ID card for your application. The code sets up this "ID card" (PFX file) and its PIN (passphrase) to create an HTTPS client that automatically proves your identity with each request to our server.

Why is this better?

This method offers enhanced security over token-based auth. Your "ID card" can't be easily copied or forged, and each request is cryptographically signed. There's no need for token management or refreshing, simplifying your code. It also enables mutual authentication, where both your app and our server verify each other's identity, providing robust protection against man-in-the-middle attacks. While initial setup may seem complex, it simplifies daily operations and provides stronger, low-maintenance security for your API interactions with the Prahsys Gateway.

Authenticate your API Request

AUTH
Examples of how to authenticate your API Request to the gateway
// Create an HTTPS agent with client certificate authentication
const httpsAgent = new https.Agent({
pfx: fs.readFileSync(process.env.GATEWAY_PFX_FILE),
passphrase: process.env.GATEWAY_API_KEY,
minVersion: 'TLSv1.2' // Enforce minimum TLS version for security
});

// Create an Axios client instance with custom configuration
const client = axios.create({
httpsAgent,
baseURL: 'https://secure.prahsys.com',
});

// Make a GET request to the '/information' endpoint
client.get('/information');

Technical Details of Authentication

  1. Client initiates connection request to a protected server resource.
  2. Server presents its certificate chain to the client.
  3. Client verifies server's certificate using its trust store.
  4. If successful, client sends its certificate chain from its key store to the server.
  5. Server verifies client's certificate:
    • Checks X.509 format
    • Validates certificate path
    • Performs CRL or OCSP checking
    • Checks expiration
  6. If server validation succeeds, the certificate chain is passed to DirectAPI for further verification:
    • Matches subject common name with merchant database record
    • Verifies Key-Usage extension for client authentication
    • Validates client certificate against allowed CA root certificates
    • Checks certificate type (production/test) against merchant profile status
  7. If all checks pass, the connection is accepted and the operation request proceeds.
  8. If any check fails, the connection is rejected with an appropriate error message.