Light Dark Auto

Enable OIDC Guarded Edge for Mesh

Greymatter Version

  • v1.8.0

Using the greymatter operator with GitOps makes it simple to add an OIDC provider to your edge gateway. This guide will use Keycloak as the OIDC provider.

Configure Keycloak

In Keycloak, you will need to set up a realm and client (if you haven’t already done so) and ensure the client is using the OIDC protocol. Specifically, you must give Keycloak a URL that redirects back to your edge node.

  1. Log in to Keycloak
  2. Select the menu item named ‘Clients’
  3. From the list of client IDs, select the ID you want to associate with this edge node.
  4. Add a URL of the form https://{EXTERNAL_IP_OR_DNS_HOSTNAME}:{PORT}/oauth to the list of Valid Redirect URIs. Upon successful authentication, users will be redirected back to this address with tokens that the edge node’s OIDC filter can parse.

Enable OIDC Filters

In <your-org>/greymatter-core repository, open gm/outputs/edge.cue and set _enable_oidc_authentication to true.

This will enable a few filters on your edge proxy’s ingress listener:

  • OIDC Authentication - the primary filter that will connect to your OIDC provider and handle the authentication flow
  • Ensure Variables - passes headers from OIDC Authentication filter to Envoy JWT Authentication filter
  • Envoy JWT Authentication JSON Web Token (JWT) verification filter for JWT token validation and use of token claims to retrieve user identification and access policies

Configure OIDC Authentication

Set values in inputs.cue in <your-org>/greymatter-core repository. This will configure the OIDC Authentication filter. Locate the oidc configuration block and set the following values:

  • endpoint_host - the IP or hostname of your Keycloak server
  • endpoint_port - the port of your Keycloak server. Keep the default value.
  • domain - the external IP or hostname of your mesh
  • client_id - the ID of your client in Keycloak
  • client_secret - the secret from your client in Keycloak (credentials tab).
  • realm - the name of your realm in Keycloak

In addition, you may also need to set _keycloak_pre_17 field to true if using a Keycloak version less than version 17.

To configure TLS options between the filter and Keycloak, for instance, in the case of mTLS or to trust a set of privately minted certs, set a combination of these values:

  • certPath - Path to the server’s certificate (mTLS)
  • keyPath - Path to the server’s private key (mTLS)
  • caPath - Path to the server’s bundled intermediate and root CA certificates
  • insecureSkipVerify - Boolean determining whether to skip certificate verification

Configure Envoy JWT Authentication

Configure the Envoy JWT Authentication filter. In the jwt_authn_provider block in inputs.cue set the following values:

  • audiences - the name of your client in Keycloak

Determine how you want to verify JWTs issued from Keycloak. JSON Web Key Set (JWKS) is a set of keys containing the public keys used to verify these JWTs. Greymatter provides two types of configurations, local and remote JWKS verification.

Local JWKS Verification

Local JWKS Verification allows you to statically configure the key used to verify the JWTs. To do this, you can navigate to https://KEYCLOAK_HOST:KEYCLOAK_PORT/realms/YOUR_REALM/protocol/openid-connect/certs. Then paste the keys directly into the inline_string field in inputs.cue.

The benefit of this approach is that an additional network call does not need to be made to Keycloak to verify JWTs. The drawback is that, if the keys change in Keycloak, you must also update it in inputs.cue. Without doing so will cause authentication errors for your users.

Remote JWKS Verification

Remote JWKS Verification solves the drawbacks of Local JWKS Verification with only the added latency of an additional network call to Keycloak to verify JWTs. Latency will vary depending on your infrastructure set up but it generally goes unnoticed to your users.

To enable Remote JWKS Verification, comment out local_jwks in inputs.cue and the remote_jwks block.

When using remote JWKS, you will also need to add cluster, route, domain, and listener objects to your edge proxy to allow the OIDC Auhentication filter to validate the JWT, along with a few more changes to ensure that greymatter can discover the new cluster. To do so, uncomment the line at the top of <your-org>/greymatter-core/gm/outputs/edge.cue, along with the commented out objects. You will also need to modify the proxy object to look like the following:

#proxy & {
  proxy_key: defaults.edge.key
  domain_keys: [defaults.edge.key, EgressToRedisName, EdgeToKeycloakName]
  listener_keys: [defaults.edge.key, EgressToRedisName, EdgeToKeycloakName]

Apply and Verify

Now that all configurations are in place, you can push your changes to <your-org>/greymatter-core repository and OIDC authentication will be configured on your edge gateway. When you navigate to https://{EXTERNAL_IP}:10808 you will be redirected to Keycloak for authentication.