The Story Behind Separate Client-Side mTLS for Production and Sandbox Key Types in WSO2 API Manager

Photo by Pixabay: https://www.pexels.com/photo/security-logo-60504/

In earlier versions of WSO2 API Manager (up until v4.3.0), client-side Mutual Transport Layer Security (mTLS) only supported the Production key type. However, starting with API Manager 4.4.0, a new feature has been introduced that allows for both Production and Sandbox key types in mTLS.

This enhancement, which I had the opportunity to design and implement, brings greater flexibility and security to the platform by enabling secure communication with both production and sandbox environments.

How to use this feature

You can access the quick guide here

High level Architecture

This feature revolves around managing TLS (Transport Layer Security) in the communication between the client and the API Gateway, ensuring secure, efficient, and dynamic routing to the appropriate backend environment (production or sandbox).

High level diagram of the request flow for separate client side MTLS. Image by Rusiri Illesinghe

Client:

• Any external entity invoking the gateway endpoint URLs. Examples include tools like cURL or Postman making API calls.

Gateway:

• Acts as the intermediary, exposing a single endpoint URL for both production and sandbox environments.
• In an MTLS scenario, uses client certificates to determine which backend endpoint to invoke.

Visible modifications

1. Server Startup Process

More specifically when consider an API artifact, apart from the other info, it fetches the client certificates of that API into a list and the certificate details (tier name and keytype) are stored in a map indexed by the unique identifier. The map is then stringified and stored as an authProperty, which is set to the ApiAuthenticationHandler.

Later in the execution process, the system determines if the API is MutualSSL Protected, using the API’s security details. If so:

• The MutualSSLAuthenticator is initialized.
• Certificate details are retrieved from the previously created string and inserted into a hashmap.
• The MutualSSL authenticator is added to the list of authenticators for the API.

2. Folder Structure Changes

To enhance support for production and sandbox environments, changes were introduced in how client certificates are stored:

During startup, Gateway Artifacts are generated from the list of API runtime artifacts. A temporary (tmp) directory is created to store these artifacts.

Subdirectory Segmentation within the temporary directories:

• Previously, all certificates were stored directly under a Client-certificates directory, with filenames derived from their aliases.
• Now, due to the possibility of duplicate aliases for production and sandbox certificates, the directory is split into two subdirectories called PRODUCTION and SANDBOX.
• Certificates are stored in these subdirectories based on their environment type.

3. Truststore Alias Changes:

• The truststore alias now includes the key type (e.g., production or sandbox) in addition to the alias value provided for the certificate, to ensure the uniqueness of the entry.

API Import Flow:

• During API import, the system checks for client certificates in the appropriate subdirectory (PRODUCTION or SANDBOX) under Client-certificates.
• If the certificate is not present in the truststore, it is added.
• If the certificate already exists, the corresponding entry is updated.

4. Publisher REST API Changes

The Publisher REST API has been updated to manage the client certificates collection effectively. The details can be accessed in the WSO2 Publisher REST API documentation.

5. Database schema changes

If you are upgrading to WSO2 API Manager 4.4.0 from earlier versions, it is important to note the changes in the database schema, specifically the **AM_API_CLIENT_CERTIFICATE** table.

Benefits for users

1. Enhanced Security

• Isolated Access Control: Separate certificates for Production and Sandbox ensure that only authorized clients can access the respective environments.
• Reduced Risk of Credential Misuse: Clients are required to use distinct credentials for each environment, minimizing the risk of accidental or malicious misuse.

2. Clear Environment Separation

• Dedicated Certificate Validation: Each environment enforces its own certificate validation, ensuring that production and sandbox operations remain independent.
• Environment-Specific Access: Developers can test APIs in the Sandbox without compromising access to the Production environment.

3. Improved Testing and Debugging

• Controlled Testing: The use of a dedicated Sandbox certificate allows testing without affecting production data or services.
• Seamless Transition: Developers can replicate Production configurations in Sandbox with separate credentials, reducing discrepancies between environments.

4. Compliance with Security Best Practices

• Adherence to Policies: Segregating environments aligns with security policies that mandate separate credentials for staging and production systems.
• Auditing and Monitoring: Environment-specific logs help in auditing and monitoring API usage for compliance and troubleshooting.

5. Greater Flexibility in API Management

• Customized Business Plans: Certificates can be tied to specific business plans, enabling fine-grained access control for each environment.
• Scalability: Organizations can scale their environments independently without impacting client configurations.

6. Reduced Risk of Configuration Errors

• Certificate-Specific Aliases: Unique aliases for each certificate minimize the chances of configuration errors that could impact API invocation.
• Explicit Endpoint Differentiation: Developers explicitly choose the target environment (Production or Sandbox) when uploading certificates, ensuring clarity.

7. Simplified Client Management

• Client-Specific Control: Different certificates for each environment allow API publishers to manage and revoke access to a single environment without affecting the other.

Conclusion

Overall, introducing separate client-side mTLS for Production and Sandbox types provides robust security, operational efficiency, and a streamlined API development lifecycle.

For more technical details or to explore related configurations, refer to the official WSO2 documentation.