Two-Factor authentication

Enhancing Dex with 2FA adds an additional layer of security, making unauthorized access significantly more difficult. This is particularly valuable for connectors like LDAP and local connectors that do not inherently support 2FA. By implementing 2FA, we align Dex with industry best practices for identity management, meet higher security compliance requirements, and ensure better protection for user data, thereby building greater trust with our users.

The 2FA data is securely stored within the `OfflineSessions` object and extends support to all configured connectors.

Signed-off-by: m.nabokikh <[email protected]>

cmd/dex/config.go

@@ -51,6 +51,9 @@ type Config struct {
 	// querying the storage. Cannot be specified without enabling a passwords
 	// database.
 	StaticPasswords []password `json:"staticPasswords"`
+
+	// TOTP represents the configuration for two-factor authentication.
+	TOTP TOTP `json:"twoFactorAuthn"`
 }
 
 // Validate the configuration
@@ -422,3 +425,10 @@ type RefreshToken struct {
 	AbsoluteLifetime  string `json:"absoluteLifetime"`
 	ValidIfNotUsedFor string `json:"validIfNotUsedFor"`
 }
+
+type TOTP struct {
+	// Issuer is the name of the service (will be shown in the authenticator app).
+	Issuer string `json:"issuer"`
+	// Connectors is a list of connectors that will use TOTP.
+	Connectors []string `json:"connectors"`
+}

cmd/dex/config_test.go

@@ -343,6 +343,11 @@ expiry:
   idTokens: "25h"
   authRequests: "25h"
 
+twoFactorAuthn:
+  issuer: dex
+  connectors:
+  - mock
+
 logger:
   level: "debug"
   format: "json"
@@ -432,6 +437,10 @@ logger:
 			IDTokens:     "25h",
 			AuthRequests: "25h",
 		},
