DEV Community

Cover image for 2-Way SSL in Apigee X: A Beginner's Guide to Mutual TLS (mTLS)
realNameHidden
realNameHidden

Posted on

2-Way SSL in Apigee X: A Beginner's Guide to Mutual TLS (mTLS)

#apigee #mtls #2wayssl

APIs power almost everything we use today—from mobile banking and online shopping to healthcare applications and enterprise systems. But here's a question:

How do you know the client calling your API is really who they claim to be?

Imagine you're entering a highly secure building.

  • The security guard checks your ID before letting you in.
  • But before showing your ID, you also verify that the guard actually works for the company.

Both sides verify each other's identity before exchanging any sensitive information.

This is exactly how 2-Way SSL, also known as Mutual TLS (mTLS), works.

Unlike traditional HTTPS, where only the server proves its identity, 2-Way SSL in Apigee X requires both the client and the server to authenticate each other using digital certificates.

If you're working with banking APIs, healthcare systems, government services, or enterprise integrations, understanding 2-Way SSL in Apigee X is an essential skill.

In this guide, you'll learn:

  • What 2-Way SSL is
  • How Mutual TLS works
  • Why organizations use it
  • How to configure it in Apigee X
  • Best practices and common mistakes
  • Real-world use cases

What is 2-Way SSL (Mutual TLS)?

Normally, when you open a secure website, your browser verifies the website's certificate.

Client
   │
   │ HTTPS Request
   ▼
Server
   │
   │ Sends Certificate
   ▼
Client verifies Server
Enter fullscreen mode Exit fullscreen mode

The server proves its identity.

The client does not.

This is called One-Way SSL.

With 2-Way SSL, both sides exchange certificates.

        Mutual Authentication

Client                     Server
   │                          │
   │----Client Hello--------->│
   │<---Server Certificate----│
   │----Client Certificate--->│
   │<----Certificate Verify---│
   │
Secure Encrypted Connection Established
Enter fullscreen mode Exit fullscreen mode

Now both parties trust each other.

Why Do We Need 2-Way SSL?

Think of entering an airport.

With One-Way SSL:

  • You verify the airport is legitimate.
  • The airport doesn't verify who you are.

With Mutual TLS:

  • You verify the airport.
  • The airport verifies your passport.

Only authorized travelers enter.

This significantly improves API security.

How Does 2-Way SSL Work in Apigee X?

Let's understand the complete flow.

+--------------------+
| API Client         |
| Client Certificate |
+---------+----------+
          |
          | HTTPS Request
          |
          ▼
+-----------------------+
| Apigee X              |
| Verify Client Cert    |
+-----------+-----------+
            |
            |
            ▼
+-----------------------+
| Backend Service       |
| HTTPS                 |
+-----------------------+
Enter fullscreen mode Exit fullscreen mode

Apigee X validates the client certificate before forwarding the request to the backend service.

If the certificate is invalid or missing, the request is rejected immediately.

Key Components

Client Certificate

Identifies the API consumer.

Example:

  • Mobile application
  • Internal service
  • Partner application

Server Certificate

Identifies the API gateway.

Usually issued by a trusted Certificate Authority (CA).

Certificate Authority (CA)

A trusted organization that issues certificates.

Think of it as a government issuing passports.

If the passport is fake, entry is denied.

Truststore

Stores trusted CA certificates.

Apigee uses the Truststore to verify client certificates.

Keystore

Stores server certificates and private keys.

Used by Apigee to present its own identity.

Real-World Use Cases

Banking APIs

Banks require partner systems to present valid certificates before processing transactions.

Healthcare

Patient information is extremely sensitive.

Mutual TLS ensures only authorized hospital systems access medical records.

Government APIs

Government systems use Mutual TLS to protect citizen data and prevent unauthorized access.

Enterprise Microservices

Internal services authenticate each other without relying solely on API keys.

Benefits of 2-Way SSL in Apigee X

✅ Strong client authentication

✅ Prevents unauthorized access

✅ Encrypts communication

✅ Meets compliance requirements

✅ Protects sensitive APIs

✅ Reduces impersonation attacks

Step-by-Step Guide: Configure 2-Way SSL in Apigee X

Step 1: Create Certificates

Generate:

  • Server certificate
  • Client certificate

Example using OpenSSL:

# Generate Client Private Key

openssl genrsa -out client.key 2048

# Generate CSR

