vikunja/pkg/modules/auth/openid/openid.go

// Vikunja is a to-do list application to facilitate your life.
// Copyright 2018-present Vikunja and contributors. All rights reserved.
//
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU Affero General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU Affero General Public License for more details.
//
// You should have received a copy of the GNU Affero General Public License
// along with this program.  If not, see <https://www.gnu.org/licenses/>.

package openid

import (
	"bytes"
	"context"
	"encoding/json"
	"errors"
	"fmt"
	"net/http"
	"strconv"
	"strings"

	"code.vikunja.io/api/pkg/db"
	"code.vikunja.io/api/pkg/events"
	"code.vikunja.io/api/pkg/log"
	"code.vikunja.io/api/pkg/models"
	"code.vikunja.io/api/pkg/modules/auth"
	"code.vikunja.io/api/pkg/modules/avatar"
	"code.vikunja.io/api/pkg/modules/avatar/upload"
	"code.vikunja.io/api/pkg/modules/keyvalue"
	"code.vikunja.io/api/pkg/user"
	"code.vikunja.io/api/pkg/utils"

	"github.com/coreos/go-oidc/v3/oidc"
	petname "github.com/dustinkirkland/golang-petname"
	"github.com/labstack/echo/v5"
	"golang.org/x/oauth2"
	"xorm.io/xorm"
)

// Callback contains the callback after an auth request was made and redirected
type Callback struct {
	Code        string `query:"code" json:"code"`
	Scope       string `query:"scope" json:"scope"`
	RedirectURL string `json:"redirect_url"`
	// TOTPPasscode is required when the resolved user has TOTP enabled.
	// Clients must restart the OIDC flow and populate this field after
	// receiving a 412 with error code 1017. See GHSA-8jvc-mcx6-r4cg.
	TOTPPasscode string `json:"totp_passcode"`
}

// Provider is the structure of an OpenID Connect provider
type Provider struct {
	Name                string `json:"name"`
	Key                 string `json:"key"`
	OriginalAuthURL     string `json:"-"`
	AuthURL             string `json:"auth_url"`
	LogoutURL           string `json:"logout_url"`
	ClientID            string `json:"client_id"`
	Scope               string `json:"scope"`
	EmailFallback       bool   `json:"email_fallback"`
	UsernameFallback    bool   `json:"username_fallback"`
	ForceUserInfo       bool   `json:"force_user_info"`
	RequireAvailability bool   `json:"-"`
	ClientSecret        string `json:"-"`
	// RP-Initiated Logout endpoint, cached at init so logout never fetches.
	// Exported so it survives the gob keyvalue round-trip (gob skips unexported
	// fields like openIDProvider); json:"-" keeps it out of /info.
	EndSessionURL  string `json:"-"`
	openIDProvider *oidc.Provider
	Oauth2Config   *oauth2.Config `json:"-"`
}

type claims struct {
	Email              string                   `json:"email"`
	Name               string                   `json:"name"`
	PreferredUsername  string                   `json:"preferred_username"`
	Nickname           string                   `json:"nickname"`
	VikunjaGroups      []map[string]interface{} `json:"vikunja_groups"`
	Picture            string                   `json:"picture"`
	ExtraSettingsLinks map[string]any           `json:"extra_settings_links"`
}

func init() {
	petname.NonDeterministicMode()
}

func (p *Provider) setOicdProvider() (err error) {
	err = utils.RetryWithBackoff(fmt.Sprintf("OpenID Connect provider '%s'", p.Name), func() error {
		var providerErr error
		p.openIDProvider, providerErr = oidc.NewProvider(context.Background(), p.OriginalAuthURL)
		return providerErr
	})

	if err != nil && p.RequireAvailability {
		log.Fatalf("OpenID Connect provider '%s' is not available and require_availability is enabled: %s", p.Name, err)
	}

	return err
}