+		TOTP: TOTP{
+			Issuer:     "dex",
+			Connectors: []string{"mock"},
+		},
 		Logger: Logger{
 			Level:  slog.LevelDebug,
 			Format: "json",

cmd/dex/serve.go

@@ -302,6 +302,8 @@ func runServe(options serveOptions) error {
 		Now:                    now,
 		PrometheusRegistry:     prometheusRegistry,
 		HealthChecker:          healthChecker,
+		TOTPIssuer:             c.TOTP.Issuer,
+		TOTPConnectors:         c.TOTP.Connectors,
 	}
 	if c.Expiry.SigningKeys != "" {
 		signingKeys, err := time.ParseDuration(c.Expiry.SigningKeys)

examples/config-dev.yaml

@@ -75,6 +75,12 @@ telemetry:
   http: 0.0.0.0:5558
   # enableProfiling: true
 
+# Configuration for the two-factor authentication
+# twoFactorAuthn:
+#   issuer: "dex"
+#   connectors:
+#   - mock
+
 # Uncomment this block to enable the gRPC API. This values MUST be different
 # from the HTTP endpoints.
 # grpc:

go.mod

@@ -27,6 +27,7 @@ require (
 	github.com/mattn/go-sqlite3 v1.14.22
 	github.com/oklog/run v1.1.0
 	github.com/pkg/errors v0.9.1
+	github.com/pquerna/otp v1.4.0
 	github.com/prometheus/client_golang v1.19.1
 	github.com/russellhaering/goxmldsig v1.4.0
 	github.com/spf13/cobra v1.8.1
@@ -53,6 +54,7 @@ require (
 	github.com/agext/levenshtein v1.2.1 // indirect
 	github.com/apparentlymart/go-textseg/v13 v13.0.0 // indirect
 	github.com/beorn7/perks v1.0.1 // indirect
+	github.com/boombuler/barcode v1.0.1-0.20190219062509-6c824513bacc // indirect
 	github.com/cespare/xxhash/v2 v2.3.0 // indirect
 	github.com/coreos/go-semver v0.3.0 // indirect
 	github.com/coreos/go-systemd/v22 v22.3.2 // indirect

go.sum

@@ -37,6 +37,8 @@ github.com/beevik/etree v1.4.0 h1:oz1UedHRepuY3p4N5OjE0nK1WLCqtzHf25bxplKOHLs=
 github.com/beevik/etree v1.4.0/go.mod h1:cyWiXwGoasx60gHvtnEh5x8+uIjUVnjWqBvEnhnqKDA=
 github.com/beorn7/perks v1.0.1 h1:VlbKKnNfV8bJzeqoa4cOKqO6bYr3WgKZxO8Z16+hsOM=
 github.com/beorn7/perks v1.0.1/go.mod h1:G2ZrVWU2WbWT9wwq4/hrbKbnv/1ERSJQ0ibhJ6rlkpw=
+github.com/boombuler/barcode v1.0.1-0.20190219062509-6c824513bacc h1:biVzkmvwrH8WK8raXaxBx6fRVTlJILwEwQGL1I/ByEI=
+github.com/boombuler/barcode v1.0.1-0.20190219062509-6c824513bacc/go.mod h1:paBWMcWSl3LHKBqUq+rly7CNSldXjb2rDl3JlRe0mD8=
 github.com/census-instrumentation/opencensus-proto v0.2.1/go.mod h1:f6KPmirojxKA12rnyqOA5BBL4O983OfeGPqjHWSTneU=
 github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
 github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
@@ -187,6 +189,8 @@ github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
 github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/pquerna/otp v1.4.0 h1:wZvl1TIVxKRThZIBiwOOHOGP/1+nZyWBil9Y2XNEDzg=
+github.com/pquerna/otp v1.4.0/go.mod h1:dkJfzwRKNiegxyNb54X/3fLwhCynbMspSyWKnvi1AEg=
 github.com/prometheus/client_golang v1.19.1 h1:wZWJDwK+NameRJuPGDhlnFgx8e8HN3XHQeLaYJFJBOE=
 github.com/prometheus/client_golang v1.19.1/go.mod h1:mP78NwGzrVks5S2H6ab8+ZZGJLZUq1hoULYBAYBw1Ho=
 github.com/prometheus/client_model v0.0.0-20190812154241-14fe0d1b01d4/go.mod h1:xMI15A0UPsDsEKsMN9yxemIoYk6Tm2C1GtYGdfGttqA=

server/handlers.go

@@ -11,7 +11,6 @@ import (
 	"html/template"
 	"net/http"
 	"net/url"
-	"path"
 	"sort"
 	"strconv"
 	"strings"
@@ -514,6 +513,11 @@ func (s *Server) finalizeLogin(ctx context.Context, identity connector.Identity,
 		a.LoggedIn = true
 		a.Claims = claims
 		a.ConnectorData = identity.ConnectorData
+
+		if !s.totp.enabledForConnector(a.ConnectorID) {
+			a.TOTPValidated = true
+		}
+
 		return a, nil
 	}
 	if err := s.storage.UpdateAuthRequest(authReq.ID, updater); err != nil {
@@ -529,36 +533,11 @@ func (s *Server) finalizeLogin(ctx context.Context, identity connector.Identity,
 		"connector_id", authReq.ConnectorID, "username", claims.Username,
 		"preferred_username", claims.PreferredUsername, "email", email, "groups", claims.Groups)
 
-	// we can skip the redirect to /approval and go ahead and send code if it's not required
-	if s.skipApproval && !authReq.ForceApprovalPrompt {
-		return "", true, nil
-	}
-
-	// an HMAC is used here to ensure that the request ID is unpredictable, ensuring that an attacker who intercepted the original
-	// flow would be unable to poll for the result at the /approval endpoint
-	h := hmac.New(sha256.New, authReq.HMACKey)
-	h.Write([]byte(authReq.ID))
-	mac := h.Sum(nil)
-
-	returnURL := path.Join(s.issuerURL.Path, "/approval") + "?req=" + authReq.ID + "&hmac=" + base64.RawURLEncoding.EncodeToString(mac)
-	_, ok := conn.(connector.RefreshConnector)
-	if !ok {
-		return returnURL, false, nil
-	}
-
-	offlineAccessRequested := false
-	for _, scope := range authReq.Scopes {
-		if scope == scopeOfflineAccess {
-			offlineAccessRequested = true
-			break
-		}
-	}
-	if !offlineAccessRequested {
-		return returnURL, false, nil
-	}
-
 	// Try to retrieve an existing OfflineSession object for the corresponding user.
-	session, err := s.storage.GetOfflineSessions(identity.UserID, authReq.ConnectorID)
+	// TODO(nabokihms): We create an offline session even if the offline access is not requested.
+	//   In the future it will be possible to migrate to sessions.
+	//   Sessions may contain attributes like approval status, etc.
+	_, err := s.storage.GetOfflineSessions(identity.UserID, authReq.ConnectorID)
 	if err != nil {
 		if err != storage.ErrNotFound {
 			s.logger.ErrorContext(ctx, "failed to get offline session", "err", err)
@@ -571,18 +550,25 @@ func (s *Server) finalizeLogin(ctx context.Context, identity connector.Identity,
 			ConnectorData: identity.ConnectorData,
 		}
 
+		if s.totp.enabledForConnector(authReq.ConnectorID) {
+			generated, err := s.totp.generate(authReq.ConnectorID, identity.Email)
+			if err != nil {
+				s.logger.ErrorContext(ctx, "failed to generate totp for offline session", "err", err)
+				return "", false, err
+			}
+			offlineSessions.TOTP = generated.String()
+		}
+
 		// Create a new OfflineSession object for the user and add a reference object for
 		// the newly received refreshtoken.
 		if err := s.storage.CreateOfflineSessions(ctx, offlineSessions); err != nil {
 			s.logger.ErrorContext(ctx, "failed to create offline session", "err", err)
 			return "", false, err
 		}
-
-		return returnURL, false, nil
 	}
 
 	// Update existing OfflineSession obj with new RefreshTokenRef.
-	if err := s.storage.UpdateOfflineSessions(session.UserID, session.ConnID, func(old storage.OfflineSessions) (storage.OfflineSessions, error) {
+	if err := s.storage.UpdateOfflineSessions(identity.UserID, authReq.ConnectorID, func(old storage.OfflineSessions) (storage.OfflineSessions, error) {
 		if len(identity.ConnectorData) > 0 {
 			old.ConnectorData = identity.ConnectorData
 		}
@@ -592,7 +578,32 @@ func (s *Server) finalizeLogin(ctx context.Context, identity connector.Identity,
 		return "", false, err
 	}
 
-	return returnURL, false, nil
+	// we can skip the redirect to /approval and /totp and go ahead and send code if it's not required
+	if s.skipApproval && !authReq.ForceApprovalPrompt && !s.totp.enabledForConnector(authReq.ConnectorID) {
+		return "", true, nil
+	}
+
+	// an HMAC is used here to ensure that the request ID is unpredictable, ensuring that an attacker who intercepted the original
+	// flow would be unable to poll for the result at the /approval endpoint
+	h := hmac.New(sha256.New, authReq.HMACKey)
+	h.Write([]byte(authReq.ID))
+	mac := h.Sum(nil)
+
+	// Deep copy issuer URL to avoid modifying the global one.
+	returnURL, _ := url.Parse(s.issuerURL.String())
+	values := returnURL.Query()
+	values.Set("req", authReq.ID)
+	values.Set("hmac", base64.RawURLEncoding.EncodeToString(mac))
+
+	if s.totp.enabledForConnector(authReq.ConnectorID) {
+		values.Set("state", identity.UserID)
+		returnURL = returnURL.JoinPath("totp")
+	} else {
+		returnURL = returnURL.JoinPath("approval")
+	}
+
+	returnURL.RawQuery = values.Encode()
+	return returnURL.String(), false, nil
 }
 
 func (s *Server) handleApproval(w http.ResponseWriter, r *http.Request) {
@@ -613,7 +624,7 @@ func (s *Server) handleApproval(w http.ResponseWriter, r *http.Request) {
 		s.renderError(r, w, http.StatusInternalServerError, "Database error.")
 		return
 	}
-	if !authReq.LoggedIn {
+	if !authReq.LoggedIn || !authReq.TOTPValidated {
 		s.logger.ErrorContext(r.Context(), "auth request does not have an identity for approval")
 		s.renderError(r, w, http.StatusInternalServerError, "Login process not yet finalized.")
 		return

server/server.go

@@ -120,6 +120,9 @@ type Config struct {
 	PrometheusRegistry *prometheus.Registry
 
 	HealthChecker gosundheit.Health
+
+	TOTPIssuer     string
+	TOTPConnectors []string
 }
 
 // WebConfig holds the server's frontend templates and asset configuration.
@@ -197,6 +200,8 @@ type Server struct {
 	refreshTokenPolicy *RefreshTokenPolicy
 
 	logger *slog.Logger
+
+	totp *secondFactorAuthenticator
 }
 
 // NewServer constructs a server from the provided config.
@@ -312,6 +317,7 @@ func newServer(ctx context.Context, c Config, rotationStrategy rotationStrategy)
 		now:                    now,
 		templates:              tmpls,
 		passwordConnector:      c.PasswordConnector,
+		totp:                   newSecondFactorAuthenticator(c.TOTPIssuer, c.TOTPConnectors),
 		logger:                 c.Logger,
 	}
 
@@ -463,6 +469,7 @@ func newServer(ctx context.Context, c Config, rotationStrategy rotationStrategy)
 	// "authproxy" connector.
 	handleFunc("/callback/{connector}", s.handleConnectorCallback)
 	handleFunc("/approval", s.handleApproval)
+	handleFunc("/totp", s.handleTOTPVerify)
 	handle("/healthz", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		if !c.HealthChecker.IsHealthy() {
 			s.renderError(r, w, http.StatusInternalServerError, "Health check failed.")

server/templates.go

@@ -22,6 +22,7 @@ const (
 	tmplError         = "error.html"
 	tmplDevice        = "device.html"
 	tmplDeviceSuccess = "device_success.html"
+	tmplTOTPVerify    = "totp_verify.html"
 )
 
 var requiredTmpls = []string{
@@ -32,6 +33,7 @@ var requiredTmpls = []string{
 	tmplError,
 	tmplDevice,
 	tmplDeviceSuccess,
+	tmplTOTPVerify,
 }
 
 type templates struct {
@@ -42,6 +44,7 @@ type templates struct {
 	errorTmpl         *template.Template
 	deviceTmpl        *template.Template
 	deviceSuccessTmpl *template.Template
+	tmplTOTPVerify    *template.Template
 }
 
 type webConfig struct {
@@ -169,6 +172,7 @@ func loadTemplates(c webConfig, templatesDir string) (*templates, error) {
 		errorTmpl:         tmpls.Lookup(tmplError),
 		deviceTmpl:        tmpls.Lookup(tmplDevice),
 		deviceSuccessTmpl: tmpls.Lookup(tmplDeviceSuccess),
+		tmplTOTPVerify:    tmpls.Lookup(tmplTOTPVerify),
 	}, nil
 }
 
@@ -282,6 +286,21 @@ func (t *templates) deviceSuccess(r *http.Request, w http.ResponseWriter, client
 	return renderTemplate(w, t.deviceSuccessTmpl, data)
 }
 
+func (t *templates) totpVerify(r *http.Request, w http.ResponseWriter, postURL, issuer, connector, qrCode string, lastWasInvalid bool) error {
+	if lastWasInvalid {
+		w.WriteHeader(http.StatusUnauthorized)
+	}
+	data := struct {
+		PostURL   string
+		Invalid   bool
+		Issuer    string
+		Connector string
+		QRCode    string
+		ReqPath   string
+	}{postURL, lastWasInvalid, issuer, connector, qrCode, r.URL.Path}
+	return renderTemplate(w, t.tmplTOTPVerify, data)
+}
+
 func (t *templates) login(r *http.Request, w http.ResponseWriter, connectors []connectorInfo) error {
 	sort.Sort(byName(connectors))
 	data := struct {