Light Dark Auto

OIDC Guarded Edge

Greymatter Version

  • v1.8.0

Using the 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 OpenID Connect protocol. The specific change you need to make to support OIDC flow is to add a redirect URI back to your edge gateway.

  • Login to Keycloak
  • Select Clients
  • Select your client ID from the list of clients.
  • Add https://{EXTERNAL_IP_OR_DNS_HOSTNAME}:10808/oauth to the list of Valid Redirect URIs. Upon successful authentication, users will be redirected back to this address, which will be handled by the edge gateway.

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 retrive 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

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. 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 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.