func (p *Provider) Issuer() (issuerURL string, err error) {
	type Issuer struct {
		Issuer string `json:"issuer"`
	}

	if p.openIDProvider == nil {
		err = p.setOicdProvider()
		if err != nil {
			return "", err
		}
	}

	iss := &Issuer{}
	err = p.openIDProvider.Claims(iss)
	if err != nil {
		return "", err
	}
	return iss.Issuer, nil
}

// enforceTOTPIfRequired mirrors the TOTP gate from pkg/routes/api/v1/login.go
// for the OIDC flow. Returns nil when the user does not have TOTP enabled.
// See GHSA-8jvc-mcx6-r4cg.
func enforceTOTPIfRequired(s *xorm.Session, u *user.User, totpPasscode string) error {
	totpEnabled, err := user.TOTPEnabledForUser(s, u)
	if err != nil {
		return err
	}
	if !totpEnabled {
		return nil
	}

	if totpPasscode == "" {
		return user.ErrInvalidTOTPPasscode{}
	}

	_, err = user.ValidateTOTPPasscode(s, &user.TOTPPasscode{
		User:     u,
		Passcode: totpPasscode,
	})
	if err != nil {
		return err
	}

	// Reset the counter so old failed attempts don't trip a later lockout.
	if err := keyvalue.Del(u.GetFailedTOTPAttemptsKey()); err != nil {
		return err
	}

	return nil
}

// HandleCallback handles the auth request callback after redirecting from the provider with an auth code
// @Summary Authenticate a user with OpenID Connect
// @Description After a redirect from the OpenID Connect provider to the frontend has been made with the authentication `code`, this endpoint can be used to obtain a jwt token for that user and thus log them in.
// @ID get-token-openid
// @tags auth
// @Accept json
// @Produce json
// @Security JWTKeyAuth
// @Param callback body openid.Callback true "The openid callback"
// @Param provider path int true "The OpenID Connect provider key as returned by the /info endpoint"
// @Success 200 {object} auth.Token
// @Failure 412 {object} models.Message "Invalid totp passcode."
// @Failure 500 {object} models.Message "Internal error"
// @Router /auth/openid/{provider}/callback [post]
func HandleCallback(c *echo.Context) error {
	cb := &Callback{}
	if err := c.Bind(cb); err != nil {
		return &models.ErrOpenIDBadRequest{Message: "Bad data"}
	}

	u, oidcData, err := AuthenticateCallback(c.Request().Context(), cb, c.Param("provider"))
	if err != nil {
		var detailedErr *models.ErrOpenIDBadRequestWithDetails
		if errors.As(err, &detailedErr) {
			return c.JSON(http.StatusBadRequest, map[string]interface{}{
				"message": detailedErr.Message,
				"details": detailedErr.Details,
			})
		}
		return err
	}

	// Create token
	return auth.NewUserAuthTokenResponse(u, c, false, oidcData)
}

