Skip to main content
logoTetrate Enterprise Gateway for Envoy (TEG)Version: v0.1.0

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 straightforward OIDCAuthenticationPolicy. This enables instant authentication for your application, all without the need to make any code modifications.

Integrate Your Existing OIDC Provider

Create an OIDCAuthenticationPolicy​

First, create an OIDCAuthenticationPolicy to connect to your OIDC identity provider. For information on how to configure the OIDCAuthenticationPolicy Policy, 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
  redirectURI: REDIRECT_URI # this field will be removed in v0.1 rc.3

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 an 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 an 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
  redirectURI: https://www.example.com/oauth2/callback # this field will be removed in v0.1 rc.3 and don't need anymore

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.