TEG offers seamless single sign-on (SSO) integration through OIDC. With TEG, you can effortlessly link your application to any OIDC identity provider using the OIDCAuthenticationPolicy. This enables instant authentication for your application, all without the need to make any code modifications.

Integrate Your Existing OIDC Provider

Prerequisites

This guide assumes that the referenced Gateway and HTTPS listener have already been created. Furthermore, OIDC will not work in a plaintext HTTP listener environment for security reasons.

Create an OIDCAuthenticationPolicy

First, create an OIDCAuthenticationPolicy to connect to your OIDC identity provider. For information on how to configure the OIDCAuthenticationPolicy, see the API definition below.

policy.yaml

apiVersion:gateway.envoyproxy.io/v1alpha1
kind: OIDCAuthenticationPolicy
metadata:
  name: test-authn-policy
spec:
  targetRef: # The Gateway and Listener that this policy applies to
    name: GATEWAY_NAME # Gateway Name
    sectionName: LISTENER_NAME #Listener Name
  provider:
    issuer: ISSUER
    authorizationEndpoint: # optional
    tokenEndpoint: # optional
  clientID: CLIENT_ID
  clientSecret:
    name:  CLIENT_SECRET
  scopes: # optional

The following provides a detailed explanation of the most important fields:

• TargetRef: the Gateway and Listener to which this OIDAuthenticationPolicy applies.

  Note: The targeted Gateway should not have multiple listeners listening on the same ports. This is a known limitation of OIDCAuthenticationPolicy and will be resolved in future versions.

• Provider: the information of the OIDC identity provider

  • Issuer: The OIDC identity provider's issuer identifier. It’s also a URL which can be used by TEG to discover the provider’s AuthorizationEndpoint and TokenEndpoint.
  • AuthorizationEndpoint: The URL to which users are redirected in the authentication flow. If not provided, TEG will obtain it from the provider's Well-Known Configuration Endpoint through the OIDC discovery mechanism.
  • TokenEndpoint: The URL where your application exchanges the authorization code for an access token. It’s an optional field. If not provided,TEG will obtain it from the provider's Well-Known Configuration Endpoint through the OIDC discovery mechanism.

• ClientID: This is a unique identifier assigned to your application by the OIDC identity provider. You should be able to get it from your OIDC identity provider.

• ClientSecret: The Kubernetes secret which contains the OIDC client secret, which is a confidential token shared between your application and the OIDC identity provider to authenticate your application. You should be able to get it from your OIDC identity provider.

• Scopes: Scopes are used by an application during authentication to authorize access to a user's details, like name and email. Common scopes include openid for authentication, profile for user profile information, and email for user’s email address. This is an optional field. If not specified, the default "openid" is used.

The following snippet is an example of OIDCAuthenticationPolicy integrating TEG with the Google OIDC identity provider to enable SSO for applications behind the Listener listener-bar of the Gateway gateway-foo.

policy.yaml

apiVersion:gateway.envoyproxy.io/v1alpha1
kind: OIDCAuthenticationPolicy
metadata:
  name: test-authn-policy
spec:
  targetRef:
    name: gateway-foo
    sectionName: listener-bar
  provider:
    issuer: https://accounts.google.com
  clientID: xxx.apps.googleusercontent.com
  clientSecret:
    name:  oidc-client-secret

Create the Kubernetes secret containing the OIDC client secret

You also need to create a Kubernetes secret to contain the OIDC client secret referenced by the above OIDCAuthenticationPolicy.

kubectl create secret generic oidc-client-secret \
  --from-literal=client_secret=YOUR-OIDC-CLIENT-SECRET

The configuration is as straightforward as that. When you access a URL protected by an OIDCAuthenticationPolicy, you’ll be redirected to the OIDC identity provider’s login page for authentication. Following a successful login, you’ll gain access to the protected resources.

Following the steps in this doc, You can also connect TEG to other OIDC identity providers, such as Auth0, Azure AD, Keycloak, Okta, etc.