// AuthenticateCallback resolves an OpenID Connect callback to an authenticated
// user: it exchanges the auth code, verifies the ID token, creates or updates the
// matching local user, enforces the account-status and TOTP gates, and syncs the
// user's external teams. It is the transport-agnostic core shared by the v1 echo
// handler and the v2 Huma handler; the caller issues the auth token. The
// ErrOpenIDBadRequestWithDetails error keeps its provider detail so v1 can render
// its bespoke body and v2 can map it to RFC 9457.
func AuthenticateCallback(ctx context.Context, cb *Callback, providerKey string) (*user.User, *models.SessionOIDCData, error) {
	// ctx is threaded through only to dispatch the login event; the OIDC token
	// exchange, claim verification and user/avatar sync run on their own
	// background contexts, exactly as the v1 callback always did.
	provider, oauthToken, idToken, rawIDToken, err := exchangeOidcTokens(cb, providerKey) //nolint:contextcheck
	if err != nil {
		return nil, nil, err
	}

	// Stored so logout can replay it as id_token_hint in an RP-Initiated Logout.
	oidcData := &models.SessionOIDCData{
		IDToken:     rawIDToken,
		ProviderKey: providerKey,
	}

	cl, err := getClaims(provider, oauthToken, idToken) //nolint:contextcheck
	if err != nil {
		return nil, nil, err
	}

	s := db.NewSession()
	defer s.Close()
	// Discards events queued during a rolled-back transaction (e.g. user
	// creation); a no-op once DispatchPending has run.
	defer events.CleanupPending(s)

	// Check if we have seen this user before
	u, err := getOrCreateUser(s, cl, provider, idToken) //nolint:contextcheck
	if err != nil {
		_ = s.Rollback()
		log.Errorf("Error creating new user for provider %s: %v", provider.Name, err)
		return nil, nil, err
	}

	if u.Status == user.StatusDisabled {
		_ = s.Rollback()
		return nil, nil, &user.ErrAccountDisabled{UserID: u.ID}
	}
	if u.Status == user.StatusAccountLocked {
		_ = s.Rollback()
		return nil, nil, &user.ErrAccountLocked{UserID: u.ID}
	}

	// Must run before team sync so a failed 2FA attempt cannot mutate team
	// membership. Commit before HandleFailedTOTPAuth so the getOrCreateUser
	// writes persist and the SQLite write lock is released — its dedicated
	// session needs to acquire its own. See GHSA-fgfv-pv97-6cmj.
	if err := enforceTOTPIfRequired(s, u, cb.TOTPPasscode); err != nil {
		if commitErr := s.Commit(); commitErr != nil {
			log.Errorf("Error committing session after failed OIDC TOTP attempt for user %d: %v", u.ID, commitErr)
		} else {
			// The user creation above was committed, so its events are real.
			events.DispatchPending(ctx, s)
		}
		if user.IsErrInvalidTOTPPasscode(err) {
			user.HandleFailedTOTPAuth(u)
		}
		return nil, nil, err
	}

	teamData := getTeamDataFromToken(cl.VikunjaGroups, provider)

	err = models.SyncExternalTeamsForUser(s, u, teamData, idToken.Issuer, provider.Name)
	if err != nil {
		return nil, nil, err
	}

	err = s.Commit()
	if err != nil {
		_ = s.Rollback()
		log.Errorf("Error creating new team for provider %s: %v", provider.Name, err)
		return nil, nil, err
	}

	events.DispatchPending(ctx, s)

	return u, oidcData, nil
}

func getTeamDataFromToken(groups []map[string]interface{}, provider *Provider) (teamData []*models.Team) {
	teamData = []*models.Team{}
	for _, t := range groups {
		var name string
		var description string
		var oidcID string
		var isPublic bool

		// Read name
		_, exists := t["name"]
		if exists {
			name = t["name"].(string)
		}

		// Read description
		_, exists = t["description"]
		if exists {
			description = t["description"].(string)
		}

		// Read isPublic flag
		_, exists = t["isPublic"]
		if exists {
			isPublic = t["isPublic"].(bool)
		}

		// Read oidcID
		_, exists = t["oidcID"]
		if exists {
			switch id := t["oidcID"].(type) {
			case string:
				oidcID = id
			case int64:
				oidcID = strconv.FormatInt(id, 10)
			case float64:
				oidcID = strconv.FormatFloat(id, 'f', -1, 64)
			default:
				log.Errorf("No oidcID assigned for %v or type %v not supported", t, t)
			}
		}
		if name == "" || oidcID == "" {
			log.Errorf("Claim of your custom scope does not hold name or oidcID for automatic group assignment through oidc provider. Please check %s", provider.Name)
			continue
		}
		teamData = append(teamData, &models.Team{
			Name:        name,
			ExternalID:  oidcID,
			Description: description,
			IsPublic:    isPublic,
		})
	}

	return teamData
}