openssl req -new -key client.key -out client.csr

# Generate Certificate

openssl x509 -req \
-in client.csr \
-signkey client.key \
-out client.crt \
-days 365
Enter fullscreen mode Exit fullscreen mode

Step 2: Upload Certificates

In Apigee:

Admin

↓

Environment

↓

Keystore

↓

Upload Server Certificate
Enter fullscreen mode Exit fullscreen mode

Create another Truststore.

Upload the trusted CA certificate.

Step 3: Configure Virtual Host

Enable Mutual TLS.

Example (conceptual):

<VirtualHost name="secure-host">

    <SSLInfo>

        <Enabled>true</Enabled>

        <ClientAuthEnabled>true</ClientAuthEnabled>

        <KeyStore>gateway-keystore</KeyStore>

        <TrustStore>trusted-client-ca</TrustStore>

    </SSLInfo>

</VirtualHost>
Enter fullscreen mode Exit fullscreen mode

Explanation:

  • Enabled enables HTTPS.
  • ClientAuthEnabled requires clients to present a certificate.
  • KeyStore stores the server certificate.
  • TrustStore stores trusted CA certificates.

Step 4: Call the API

Example using curl:

curl https://api.example.com/orders \
--cert client.crt \
--key client.key
Enter fullscreen mode Exit fullscreen mode

If the certificate is valid:

HTTP 200 OK
Enter fullscreen mode Exit fullscreen mode

Otherwise:

HTTP 403 Forbidden
Enter fullscreen mode Exit fullscreen mode

Complete Authentication Flow 

              API Request

      +----------------------+
      |     API Client       |
      +----------+-----------+
                 |
                 | Client Certificate
                 |
                 ▼
       +----------------------+
       |     Apigee X         |
       | Verify Certificate   |
       +----------+-----------+
                  |
        Certificate Valid?
          /              \
        Yes              No
         |                |
         ▼                ▼
 Backend Service     Reject Request
                      HTTP 403
Enter fullscreen mode Exit fullscreen mode

Common Errors

Certificate Expired 

SSL Handshake Failed
Enter fullscreen mode Exit fullscreen mode

Renew the certificate before it expires.

Wrong Truststore

The CA is not trusted.

Upload the correct CA certificate.

Missing Client Certificate

The client forgot to send a certificate.

Apigee rejects the request.

Certificate Doesn't Match Private Key

The certificate and key belong to different pairs.

Generate a matching certificate/key pair.

Best Practices

1. Use Certificates from a Trusted CA

Avoid self-signed certificates in production unless your organization's security policy explicitly permits them.

2. Rotate Certificates Regularly

Never keep certificates active for many years.

Automate certificate renewal where possible.

3. Protect Private Keys

Never:

  • Commit private keys to Git
  • Store them in source code
  • Share them through email or messaging apps

Use secure secret management solutions.

4. Combine mTLS with OAuth 2.0

Mutual TLS verifies who the client is.

OAuth verifies what the client is allowed to access.

Together they provide layered security.

5. Monitor TLS Handshake Failures

Review logs and monitoring dashboards regularly to detect:

  • Invalid certificates
  • Expired certificates
  • Unauthorized access attempts

Common Mistakes to Avoid

❌ Using expired certificates

❌ Forgetting to upload CA certificates to the Truststore

❌ Storing private keys insecurely

❌ Skipping certificate rotation

❌ Assuming HTTPS alone provides client authentication

Conclusion

Securing APIs is about more than encrypting traffic—it’s about ensuring that only trusted clients can access sensitive services.

2-Way SSL in Apigee X (Mutual TLS) provides a robust authentication mechanism where both the client and server verify each other's identity before any data is exchanged. This makes it an excellent choice for financial services, healthcare, government APIs, and enterprise integrations.

As you build more secure APIs, experiment with Mutual TLS in a development environment, observe the certificate exchange, and become familiar with how Apigee X validates client certificates. Hands-on practice is the best way to reinforce these concepts.

Call to Action

Have you implemented 2-Way SSL in Apigee X or are you planning to?

Share your experience, questions, or challenges in the comments—I'd love to hear about them.

If you found this guide helpful, follow for more beginner-friendly articles on:

  • Apigee X
  • API Management
  • API Security
  • OAuth 2.0
  • API Traffic Management
  • Google Cloud

Happy learning!

Helpful Resources

Top comments (0)