feat: add built-in OIDC authentication support

Add native OIDC support for self-hosted instances, enabling direct
integration with providers like Keycloak, PocketID, and any
OpenID Connect compliant identity provider.

Changes:
- Add OIDC OAuth2 start and callback handlers
- Add OIDC config struct with env var bindings (SERVER_AUTH_OIDC_*)
- Use OIDC discovery to resolve auth/token endpoints at startup
- Cache oidc.Provider for ID token verification (no per-request discovery)
- Add OIDC routes to OpenAPI spec and regenerate server code
- Expose 'oidc' scheme via /api/v1/meta endpoint
- Add SSO button to frontend auth page
- Support domain restrictions for OIDC users
- Default scopes: openid, profile, email

Closes #3052

Author: yaswanthkumar1995

api-contracts/openapi/openapi.yaml

@@ -101,6 +101,10 @@ paths:
     $ref: "./paths/user/user.yaml#/oauth-start-github"
   /api/v1/users/github/callback:
     $ref: "./paths/user/user.yaml#/oauth-callback-github"
+  /api/v1/users/oidc/start:
+    $ref: "./paths/user/user.yaml#/oauth-start-oidc"
+  /api/v1/users/oidc/callback:
+    $ref: "./paths/user/user.yaml#/oauth-callback-oidc"
   /api/v1/tenants/{tenant}/slack/start:
     $ref: "./paths/user/user.yaml#/oauth-start-slack"
   /api/v1/users/slack/callback:

api-contracts/openapi/paths/user/user.yaml

@@ -228,6 +228,36 @@ oauth-callback-github:
     summary: Complete OAuth flow
     tags:
       - User
+oauth-start-oidc:
+  get:
+    description: Starts the OIDC OAuth flow
+    operationId: user:update:oidc-oauth-start
+    responses:
+      "302":
+        description: Successfully started the OAuth flow
+        headers:
+          location:
+            schema:
+              type: string
+    security: []
+    summary: Start OIDC OAuth flow
+    tags:
+      - User
+oauth-callback-oidc:
+  get:
+    description: Completes the OIDC OAuth flow
+    operationId: user:update:oidc-oauth-callback
+    responses:
+      "302":
+        description: Successfully completed the OAuth flow
+        headers:
+          location:
+            schema:
+              type: string
+    security: []
+    summary: Complete OIDC OAuth flow
+    tags:
+      - User
 oauth-start-slack:
   get:
     x-resources: ["tenant"]

api/v1/server/handlers/metadata/get.go

@@ -21,6 +21,10 @@ func (u *MetadataService) MetadataGet(ctx echo.Context, request gen.MetadataGetR
 		authTypes = append(authTypes, "github")
 	}
 
+	if u.config.Auth.ConfigFile.OIDC.Enabled {
+		authTypes = append(authTypes, "oidc")
+	}
+
 	pylonAppID := u.config.Pylon.AppID
 
 	var posthogConfig *gen.APIMetaPosthog

api/v1/server/handlers/users/oidc_oauth_callback.go

