feat: allow limiting lifespan of low-aal sessions

Author: hf

Diff for: internal/api/token_refresh.go

@@ -65,7 +65,13 @@ func (a *API) RefreshTokenGrant(ctx context.Context, w http.ResponseWriter, r *h
 			return badRequestError(apierrors.ErrorCodeSessionNotFound, "Invalid Refresh Token: No Valid Session Found")
 		}
 
-		result := session.CheckValidity(retryStart, &token.UpdatedAt, config.Sessions.Timebox, config.Sessions.InactivityTimeout)
+		sessionValidityConfig := models.SessionValidityConfig{
+			Timebox:           config.Sessions.Timebox,
+			InactivityTimeout: config.Sessions.InactivityTimeout,
+			AllowLowAAL:       config.Sessions.AllowLowAAL,
+		}
+
+		result := session.CheckValidity(sessionValidityConfig, retryStart, &token.UpdatedAt, user.HighestPossibleAAL())
 
 		switch result {
 		case models.SessionValid:
@@ -74,6 +80,9 @@ func (a *API) RefreshTokenGrant(ctx context.Context, w http.ResponseWriter, r *h
 		case models.SessionTimedOut:
 			return badRequestError(apierrors.ErrorCodeSessionExpired, "Invalid Refresh Token: Session Expired (Inactivity)")
 
+		case models.SessionLowAAL:
+			return badRequestError(apierrors.ErrorCodeSessionExpired, "Invalid Refresh Token: Session Expired (Low AAL: User Needs MFA Verification)")
+
 		default:
 			return badRequestError(apierrors.ErrorCodeSessionExpired, "Invalid Refresh Token: Session Expired")
 		}
@@ -134,7 +143,7 @@ func (a *API) RefreshTokenGrant(ctx context.Context, w http.ResponseWriter, r *h
 						continue
 					}
 
-					if s.CheckValidity(retryStart, nil, config.Sessions.Timebox, config.Sessions.InactivityTimeout) != models.SessionValid {
+					if s.CheckValidity(sessionValidityConfig, retryStart, nil, user.HighestPossibleAAL()) != models.SessionValid {
 						// session is not valid so it
 						// can't be regarded as active
 						// on the user

Diff for: internal/conf/configuration.go

@@ -163,20 +163,25 @@ func (a *APIConfiguration) Validate() error {
 }
 
 type SessionsConfiguration struct {
-	Timebox           *time.Duration `json:"timebox"`
+	Timebox           *time.Duration `json:"timebox,omitempty"`
 	InactivityTimeout *time.Duration `json:"inactivity_timeout,omitempty" split_words:"true"`
+	AllowLowAAL       *time.Duration `json:"allow_low_aal,omitempty" split_words:"true"`
 
 	SinglePerUser bool     `json:"single_per_user" split_words:"true"`
 	Tags          []string `json:"tags,omitempty"`
 }
 
 func (c *SessionsConfiguration) Validate() error {
-	if c.Timebox == nil {
-		return nil
+	if c.Timebox != nil && *c.Timebox <= time.Duration(0) {
+		return fmt.Errorf("conf: session timebox duration must be positive when set, was %v", (*c.Timebox).String())
 	}
 
-	if *c.Timebox <= time.Duration(0) {
-		return fmt.Errorf("conf: session timebox duration must be positive when set, was %v", (*c.Timebox).String())
+	if c.InactivityTimeout != nil && *c.InactivityTimeout <= time.Duration(0) {
+		return fmt.Errorf("conf: session inactivity timeout duration must be positive when set, was %v", (*c.InactivityTimeout).String())
+	}
+
+	if c.AllowLowAAL != nil && *c.AllowLowAAL <= time.Duration(0) {
+		return fmt.Errorf("conf: session allow low AAL duration must be positive when set, was %v", (*c.InactivityTimeout).String())
 	}
 
 	return nil

Diff for: internal/conf/configuration_test.go

@@ -490,6 +490,17 @@ func TestValidate(t *testing.T) {
 			err: `conf: session timebox duration must` +
 				` be positive when set, was -1`,
 		},
+		{
+			val: &SessionsConfiguration{AllowLowAAL: nil},
+		},
+		{
+			val: &SessionsConfiguration{AllowLowAAL: new(time.Duration)},
+			err: `conf: session allow low AAL duration must be positive when set, was 0`,
+		},
+		{
+			val: &SessionsConfiguration{AllowLowAAL: toPtr(time.Duration(-1))},
+			err: `conf: session allow low AAL duration must be positive when set, was -1`,
+		},
 		{
 			val: &SessionsConfiguration{Timebox: toPtr(time.Duration(1))},
 		},

Diff for: internal/models/sessions.go

@@ -34,6 +34,36 @@ func (aal AuthenticatorAssuranceLevel) String() string {
 	}
 }
 
+func (aal AuthenticatorAssuranceLevel) PointerString() *string {
+	value := aal.String()
+
+	return &value
+}
+
+// CompareAAL returns 0 if both AAL levels are equal, > 0 if A is a higher level than B or < 0 if A is a lower level than B.
+func CompareAAL(a, b AuthenticatorAssuranceLevel) int {
+	return strings.Compare(a.String(), b.String())
+}
+
+func ParseAAL(value *string) AuthenticatorAssuranceLevel {
+	if value == nil {
+		return AAL1
+	}
+
+	switch *value {
+	case AAL1.String():
+		return AAL1
+
+	case AAL2.String():
+		return AAL2
+
+	case AAL3.String():
+		return AAL3
+	}
+
+	return AAL1
+}
+
 // AMREntry represents a method that a user has logged in together with the corresponding time
 type AMREntry struct {
 	Method    string `json:"method"`
@@ -117,21 +147,32 @@ const (
 	SessionPastNotAfter                       = iota
 	SessionPastTimebox                        = iota
 	SessionTimedOut                           = iota
+	SessionLowAAL                             = iota
 )
 
-func (s *Session) CheckValidity(now time.Time, refreshTokenTime *time.Time, timebox, inactivityTimeout *time.Duration) SessionValidityReason {
+type SessionValidityConfig struct {
+	Timebox           *time.Duration
+	InactivityTimeout *time.Duration
+	AllowLowAAL       *time.Duration
+}
+
+func (s *Session) CheckValidity(config SessionValidityConfig, now time.Time, refreshTokenTime *time.Time, userHighestPossibleAAL AuthenticatorAssuranceLevel) SessionValidityReason {
 	if s.NotAfter != nil && now.After(*s.NotAfter) {
 		return SessionPastNotAfter
 	}
 
-	if timebox != nil && *timebox != 0 && now.After(s.CreatedAt.Add(*timebox)) {
+	if config.Timebox != nil && *config.Timebox != 0 && now.After(s.CreatedAt.Add(*config.Timebox)) {
 		return SessionPastTimebox
 	}
 
-	if inactivityTimeout != nil && *inactivityTimeout != 0 && now.After(s.LastRefreshedAt(refreshTokenTime).Add(*inactivityTimeout)) {
+	if config.InactivityTimeout != nil && *config.InactivityTimeout != 0 && now.After(s.LastRefreshedAt(refreshTokenTime).Add(*config.InactivityTimeout)) {
 		return SessionTimedOut
 	}
 
+	if config.AllowLowAAL != nil && *config.AllowLowAAL != 0 && CompareAAL(ParseAAL(s.AAL), userHighestPossibleAAL) < 0 && now.After(s.CreatedAt.Add(*config.AllowLowAAL)) {
+		return SessionLowAAL
+	}
+
 	return SessionValid
 }
 
@@ -161,11 +202,9 @@ func (s *Session) DetermineTag(tags []string) string {
 func NewSession(userID uuid.UUID, factorID *uuid.UUID) (*Session, error) {
 	id := uuid.Must(uuid.NewV4())
 
-	defaultAAL := AAL1.String()
-
 	session := &Session{
 		ID:       id,
-		AAL:      &defaultAAL,
+		AAL:      AAL1.PointerString(),
 		UserID:   userID,
 		FactorID: factorID,
 	}

Diff for: internal/models/sessions_test.go

@@ -102,3 +102,53 @@ func (ts *SessionsTestSuite) TestCalculateAALAndAMR() {
 	}
 	require.True(ts.T(), found)
 }
+
+func pointerDuration(value time.Duration) *time.Duration {
+	return &value
+}
+
+func TestCheckValidity(t *testing.T) {
+	start := time.Now()
+
+	examples := []struct {
+		name               string
+		session            *Session
+		highestPossibleAAL AuthenticatorAssuranceLevel
+		now                time.Time
+		config             SessionValidityConfig
+		expected           SessionValidityReason
+	}{
+		{
+			name:               "low aal session past creation time is invalid",
+			now:                start.Add(time.Second * 61),
+			highestPossibleAAL: AAL2,
+			session: &Session{
+				AAL:       AAL1.PointerString(),
+				CreatedAt: start,
+			},
+			config: SessionValidityConfig{
+				AllowLowAAL: pointerDuration(time.Second * 60),
+			},
+			expected: SessionLowAAL,
+		},
+		{
+			name:               "high aal session is valid past creation time",
+			now:                start.Add(time.Second * 61),
+			highestPossibleAAL: AAL2,
+			session: &Session{
+				AAL:       AAL2.PointerString(),
+				CreatedAt: start,
+			},
+			config: SessionValidityConfig{
+				AllowLowAAL: pointerDuration(time.Second * 60),
+			},
+			expected: SessionValid,
+		},
+	}
+
+	for _, example := range examples {
+		t.Run(example.name, func(t *testing.T) {
+			require.Equal(t, example.expected, example.session.CheckValidity(example.config, example.now, &example.now, example.highestPossibleAAL))
+		})
+	}
+}

Diff for: internal/models/user.go

@@ -584,6 +584,18 @@ func (u *User) Recover(tx *storage.Connection) error {
 	return ClearAllOneTimeTokensForUser(tx, u.ID)
 }
 
+// HighestPossibleAAL returns the AAL level that this user can obtain. Derived
+// from the number of verified MFA factors associated with the user object.
+func (u *User) HighestPossibleAAL() AuthenticatorAssuranceLevel {
+	for _, factor := range u.Factors {
+		if factor.Status == FactorStateVerified.String() {
+			return AAL2
+		}
+	}
+
+	return AAL1
+}
+
 // CountOtherUsers counts how many other users exist besides the one provided
 func CountOtherUsers(tx *storage.Connection, id uuid.UUID) (int, error) {
 	userCount, err := tx.Q().Where("instance_id = ? and id != ?", uuid.Nil, id).Count(&User{})