// Download and store a user's avatar from an OpenID provider
func syncUserAvatarFromOpenID(s *xorm.Session, u *user.User, pictureURL string) (err error) {
	// If no picture URL is provided, reset the avatar provider if it was set to openid
	if pictureURL == "" {
		if u.AvatarProvider == "openid" {
			u.AvatarProvider = "default"
			_, err = s.Where("id = ?", u.ID).Cols("avatar_provider").Update(&user.User{AvatarProvider: "default"})
			if err != nil {
				return fmt.Errorf("error resetting avatar provider: %w", err)
			}
			avatar.FlushAllCaches(u)
		}
		return nil
	}

	log.Debugf("Found avatar URL for user %s: %s", u.Username, pictureURL)

	// Download avatar
	avatarData, err := utils.DownloadImage(pictureURL)
	if err != nil {
		return fmt.Errorf("error downloading avatar: %w", err)
	}

	// Process avatar, ensure 1:1 ratio
	processedAvatar, err := utils.CropAvatarTo1x1(avatarData)
	if err != nil {
		return fmt.Errorf("error processing avatar: %w", err)
	}

	// Set avatar provider to openid
	u.AvatarProvider = "openid"

	// Store avatar and update user
	err = upload.StoreAvatarFile(s, u, bytes.NewReader(processedAvatar))
	if err != nil {
		return fmt.Errorf("error storing avatar: %w", err)
	}

	avatar.FlushAllCaches(u)

	return nil
}

// fallbackSearchUsers builds the ordered list of local-user lookups used to link an OIDC
// login to an existing account when the provider has email and/or username fallback enabled.
// GetUserWithEmail ANDs all non-zero fields, so the email (when set) is combined with each
// username candidate.
func fallbackSearchUsers(cl *claims, provider *Provider, idToken *oidc.IDToken) []*user.User {
	fallbackEmail := ""
	if provider.EmailFallback {
		// Used alone, allow for someone to connect from various provider to the same account.
		// Discouraged for untrusted providers where someone can set email without verification.
		// Note: mapping on email prevents auto-updating the user email.
		fallbackEmail = cl.Email
	}

	// Try the subject first (keeps working for IdPs where sub == username), then the
	// preferred_username. The latter lets providers with an opaque sub (e.g. a random
	// UUID, like PocketID) still link to an existing local account.
	var searches []*user.User
	if provider.UsernameFallback {
		// Skip empty username candidates: GetUserWithEmail ANDs only non-zero fields, so a
		// {Issuer, Username:"", Email:""} would degenerate to an issuer-only lookup and link
		// an arbitrary local user. idToken.Subject is non-empty per OIDC, but guard anyway.
		if idToken.Subject != "" {
			searches = append(searches, &user.User{Issuer: user.IssuerLocal, Username: idToken.Subject, Email: fallbackEmail})
		}
		preferred := strings.ReplaceAll(cl.PreferredUsername, " ", "-")
		if preferred != "" && preferred != idToken.Subject {
			searches = append(searches, &user.User{Issuer: user.IssuerLocal, Username: preferred, Email: fallbackEmail})
		}
	}
	// EmailFallback without UsernameFallback: a single email-only lookup (the caller only
	// runs this when at least one fallback is enabled, so EmailFallback is guaranteed here).
	// Only add it when there is a real email — an empty email would degenerate to an
	// issuer-only lookup and link an arbitrary local user.
	if len(searches) == 0 && cl.Email != "" {
		searches = append(searches, &user.User{Issuer: user.IssuerLocal, Email: cl.Email})
	}

	return searches
}