@@ -0,0 +1,174 @@
+package users
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	"github.com/coreos/go-oidc/v3/oidc"
+	"github.com/jackc/pgx/v5"
+	"github.com/labstack/echo/v4"
+	"golang.org/x/oauth2"
+
+	"github.com/hatchet-dev/hatchet/api/v1/server/authn"
+	"github.com/hatchet-dev/hatchet/api/v1/server/middleware/redirect"
+	"github.com/hatchet-dev/hatchet/api/v1/server/oas/gen"
+	"github.com/hatchet-dev/hatchet/pkg/analytics"
+	"github.com/hatchet-dev/hatchet/pkg/config/server"
+	v1 "github.com/hatchet-dev/hatchet/pkg/repository"
+	"github.com/hatchet-dev/hatchet/pkg/repository/sqlcv1"
+)
+
+// Note: we want all errors to redirect, otherwise the user will be greeted with raw JSON in the middle of the login flow.
+func (u *UserService) UserUpdateOidcOauthCallback(ctx echo.Context, _ gen.UserUpdateOidcOauthCallbackRequestObject) (gen.UserUpdateOidcOauthCallbackResponseObject, error) {
+	isValid, _, err := authn.NewSessionHelpers(u.config.SessionStore).ValidateOAuthState(ctx, "oidc")
+
+	if err != nil || !isValid {
+		return nil, redirect.GetRedirectWithError(ctx, u.config.Logger, err, "Could not log in. Please try again and make sure cookies are enabled.")
+	}
+
+	token, err := u.config.Auth.OIDCOAuthConfig.Exchange(ctx.Request().Context(), ctx.Request().URL.Query().Get("code"))
+
+	if err != nil {
+		return nil, redirect.GetRedirectWithError(ctx, u.config.Logger, err, "Forbidden")
+	}
+
+	if !token.Valid() {
+		return nil, redirect.GetRedirectWithError(ctx, u.config.Logger, fmt.Errorf("invalid token"), "Forbidden")
+	}
+
+	user, err := u.upsertOIDCUserFromToken(ctx.Request().Context(), u.config, token)
+
+	if err != nil {
+		if errors.Is(err, ErrNotInRestrictedDomain) {
+			return nil, redirect.GetRedirectWithError(ctx, u.config.Logger, err, "Email is not in the restricted domain group.")
+		}
+
+		return nil, redirect.GetRedirectWithError(ctx, u.config.Logger, err, "Internal error.")
+	}
+
+	err = authn.NewSessionHelpers(u.config.SessionStore).SaveAuthenticated(ctx, user)
+
+	if err != nil {
+		return nil, redirect.GetRedirectWithError(ctx, u.config.Logger, err, "Internal error.")
+	}
+
+	analyticsCtx := context.WithValue(ctx.Request().Context(), analytics.UserIDKey, user.ID)
+	analyticsCtx = context.WithValue(analyticsCtx, analytics.SourceKey, analytics.SourceUI)
+	u.config.Analytics.Enqueue(
+		analyticsCtx,
+		analytics.User, analytics.Login,
+		user.ID.String(),
+		map[string]interface{}{"provider": "oidc"},
+	)
+
+	return gen.UserUpdateOidcOauthCallback302Response{
+		Headers: gen.UserUpdateOidcOauthCallback302ResponseHeaders{
+			Location: u.config.Runtime.ServerURL,
+		},
+	}, nil
+}
+
+func (u *UserService) upsertOIDCUserFromToken(ctx context.Context, config *server.ServerConfig, tok *oauth2.Token) (*sqlcv1.User, error) {
+	claims, err := getOIDCClaimsFromToken(ctx, config, tok)
+	if err != nil {
+		return nil, err
+	}
+
+	if err := u.checkUserRestrictionsForEmail(config, claims.Email); err != nil {
+		return nil, err
+	}
+
+	expiresAt := tok.Expiry
+
+	accessTokenEncrypted, err := config.Encryption.Encrypt([]byte(tok.AccessToken), "oidc_access_token")
+	if err != nil {
+		return nil, fmt.Errorf("failed to encrypt access token: %s", err.Error())
+	}
+
+	refreshToken := tok.RefreshToken
+	if refreshToken == "" {
+		refreshToken = "none"
+	}
+
+	refreshTokenEncrypted, err := config.Encryption.Encrypt([]byte(refreshToken), "oidc_refresh_token")
+	if err != nil {
+		return nil, fmt.Errorf("failed to encrypt refresh token: %s", err.Error())
+	}
+
+	oauthOpts := &v1.OAuthOpts{
+		Provider:       "oidc",
+		ProviderUserId: claims.Sub,
+		AccessToken:    accessTokenEncrypted,
+		RefreshToken:   refreshTokenEncrypted,
+		ExpiresAt:      &expiresAt,
+	}
+
+	user, err := u.config.V1.User().GetUserByEmail(ctx, claims.Email)
+
+	switch err {
+	case nil:
+		user, err = u.config.V1.User().UpdateUser(ctx, user.ID, &v1.UpdateUserOpts{
+			EmailVerified: v1.BoolPtr(claims.EmailVerified),
+			Name:          v1.StringPtr(claims.Name),
+			OAuth:         oauthOpts,
+		})
+
+		if err != nil {
+			return nil, fmt.Errorf("failed to update user: %s", err.Error())
+		}
+	case pgx.ErrNoRows:
+		user, err = u.config.V1.User().CreateUser(ctx, &v1.CreateUserOpts{
+			Email:         claims.Email,
+			EmailVerified: v1.BoolPtr(claims.EmailVerified),
+			Name:          v1.StringPtr(claims.Name),
+			OAuth:         oauthOpts,
+		})
+
+		if err != nil {
+			return nil, fmt.Errorf("failed to create user: %s", err.Error())
+		}
+	default:
+		return nil, fmt.Errorf("failed to get user: %s", err.Error())
+	}
+
+	return user, nil
+}
+
+type oidcClaims struct {
+	Email         string `json:"email"`
+	EmailVerified bool   `json:"email_verified"`
+	Name          string `json:"name"`
+	Sub           string `json:"sub"`
+}
+
+func getOIDCClaimsFromToken(ctx context.Context, config *server.ServerConfig, tok *oauth2.Token) (*oidcClaims, error) {
+	verifier := config.Auth.OIDCProvider.Verifier(&oidc.Config{
+		ClientID: config.Auth.OIDCOAuthConfig.ClientID,
+	})
+
+	rawIDToken, ok := tok.Extra("id_token").(string)
+	if !ok {
+		return nil, fmt.Errorf("no id_token in token response")
+	}
+
+	idToken, err := verifier.Verify(ctx, rawIDToken)
+	if err != nil {
+		return nil, fmt.Errorf("failed to verify ID token: %s", err.Error())
+	}
+
+	claims := &oidcClaims{}
+	if err := idToken.Claims(claims); err != nil {
+		return nil, fmt.Errorf("failed to parse ID token claims: %s", err.Error())
+	}
+
+	if claims.Email == "" {
+		return nil, fmt.Errorf("OIDC provider did not return an email claim")
+	}
+
+	if claims.Sub == "" {
+		return nil, fmt.Errorf("OIDC provider did not return a sub claim")
+	}
+
+	return claims, nil
+}

