OAuth

This feature is available with a Gloo Mesh Gateway license only.

Gloo Mesh supports authentication via OpenID Connect (OIDC). OIDC is an identity layer on top of the OAuth 2.0 protocol. In OAuth 2.0 flows, authentication is performed by an external Identity Provider (IdP) which, in case of success, returns an Access Token representing the user identity. The protocol does not define the contents and structure of the Access Token, which greatly reduces the portability of OAuth 2.0 implementations.

The goal of OIDC is to address this ambiguity by additionally requiring Identity Providers to return a well-defined ID Token. OIDC ID tokens follow the JSON Web Token standard and contain specific fields that your applications can expect and handle. This standardization allows you to switch between Identity Providers - or support multiple ones at the same time - with minimal, if any, changes to your downstream services; it also allows you to consistently apply additional security measures like Role-based Access Control (RBAC) based on the identity of your users, i.e. the contents of their ID token (check out this guide for an example of how to use Gloo Mesh to apply RBAC policies to JWTs).

In this guide, we will focus on the format of the Gloo Mesh API for OIDC authentication.

Configuration format

Following is an example of an AuthConfig with an OIDC configuration (for more information on AuthConfig CRDs, see the main page of the authentication docs):

apiVersion: enterprise.gloo.solo.io/v1
kind: AuthConfig
metadata:
  name: oidc
  namespace: gloo-system
spec:
  configs:
  - oauth2:
      oidcAuthorizationCode:
        issuerUrl: theissuer.com
        appUrl: https://myapp.com
        authEndpointQueryParams:
          paramKey: paramValue
        callbackPath: /my/callback/path/
        clientId: myclientid
        clientSecretRef:
          name: my-oauth-secret
          namespace: gloo-system
        scopes:
        - email

The AuthConfig consists of a single config of type oauth2.oidcAuthorizationCode. Let's go through each of its attributes:

The callback path must have a matching route in the VirtualGateway associated with the OIDC settings. For example, you could simply have a / path-prefix route which would match any callback path. The important part of this callback “catch all” route is that it goes through the routing filters including external auth. Please see the examples for Google, Dex, and Okta.

Use the cookieOptions field to customize cookie behavior:

Example configuration:

apiVersion: enterprise.gloo.solo.io/v1
kind: AuthConfig
metadata:
  name: oidc-dex
  namespace: gloo-system
spec:
  configs:
  - oauth2:
      oidcAuthorizationCode:
        appUrl: http://localhost:8080/
        callbackPath: /callback
        clientId: gloo
        clientSecretRef:
          name: oauth
          namespace: gloo-system
        issuerUrl: http://dex.gloo-system.svc.cluster.local:32000/
        scopes:
        - email
        session:
          cookieOptions:
            notSecure: true
            maxAge: 3600

Logout URL

Gloo Mesh also supports specifying a logout url. When specified, accessing this url will trigger a deletion of the user session, with an empty 200 OK response returned.

Example configuration:

apiVersion: enterprise.gloo.solo.io/v1
kind: AuthConfig
metadata:
  name: oidc-dex
  namespace: gloo-system
spec:
  configs:
  - oauth2:
      oidcAuthorizationCode:
        appUrl: http://localhost:8080/
        callbackPath: /callback
        clientId: gloo
        clientSecretRef:
          name: oauth
          namespace: gloo-system
        issuerUrl: http://dex.gloo-system.svc.cluster.local:32000/
        scopes:
        - email
        logoutPath: /logout

When this url is accessed, the user session and cookie will be deleted.

Sessions in Redis

By default, the tokens will be saved in a secure client side cookie. Gloo Mesh can instead use Redis to save the OIDC tokens, and set a randomly generated session id in the user's cookie.

Example configuration:

apiVersion: enterprise.gloo.solo.io/v1
kind: AuthConfig
metadata:
  name: oidc-dex
  namespace: gloo-system
spec:
  configs:
  - oauth2:
      oidcAuthorizationCode:
        appUrl: http://localhost:8080/
        callbackPath: /callback
        clientId: gloo
        clientSecretRef:
          name: oauth
          namespace: gloo-system
        issuerUrl: http://dex.gloo-system.svc.cluster.local:32000/
        scopes:
        - email
        session:
          failOnFetchFailure: true
          redis:
            cookieName: session
            options:
              host: redis.gloo-system.svc.cluster.local:6379

Forwarding the ID token upstream

You can configure Gloo Mesh to forward the id token to the destination on successful authentication. To do that, set the headers section in the configuration.

Example configuration:

apiVersion: enterprise.gloo.solo.io/v1
kind: AuthConfig
metadata:
  name: oidc-dex
  namespace: gloo-system
spec:
  configs:
  - oauth2:
      oidcAuthorizationCode:
        appUrl: http://localhost:8080/
        callbackPath: /callback
        clientId: gloo
        clientSecretRef:
          name: oauth
          namespace: gloo-system
        issuerUrl: http://dex.gloo-system.svc.cluster.local:32000/
        scopes:
        - email
        headers:
          idTokenHeader: "x-token"

Examples

We have seen how a sample OIDC AuthConfig is structured. For complete examples of how to set up an OIDC flow with Gloo Mesh, check out the following guides: