About OIDC

Gloo Gateway 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). For successful authentications, the IdP returns an access token that represents the user identity. However, the protocol does not define the contents and structure of the access token. This ambiguity greatly reduces the portability of OAuth 2.0 implementations.

The goal of OIDC is to address OAuth 2.0’s ambiguity by requiring IdPs to return a well-defined ID token. OIDC ID tokens follow the JSON Web Token (JWT) standard and contain specific fields. You can write your apps to expect and handle these fields. This standardization allows you to switch between IdPs or support multiple IdPs at the same time. You need minimal, if any, changes to your downstream services. OIDC also allows you to consistently apply security measures such as Kubernetes role-based access control (RBAC) based on the content of the ID tokens. This way, you can use the same user identity information for authentication to apps in your cluster.

Supported types of OAuth2

The Gloo Gateway external auth server supports two types of OAuth 2.0: authorization code and access token validation. The way that you set these up vary by the OIDC provider.

Authorization codes

Authorization codes are commonly used in scenarios where end users access a web application. For example, you might want to control access to your API products in a developer portal that users interact with through a frontend web app.

Before a request is forwarded to a protected API product, the Gloo external auth server intercepts and redirects the request to the OIDC provider that you configured for client authentication. The client then authenticates through the OIDC provider. If the client is successfully authenticated, the OIDC provider issues an authorization code and stores it as a query parameter in the response. The client is then redirected back to the Gloo external auth server. The external auth server then exchanges the authorization code for an identity (ID) and access token. Finally, Gloo stores and uses the access token to authenticate the client’s requests. This way, the access token is not exposed to the user’s browser and is more secure.

For programmatic access, the user can instead provide the access token from the OIDC as a header in the initial request.

For more information, refer to the following resources:

Front channel logout

Front channel logout is a security mechanism that is used in the context of Single Sign-On (SSO) and Identity and Access Management (IAM) systems to ensure that when a user logs out of one app or service, they are also automatically logged out of the Identity Provider (IdP) and therefore all related apps and services in a secure and synchronized manner. Without front channel logout, the user is logged out of the requested app only.

You can add a front channel logout path in the AuthConfig that configures OIDC authorization code for your app as shown in the following example AuthConfig. Note that the frontChannelLogout path must be set in your IdP for your app. It must also be different from the logoutPath that you set to log out of your app.

  apiVersion: enterprise.gloo.solo.io/v1
kind: AuthConfig
metadata:
  name: oauth-keycloak
  namespace: gloo-system
spec:
  configs:
    - oauth2:
        oidcAuthorizationCode:
          appUrl: "http://portal.example.com"
          callbackPath: /v1/login
          logoutPath: /v1/logout
          frontChannelLogout:
            path: /front_channel_logout
          clientId: $KEYCLOAK_CLIENT
          clientSecretRef:
            name: oauth-keycloak
            namespace: gloo-system
          issuerUrl: "$KEYCLOAK_URL/realms/$REALM"
          session:
            failOnFetchFailure: true
            cookie:
              allowRefreshing: true
          scopes:
          - openid
          headers:
            idTokenHeader: id_token

When the user goes to the configured logoutPath, a request is sent to the IdP to log the user out of the app. Because you also set a frontChannelLogout path that matches the setting in the IdP, the IdP initiates the logout from every app that the user is currently logged in to.

Access token validation

For programmatic access, you can set up external auth to use access token validation. In such case, the user gets the access token from the OIDC provider first. Then, the user provides the access token in requests to your API products. Gloo stores and uses the access token to authenticate the user’s requests.

For more information, refer to the following resources: