Light Dark Auto

Enable OIDC Guarded Edge for Tenant

Using the OIDC Pipeline Filter to authenticate users with Keycloak

GSL exposes OpenID Connect (OIDC) authentication functionality through the #OIDCPipelineFilter filter definition. The filter redirects unauthenticated users to an OIDC provider’s login page and handles token exchange and refresh afterwards.

Although this guide specifically references enabling OIDC on an application edge node, the process and configuration for any service proxy remains the same.

Prerequisites

  • A deployed tenant edge
  • A deployed Keycloak instance

You need a few data points from Keycloak:

  • A realm
  • A client ID for the edge
  • The client secret for the client ID

Finally, you need to add a URL pointing to your edge into the ‘Valid Redirect URIs’ list for the client. It must conform to this format: https://{EXTERNAL_IP_OR_DNS_HOSTNAME}:{PORT}/oauth.

If you have access to the Keycloak instance, please refer to the mesh admin version of this guide to set and collect the appropriate values. Otherwise, contact your Keycloak administrator.

Add the OIDC Pipeline Filter to the Edge

Enable the OIDC Pipeline Filter

Open the GSL configuration file for your project’s edge. Select the listener that should execute the OIDC flow. Inside the listener’s filter array (add one if its not already present), insert the gsl.#OIDCPipelineFilter definition like this:

"myListener": {
    ...
    filters: [
        gsl.#OIDCPipelineFilter
    ]
}

Configure the OIDC Pipeline Filter

The OIDC pipeline filter requires a few configuration values to function. Since it is a filter, GSL expects configuration to get passed into the #options property. Use the & operator like this:

...
gsl.#OIDCPipelineFilter & {
    #options: {
     // Values go inside this block
    }
}
...

The basic set of values the filter needs to work are:

  • provider_host - the URL of the OIDC provider (includes the protocol, domain, and port components)
  • clientId - the id of the client registered by the OIDC provider (this is not the user’s id)
  • clientSecret - the corresponding secret for the client name inputted above (this is not the user’s password)
  • serviceURL - the URL that the user gets redirected to after successfully authenticating (matches the Valid Redirect URI in Keycloak and should )
  • realm - name of the OIDC realm

Additionally you have the choice to perform remote or local verification on the returned JSON Web Tokens (JWT) using JSON Web Key Sets (JWKS). That process is covered in the next sections.

Set the basic required values like this:

...
gsl.#OIDCPipelineFilter & {
    #options: {
        provider_host: "https://your.keycloak.provider.com"
        clientId:      "Your client id"
        clientSecret:  "Secret for the client specified by the above id"
        serviceUrl:    "https://url.for.redirect"
        realm:         "Your Realm"
    }
}
...

Remote verification offloads the JWT verification keys to an separate service instead of storing those keys locally. Keycloak comes with this functionality so we will leverage it for this guide.

Step outside the listener scope into the #Edge (or #Service) scope. Add an upstream to raw_upstreams:

gsl.#Edge & {
    ...

    raw_upstreams: {
        "remote_jwks": {
            gsl.#Upstream
            gsl.#TLSUpstream // or use another TLS scheme
            instances: [
                {
                    host: "your.keycloak.provider.com"
                    port: 80
                }
            ]
        }
    }

    "myListener": {
        ...
    }

    ...
}

Finally, add the provider_cluster field to the OIDC pipeline filter options’ definition and set it to the name of the raw upstream. In this case, it is “remote_jwks”:

gsl.#OIDCPipelineFilter & {
    #options: {
        ...
        provider_cluster: "remote_jwks"
    }
}

Local JWKS

Local verification with JWKS is the opposite of remote verification. The filter stores verification keys locally. Local verification eliminates a network hop, but means that the keys could expire, potentially disrupting network accessibility.

In Keycloak, you can manually fetch the keys using this URL:

https://KEYCLOAK_HOST:KEYCLOAK_PORT/realms/YOUR_REALM/protocol/openid-connect/certs

Copy and paste those values inside the OIDC Pipeline filter options’ definition:

    #options: {
        ...
        jwt: {
            local_jwks: {
                inline_string: "## PASTE CONTENTS HERE ##"
            }
        }
    }
}

Apply the Configuration Changes

Run greymatter sync --dry-run to ensure your updated configuration is valid.

If that succeeds, commit and push your changes to the remote GitOps repository. Now, attempt to load a URL behind the newly guarded edge proxy. It should redirect you to Keycloak’s login page. After a successful log in, Keycloak will redirect you to your original request’s location.

OIDC is now successfully configured!

To learn about additional OIDC options, please refer to the filter reference page.