api/v1/server/handlers/users/oidc_oauth_start.go

@@ -0,0 +1,30 @@
+package users
+
+import (
+	"github.com/labstack/echo/v4"
+
+	"github.com/hatchet-dev/hatchet/api/v1/server/authn"
+	"github.com/hatchet-dev/hatchet/api/v1/server/middleware/redirect"
+	"github.com/hatchet-dev/hatchet/api/v1/server/oas/gen"
+)
+
+// Note: we want all errors to redirect, otherwise the user will be greeted with raw JSON in the middle of the login flow.
+func (u *UserService) UserUpdateOidcOauthStart(ctx echo.Context, _ gen.UserUpdateOidcOauthStartRequestObject) (gen.UserUpdateOidcOauthStartResponseObject, error) {
+	if !u.config.Runtime.AllowSignup {
+		return nil, redirect.GetRedirectWithError(ctx, u.config.Logger, nil, "User signup is disabled.")
+	}
+
+	state, err := authn.NewSessionHelpers(u.config.SessionStore).SaveOAuthState(ctx, "oidc")
+
+	if err != nil {
+		return nil, redirect.GetRedirectWithError(ctx, u.config.Logger, err, "Could not get cookie. Please make sure cookies are enabled.")
+	}
+
+	url := u.config.Auth.OIDCOAuthConfig.AuthCodeURL(state)
+
+	return gen.UserUpdateOidcOauthStart302Response{
+		Headers: gen.UserUpdateOidcOauthStart302ResponseHeaders{
+			Location: url,
+		},
+	}, nil
+}