Mutual TLS Client Authentication

You are browsing documentation for an outdated plugin version.

Mutual TLS client authentication

The OpenID Connect plugin supports mutual TLS (mTLS) client authentication with the IdP. When mTLS authentication is enabled, Kong establishes mTLS connections with the IdP using the configured client certificate.

You can use mTLS client authentication with the following IdP endpoints and corresponding flows:

• token
  • Authorization Code Flow
  • Password Grant
  • Refresh Token Grant
• introspection
  • Introspection Authentication flow
• revocation
  • Session Authentication

For all these endpoints and for the flows supported, the plugin uses mTLS client authentication as the authentication method when communicating with the IdP, for example, to fetch the token from the token endpoint.

Requirements for an mTLS client auth configuration

Auth server configuration

The feature requires the IdP to be enabled to use mTLS and X.509 client certificate authentication. For configuring this in Keycloak, refer to the Keycloak configuration section below. For different auth servers, refer to their documentation to configure this functionality.

Kong configuration

• Set the client authentication methods. Refer to the configuration reference sections:
  • client_auth
  • token_endpoint_auth_method
  • introspection_endpoint_auth_method
  • revocation_endpoint_auth_method
• Configure the client certificate ID as a value for the tls_client_auth_cert_id field as described in the configuration reference.

Certificates

For mTLS connections, create a certificate and key pair for Kong Gateway to use when connecting to the IdP:

http -f post :8001/certificates cert@crt.pem key@key.pem

SSL verify

The configuration option tls_client_auth_ssl_verify controls whether the server (IdP) certificate is verified.

When set to true (the default value), ensure trusted certificate and verify depth are appropriately configured so that the IdP’s server certificate is trusted by Kong and the handshake can be performed successfully.

Demo

Prerequisites

Follow these prerequisites to set up a demo Keycloak app and a Kong service and route for testing mTLS client auth.

In most cases, the OpenID Connect plugin relies on a third party identity provider (IdP). The examples in this guide use Keycloak as a sample IdP.

Expand the following sections to configure Keycloak and Kong Gateway.

<socket-binding name="https" port="${jboss.https.port:8443}"/>

<socket-binding name="https" port="${jboss.https.port:8440}"/>

Set up mTLS for the OIDC plugin

Using the Keycloak and Kong Gateway configuration from the prerequisites, set up an instance of the OpenID Connect plugin.

For the demo, we’re going to set up the following:

• Issuer, client ID: Settings that connect the plugin to your IdP (in this case, the sample Keycloak app).
• client_auth: Must use TLS (tls_client_auth).
• Auth methods: For demo purposes, we use the password grant, but you can use any supported auth method.
• tls_client_auth_cert_id: Pass the ID of the certificate object you created via /certificates.

With all of the above in mind, let’s test out mTLS client auth with the password grant, using Keycloak as the IdP. Enable the OpenID Connect plugin on the openid-connect service:

curl -X POST http://localhost:8001/services/{serviceName|Id}/plugins \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --data '
    {
  "name": "openid-connect",
  "config": {
    "issuer": "http://keycloak.test:8080/auth/realms/master",
    "client_id": "client-tls-auth",
    "client_auth": "tls_client_auth",
    "auth_methods": [
      "password"
    ],
    "tls_client_auth_cert_id": "1e0721c1-fd43-494c-9864-007bbba98c8c"
  }
}
    '

curl -X POST \
https://{us|eu}.api.konghq.com/v2/control-planes/{controlPlaneId}/core-entities/services/{serviceId}/plugins \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer TOKEN" \
    --data '{"name":"openid-connect","config":{"issuer":"http://keycloak.test:8080/auth/realms/master","client_id":"client-tls-auth","client_auth":"tls_client_auth","auth_methods":["password"],"tls_client_auth_cert_id":"1e0721c1-fd43-494c-9864-007bbba98c8c"}}'

echo "
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: openid-connect-example
plugin: openid-connect
config:
  issuer: http://keycloak.test:8080/auth/realms/master
  client_id: client-tls-auth
  client_auth: tls_client_auth
  auth_methods:
  - password
  tls_client_auth_cert_id: 1e0721c1-fd43-494c-9864-007bbba98c8c
" | kubectl apply -f -

kubectl annotate service SERVICE_NAME konghq.com/plugins=openid-connect-example

plugins:
- name: openid-connect
  service: SERVICE_NAME|ID
  config:
    issuer: http://keycloak.test:8080/auth/realms/master
    client_id: client-tls-auth
    client_auth: tls_client_auth
    auth_methods:
    - password
    tls_client_auth_cert_id: 1e0721c1-fd43-494c-9864-007bbba98c8c

terraform {
  required_providers {
    konnect = {
      source  = "kong/konnect"
    }
  }
}

provider "konnect" {
  personal_access_token = "kpat_YOUR_TOKEN"
  server_url            = "https://us.api.konghq.com/"
}

resource "konnect_gateway_plugin_openid_connect" "my_openid_connect" {
  enabled = true

  config = {
    issuer = "http://keycloak.test:8080/auth/realms/master"
    client_id = "client-tls-auth"
    client_auth = "tls_client_auth"
    auth_methods = ["password"]
    tls_client_auth_cert_id = "1e0721c1-fd43-494c-9864-007bbba98c8c"
  }

  control_plane_id = konnect_gateway_control_plane.my_konnect_cp.id
  service = {
    id = konnect_gateway_service.my_service.id
  }
}

Test mTLS client auth

Access the service using the password auth method. Kong will access the IdP’s token endpoint using the mTLS Client Authentication with the configured certificate:

curl http://localhost:8000/openid-connect --user john:doe

If successful, you should receive a 200 status code:

HTTP/1.1 200 OK