OAuth

Gloo Edge 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 Edge to apply RBAC policies to JWTs).

In this guide, we will focus on the format of the Gloo Edge 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:
        issuer_url: theissuer.com
        app_url: https://myapp.com
        auth_endpoint_query_params:
          paramKey: paramValue
        callback_path: /my/callback/path/
        client_id: myclientid
        client_secret_ref:
          name: my-oauth-secret
          namespace: gloo-system
        scopes:
        - email

The AuthConfig consists of a single config of type oauth. Let’s go through each of its attributes:

• issuer_url: The url of the OpenID Connect identity provider. Gloo Edge will automatically discover OpenID Connect configuration by querying the .well-known/openid-configuration endpoint on the issuer_url. For example, if you are using Google as an identity provider, Gloo Edge will expect to find OIDC discovery information at https://accounts.google.com/.well-known/openid-configuration.
• auth_endpoint_query_params: A map of query parameters appended to the issuer url in the form issuer_url?paramKey:paramValue. These query parameters are sent to the authorization endpoint when Gloo Edge initiates the OIDC flow. This can be useful when integrating Gloo Edge with some identity providers that require custom parameters to be sent to the authorization endpoint.
• app_url: This is the public URL of your application. It is used in combination with the callback_path attribute.
• callback_path: The callback path relative to the app_url. Once a user has been authenticated, the identity provider will redirect them to this URL. Gloo Edge will intercept requests with this path, exchange the authorization code received from the Identity Provider for an ID token, place the ID token in a cookie on the request, and forward the request to its original destination.

• client_id: This is the client id that you obtained when you registered your application with the identity provider.
• client_secret_ref: This is a reference to a Kubernetes secret containing the client secret that you obtained when you registered your application with the identity provider. The easiest way to create the Kubernetes secret in the expected format is to use glooctl, but you can also provide it by kubectl applying YAML to your cluster:
  • glooctl
  • kubectl

  
  glooctl create secret oauth --namespace gloo-system --name oidc --client-secret secretvalue
  

  
  apiVersion: v1
  kind: Secret
  type: Opaque
  metadata:
    annotations:
      resource_kind: '*v1.Secret'
    name: oidc
    namespace: gloo-system
  data:
    # The value is a base64 encoding of the following YAML:
    # client_secret: secretvalue
    # Gloo Edge expects OAuth client secrets in this format.
    oauth: Y2xpZW50U2VjcmV0OiBzZWNyZXR2YWx1ZQo=
  

• scopes: scopes to request in addition to the openid scope.

Cookie options

Use the cookieOptions field to customize cookie behavior:

• notSecure - Set the cookie to not secure. This is not recommended, but might be useful for demo/testing purposes.
• maxAge - The max age of the cookie in seconds.
• path - The path of the cookie.
• domain - The domain of the 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:
          cookieOptions:
            notSecure: true
            maxAge: 3600

Logout url

Gloo 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 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 to forward the id token to the upstream 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:
          id_token_header: "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 Edge, check out the following guides:

• Authenticate with Google: Setup OpenID Connect (OIDC) authentication with the Google identity provider.

• Authenticate with Okta: Integrating Gloo Edge and Okta Identity Cloud

• Authenticate with Dex: Integrating Gloo Edge and Dex Identity Provider

• Authenticate with an Access Token: Integrating Gloo Edge and Access Tokens