func getOrCreateUser(s *xorm.Session, cl *claims, provider *Provider, idToken *oidc.IDToken) (u *user.User, err error) {

	// set defaults
	fallbackMatchFound := false
	alreadyCreatedFromIssuer := false

	// first check if the user already signed up using the provider

	u, err = user.GetUserWithEmail(s, &user.User{
		Issuer:  idToken.Issuer,
		Subject: idToken.Subject,
	})
	if err != nil && !user.IsErrUserDoesNotExist(err) && !user.IsErrUserStatusError(err) {
		return nil, err
	}
	alreadyCreatedFromIssuer = err == nil || user.IsErrUserStatusError(err)

	// If the user exists but is disabled/locked, return early — don't update their profile or sync avatar.
	// HandleCallback will reject the auth attempt.
	if alreadyCreatedFromIssuer && user.IsErrUserStatusError(err) {
		return u, nil
	}

	if !alreadyCreatedFromIssuer && (provider.EmailFallback || provider.UsernameFallback) {

		// try finding the user on fallback mapping properties
		for _, searchUser := range fallbackSearchUsers(cl, provider, idToken) {
			u, err = user.GetUserWithEmail(s, searchUser)
			if err != nil && !user.IsErrUserDoesNotExist(err) && !user.IsErrUserStatusError(err) {
				return nil, err
			}
			fallbackMatchFound = err == nil || user.IsErrUserStatusError(err)

			// Same as above: disabled/locked user found via fallback — return early.
			if fallbackMatchFound && user.IsErrUserStatusError(err) {
				return u, nil
			}
			if fallbackMatchFound {
				break
			}
		}
	}

	if !alreadyCreatedFromIssuer && !fallbackMatchFound {

		// If no user exists, create one with the preferred username if it is not already taken
		uu := &user.User{
			Username:           strings.ReplaceAll(cl.PreferredUsername, " ", "-"),
			Email:              cl.Email,
			Name:               cl.Name,
			Status:             user.StatusActive,
			Issuer:             idToken.Issuer,
			Subject:            idToken.Subject,
			ExtraSettingsLinks: cl.ExtraSettingsLinks,
		}

		u, err = auth.CreateUserWithRandomUsername(s, uu)
		if err != nil {
			return nil, err
		}
	} else if alreadyCreatedFromIssuer {

		// try updating user.Name and/or user.Email if necessary
		if cl.Email != u.Email {
			u.Email = cl.Email
		}
		if cl.Name != u.Name {
			u.Name = cl.Name
		}

		u.ExtraSettingsLinks = cl.ExtraSettingsLinks

		u, err = user.UpdateUser(s, u, false)
		if err != nil {
			return nil, err
		}
	}

	// Try sync avatar if available
	err = syncUserAvatarFromOpenID(s, u, cl.Picture)
	if err != nil {
		log.Errorf("Error syncing avatar for user %s: %v", u.Username, err)
	}

	return u, nil
}

// mergeClaims combines claims from token and userinfo based on the ForceUserInfo setting
// cl represents the claims from the token, cl2 represents the claims from userinfo
func mergeClaims(cl *claims, cl2 *claims, forceUserInfo bool) error {
	if (forceUserInfo && cl2.Email != "") || cl.Email == "" {
		cl.Email = cl2.Email
	}

	if (forceUserInfo && cl2.Name != "") || cl.Name == "" {
		cl.Name = cl2.Name
	}

	if (forceUserInfo && cl2.PreferredUsername != "") || cl.PreferredUsername == "" {
		cl.PreferredUsername = cl2.PreferredUsername
	}

	if cl.PreferredUsername == "" && cl2.Nickname != "" {
		cl.PreferredUsername = cl2.Nickname
	}

	if (forceUserInfo && cl2.Picture != "") || cl.Picture == "" {
		cl.Picture = cl2.Picture
	}

	if (forceUserInfo && len(cl2.VikunjaGroups) > 0) || len(cl.VikunjaGroups) == 0 {
		cl.VikunjaGroups = cl2.VikunjaGroups
	}

	if (forceUserInfo && len(cl2.ExtraSettingsLinks) > 0) || len(cl.ExtraSettingsLinks) == 0 {
		cl.ExtraSettingsLinks = cl2.ExtraSettingsLinks
	}

	if cl.Email == "" {
		return &user.ErrNoOpenIDEmailProvided{}
	}

	return nil
}

func getClaims(provider *Provider, oauth2Token *oauth2.Token, idToken *oidc.IDToken) (*claims, error) {

	cl := &claims{}
	err := idToken.Claims(cl)
	if err != nil {
		log.Errorf("Error getting token claims for provider %s: %v", provider.Name, err)
		return nil, err
	}

	if provider.ForceUserInfo || cl.Email == "" || cl.Name == "" || cl.PreferredUsername == "" || cl.Picture == "" {
		info, err := provider.openIDProvider.UserInfo(context.Background(), provider.Oauth2Config.TokenSource(context.Background(), oauth2Token))
		if err != nil {
			log.Errorf("Error getting userinfo for provider %s: %v", provider.Name, err)
			return nil, err
		}

		cl2 := &claims{}
		err = info.Claims(cl2)
		if err != nil {
			log.Errorf("Error parsing userinfo claims for provider %s: %v", provider.Name, err)
			return nil, err
		}

		err = mergeClaims(cl, cl2, provider.ForceUserInfo)
		if err != nil {
			if user.IsErrNoEmailProvided(err) {
				log.Errorf("Claim does not contain an email address for provider %s", provider.Name)
			}

			return nil, err
		}
	}
	return cl, nil
}

// exchangeOidcTokens resolves the provider, exchanges the callback's auth code,
// and verifies the returned ID token. It takes an already-bound Callback so it
// can be shared by the v1 echo handler (which binds from the request) and the v2
// Huma handler (which binds via its typed body).
func exchangeOidcTokens(cb *Callback, providerKey string) (*Provider, *oauth2.Token, *oidc.IDToken, string, error) {
	provider, err := GetProvider(providerKey)
	if err != nil {
		return nil, nil, nil, "", err
	}
	if provider == nil {
		return nil, nil, nil, "", &models.ErrOpenIDBadRequest{Message: "Provider does not exist"}
	}

	log.Debugf("Trying to authenticate user using provider: %s", provider.Key)

	provider.Oauth2Config.RedirectURL = cb.RedirectURL
	// Parse the access & ID token
	oauth2Token, err := provider.Oauth2Config.Exchange(context.Background(), cb.Code)
	if err != nil {
		var rerr *oauth2.RetrieveError
		if errors.As(err, &rerr) {

			details := make(map[string]interface{})
			if err := json.Unmarshal(rerr.Body, &details); err != nil {
				log.Errorf("Error unmarshalling token for provider %s: %v", provider.Name, err)
				log.Debugf("Raw token value is %s", rerr.Body)
				return nil, nil, nil, "", err
			}

			log.Errorf("Error retrieving token: %s", err)
			log.Debugf("Raw token value is %s", rerr.Body)
			return nil, nil, nil, "", &models.ErrOpenIDBadRequestWithDetails{
				Message: "Could not authenticate against third party.",
				Details: details,
			}
		}

		return nil, nil, nil, "", err
	}

	// Extract the ID Token from OAuth2 token.
	rawIDToken, ok := oauth2Token.Extra("id_token").(string)
	if !ok {
		log.Debugf("Could not get id_token, raw token is %v", oauth2Token)
		return nil, nil, nil, "", &models.ErrOpenIDBadRequest{Message: "Missing token"}
	}

	verifier := provider.openIDProvider.Verifier(&oidc.Config{ClientID: provider.ClientID})

	// Parse and verify ID Token payload.
	idToken, err := verifier.Verify(context.Background(), rawIDToken)
	if err != nil {
		log.Errorf("Error verifying token for provider %s: %v", provider.Name, err)
		return nil, nil, nil, "", err
	}

	return provider, oauth2Token, idToken, rawIDToken, nil
}