feat: Refresh token expiration window

docs/docs/guides/token-expiration.mdx

@@ -75,6 +75,44 @@ for refresh tokens to never expire.
     #....
 ```
 
+### Refresh Token Rotation
+
+When a refresh token is used it is deactivated, which is known as Refresh Token
+Rotation. By default Hydra deactivates the refresh token it receives and issues
+a new token. More information on Refresh Token Rotation can be found in the
+Recommendations section of the OAuth 2.0 Security Best Practices document
+[here](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics#section-4.13.2).
+
+There are some cases when a one time use refresh token may be undesirable, such
+as when a networking error occurs and the newly issued refresh token is not
+received. Hydra may be configured to use a refresh token grace period which
+allows a refresh token to be reused for the duration of the grace period. Note
+that a new refresh token is still generated and sent back in the response;
+clients **must** store and use the new refresh token.
+
+**WARNING** Using the refresh token grace period is an increased security risk,
+as an intercepted refresh token may be reused by a bad actor. Use this feature
+with appropriate consideration.
+
+```
+  ## refresh_token_rotation
+  #
+  # By default Refresh Tokens are rotated and invalidated with each use.
+  # See https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics#section-4.13.2 for more details
+  #
+  refresh_token_rotation:
+    #
+    ## grace_period
+    #
+    # Set the grace period for a refresh token to allow it to be used for the duration of this configuration after
+    # its first use. New refresh tokens will continue to be issued.
+    #
+    # Examples:
+    # - 5s
+    # - 1m
+    grace_period: 0s
+```
+
 ## ID Token Expiration
 
 Key `ttl.id_token` configures how long id tokens are valid.

docs/docs/reference/configuration.md

@@ -1329,6 +1329,22 @@ oauth2:
   #
   expose_internal_errors: true
 
+  ## refresh_token_rotation
+  #
+  # By default Refresh Tokens are rotated and invalidated with each use. See https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics#section-4.13.2 for more details
+  #
+  refresh_token_rotation:
+    #
+    ## grace_period
+    #
+    # Set the grace period for a refresh token to allow it to be used for the duration of this configuration after its first use. New refresh tokens will continue
+    # to be issued.
+    #
+    # Examples:
+    # - 5s
+    # - 1m
+    grace_period: 0s
+
 ## secrets ##
 #
 # The secrets section configures secrets used for encryption and signing of several systems. All secrets can be rotated, for more information on this topic go to: https://www.ory.sh/docs/hydra/advanced#rotation-of-hmac-token-signing-and-database-and-cookie-encryption-keys

driver/config/provider.go

@@ -65,6 +65,7 @@ const (
 	KeyOAuth2LegacyErrors                        = "oauth2.include_legacy_error_fields"
 	KeyExcludeNotBeforeClaim                     = "oauth2.exclude_not_before_claim"
 	KeyAllowedTopLevelClaims                     = "oauth2.allowed_top_level_claims"
+	KeyRefreshTokenRotationGracePeriod           = "oauth2.refresh_token_rotation.grace_period"
 )
 
 const DSNMemory = "memory"
@@ -428,3 +429,7 @@ func (p *Provider) CGroupsV1AutoMaxProcsEnabled() bool {
 func (p *Provider) GrantAllClientCredentialsScopesPerDefault() bool {
 	return p.p.Bool(KeyGrantAllClientCredentialsScopesPerDefault)
 }
+
+func(p *Provider) RefreshTokenRotationGracePeriod() time.Duration {
+	return p.p.DurationF(KeyRefreshTokenRotationGracePeriod, 0)
+}

internal/config/config.yaml

@@ -413,6 +413,21 @@ secrets:
     - this-is-an-old-secret
     - this-is-another-old-secret
 
+  ## refresh_token_rotation
+  #
+  # By default Refresh Tokens are rotated and invalidated with each use. See https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics#section-4.13.2 for more details
+  #
+  refresh_token_rotation:
+    #
+    ## grace_period
+    # 
+    # Set the grace period for a refresh token to allow it to be used for the duration of this configuration after its first use. New refresh tokens will continue
+    # to be issued. 
+    #
+    # Examples:
+    # - 5s
+    # - 1m
+    grace_period: 0s
 
 # Enables profiling if set. Use "cpu" to enable cpu profiling and "mem" to enable memory profiling. For more details
 # on profiling, head over to: https://blog.golang.org/profiling-go-programs

oauth2/fosite_store_helpers.go

@@ -180,8 +180,10 @@ func TestHelperRunner(t *testing.T, store InternalRegistry, k string) {
 	t.Run(fmt.Sprintf("case=testFositeStoreClientAssertionJWTValid/db=%s", k), testFositeStoreClientAssertionJWTValid(store))
 	t.Run(fmt.Sprintf("case=testHelperDeleteAccessTokens/db=%s", k), testHelperDeleteAccessTokens(store))
 	t.Run(fmt.Sprintf("case=testHelperRevokeAccessToken/db=%s", k), testHelperRevokeAccessToken(store))
+	t.Run(fmt.Sprintf("case=testHelperRevokeRefreshTokenMaybeGracePeriod/db=%s", k), testHelperRevokeRefreshTokenMaybeGracePeriod(store))
 }
 
+
 func testHelperRequestIDMultiples(m InternalRegistry, _ string) func(t *testing.T) {
 	return func(t *testing.T) {
 		requestId := uuid.New()
@@ -408,6 +410,68 @@ func testHelperRevokeAccessToken(x InternalRegistry) func(t *testing.T) {
 	}
 }
 
+func testHelperRevokeRefreshTokenMaybeGracePeriod(x InternalRegistry) func(t *testing.T) {
+
+	return func(t *testing.T) {
+		t.Run("Revokes refresh token when grace period not configured", func(t *testing.T) {
+			// SETUP
+			m := x.OAuth2Storage()
+			ctx := context.Background()
+
+			refreshTokenSession := fmt.Sprintf("refresh_token_%d", time.Now().Unix())
+			err := m.CreateRefreshTokenSession(ctx, refreshTokenSession, &defaultRequest)
+			assert.NoError(t, err, "precondition failed: could not create refresh token session")
+
+			// ACT
+			err = m.RevokeRefreshTokenMaybeGracePeriod(ctx, defaultRequest.GetID(), refreshTokenSession)
+
+			// ASSERT
+			assert.NoError(t, err)
+
+			tmpSession := new(fosite.Session)
+			_, err = m.GetRefreshTokenSession(ctx, refreshTokenSession, *tmpSession)
+
+			// a revoked refresh token returns an error when getting the token again
+			assert.Error(t, err)
+			assert.True(t, errors.Is(err, fosite.ErrInactiveToken))
+		})
+
+		t.Run("refresh token enters grace period when configured,", func(t *testing.T) {
+
+			/* TODO: figure out how to change config values and get a new/udpated OAuth2Storage instance
+			// SETUP
+			log := logrusx.New("testGracePeriod", "na")
+			option := configx.WithValue("oauth2.refresh_token_rotation.grace_period", "1m")
+			c := config.MustNew(log, option)
+
+			//TODO make m := OAuth2Storage
+
+			ctx := context.Background()
+
+			refreshTokenSession := fmt.Sprintf("refresh_token_%d", time.Now().Unix())
+			err := m.CreateRefreshTokenSession(ctx, refreshTokenSession, &defaultRequest)
+			assert.NoError(t, err, "precondition failed: could not create refresh token session")
+
+			// ACT
+			err = m.RevokeRefreshTokenMaybeGracePeriod(ctx,defaultRequest.GetID(), refreshTokenSession)
+
+			// ASSERT
+			assert.NoError(t, err)
+
+			tmpSession := new(fosite.Session)
+			_, err = m.GetRefreshTokenSession(ctx, refreshTokenSession, *tmpSession)
+
+			// when grace period is configured the refresh token can be obtained within
+			// the grace period without error
+			assert.NoError(t, err)
+
+			registry.WithConfig(oldConfig)
+			*/
+		})
+	}
+
+}
+
 func testHelperCreateGetDeletePKCERequestSession(x InternalRegistry) func(t *testing.T) {
 	return func(t *testing.T) {
 		m := x.OAuth2Storage()

persistence/sql/migrations/20211101093405_add_refresh_token_used_flag.down.sql

@@ -0,0 +1 @@
+ALTER TABLE hydra_oauth2_refresh DROP COLUMN used;

persistence/sql/migrations/20211101093405_add_refresh_token_used_flag.up.sql

@@ -0,0 +1 @@
+ALTER TABLE hydra_oauth2_refresh ADD used bool DEFAULT false;

persistence/sql/models/models.go

@@ -0,0 +1 @@
+package models

persistence/sql/persister_oauth2.go

@@ -56,7 +56,11 @@ const (
 )
 
 func (r OAuth2RequestSQL) TableName() string {
-	return "hydra_oauth2_" + string(r.Table)
+	return r.Table.TableName()
+}
+
+func (table tableName) TableName() string {
+	return "hydra_oauth2_" + string(table)
 }
 
 func (p *Persister) sqlSchemaFromRequest(rawSignature string, r fosite.Requester, table tableName) (*OAuth2RequestSQL, error) {
@@ -67,19 +71,11 @@ func (p *Persister) sqlSchemaFromRequest(rawSignature string, r fosite.Requester
 		subject = r.GetSession().GetSubject()
 	}
 
-	session, err := json.Marshal(r.GetSession())
+	session, err := p.marshalSession(r.GetSession())
 	if err != nil {
 		return nil, errorsx.WithStack(err)
 	}
 
-	if p.config.EncryptSessionData() {
-		ciphertext, err := p.r.KeyCipher().Encrypt(session)
-		if err != nil {
-			return nil, errorsx.WithStack(err)
-		}
-		session = []byte(ciphertext)
-	}
-
 	var challenge sql.NullString
 	rr, ok := r.GetSession().(*oauth2.Session)
 	if !ok && r.GetSession() != nil {
@@ -108,6 +104,31 @@ func (p *Persister) sqlSchemaFromRequest(rawSignature string, r fosite.Requester
 	}, nil
 }
 
+func (p *Persister) marshalSession(session fosite.Session) ([]byte, error) {
+	sessionBytes, err := json.Marshal(session)
+	if err != nil {
+		return nil, err
+	}
+
+	if sessionBytes, err = p.maybeEncryptSession(sessionBytes); err != nil {
+		return nil, err
+	}
+	return sessionBytes, nil
+}
+
+// MaybeEncryptSession encrypt a session if configuration indicates it should
+func (p *Persister) maybeEncryptSession(session []byte) ([]byte, error) {
+	if !p.config.EncryptSessionData() {
+		return session, nil
+	}
+
+	ciphertext, err := p.r.KeyCipher().Encrypt(session)
+	if err != nil {
+		return nil, err
+	}
+	return []byte(ciphertext), nil
+}
+
 func (r *OAuth2RequestSQL) toRequest(ctx context.Context, session fosite.Session, p *Persister) (*fosite.Request, error) {
 	sess := r.Session
 	if !gjson.ValidBytes(sess) {
@@ -219,6 +240,30 @@ func (p *Persister) createSession(ctx context.Context, signature string, request
 	return nil
 }
 
+func (p *Persister) updateRefreshSession(ctx context.Context, requestId string, session fosite.Session, used bool) error {
+	_, ok := session.(*oauth2.Session)
+	if !ok && session != nil {
+		return errors.Errorf("Expected session to be of type *Session, but got: %T", session)
+	}
+	sessionBytes, err := p.marshalSession(session)
+	if err != nil {
+		return err
+	}
+
+	updateSql := fmt.Sprintf("UPDATE %s SET session_data = ?, used = ? WHERE request_id = ?",
+		sqlTableRefresh.TableName())
+
+	return p.transaction(ctx, func(ctx context.Context, c *pop.Connection) error {
+		err := p.Connection(ctx).RawQuery(updateSql, sessionBytes, used, requestId).Exec()
+		if errors.Is(err, sql.ErrNoRows) {
+			return errorsx.WithStack(fosite.ErrNotFound)
+		} else if err != nil {
+			return sqlcon.HandleError(err)
+		}
+		return nil
+	})
+}
+
 func (p *Persister) findSessionBySignature(ctx context.Context, rawSignature string, session fosite.Session, table tableName) (fosite.Requester, error) {
 	rawSignature = p.hashSignature(rawSignature, table)
 
@@ -280,13 +325,27 @@ func (p *Persister) deactivateSessionByRequestID(ctx context.Context, id string,
 	return sqlcon.HandleError(
 		p.Connection(ctx).
 			RawQuery(
-				fmt.Sprintf("UPDATE %s SET active=false WHERE request_id=?", OAuth2RequestSQL{Table: table}.TableName()),
+				fmt.Sprintf("UPDATE %s SET active=false, used=true WHERE request_id=?", OAuth2RequestSQL{Table: table}.TableName()),
 				id,
 			).
 			Exec(),
 	)
 }
 
+func (p *Persister) getRefreshTokenUsedStatusBySignature(ctx context.Context, signature string) (bool, error) {
+	var used bool
+	return used, p.transaction(ctx, func(ctx context.Context, c *pop.Connection) error {
+		query := fmt.Sprintf("SELECT used FROM %s WHERE signature = ?", sqlTableRefresh.TableName())
+		err := p.Connection(ctx).RawQuery(query, signature).First(&used)
+		if errors.Is(err, sql.ErrNoRows) {
+			return errorsx.WithStack(fosite.ErrNotFound)
+		} else if err != nil {
+			return sqlcon.HandleError(err)
+		}
+		return err
+	})
+}
+
 func (p *Persister) CreateAuthorizeCodeSession(ctx context.Context, signature string, requester fosite.Requester) (err error) {
 	return p.createSession(ctx, signature, requester, sqlTableCode)
 }
@@ -353,8 +412,41 @@ func (p *Persister) DeletePKCERequestSession(ctx context.Context, signature stri
 	return p.deleteSessionBySignature(ctx, signature, sqlTablePKCE)
 }
 
-func (p *Persister) RevokeRefreshToken(ctx context.Context, id string) error {
-	return p.deactivateSessionByRequestID(ctx, id, sqlTableRefresh)
+func (p *Persister) RevokeRefreshToken(ctx context.Context, requestId string) error {
+	return p.deactivateSessionByRequestID(ctx, requestId, sqlTableRefresh)
+}
+
+func (p *Persister) RevokeRefreshTokenMaybeGracePeriod(ctx context.Context, requestId string, signature string) error {
+	gracePeriod := p.config.RefreshTokenRotationGracePeriod()
+	if gracePeriod <= 0 {
+		return p.RevokeRefreshToken(ctx, requestId)
+	}
+
+	var requester fosite.Requester
+	var err error
+	session := new(oauth2.Session)
+	if requester, err = p.GetRefreshTokenSession(ctx, signature, session); err != nil {
+		p.l.Errorf("signature: %s not found. grace period not applied", signature)
+		return errors.WithStack(err)
+	}
+
+	var used bool
+	if used,err = p.getRefreshTokenUsedStatusBySignature(ctx, signature); err != nil {
+		p.l.Errorf("signature: %s used status not found. grace period not applied", signature)
+		return errors.WithStack(err)
+	}
+
+	if ! used {
+		session := requester.GetSession()
+		session.SetExpiresAt(fosite.RefreshToken, time.Now().UTC().Add(gracePeriod))
+		if err = p.updateRefreshSession(ctx, requestId, session, true); err != nil {
+			p.l.Errorf("failed to update session with signature: %s", signature)
+			return errors.WithStack(err)
+		}
+	} else {
+		p.l.Debugf("request_id: %s has already been used and is in the grace period", requestId)
+	}
+	return nil
 }
 
 func (p *Persister) RevokeAccessToken(ctx context.Context, id string) error {

spec/config.json

@@ -867,9 +867,23 @@
               ]
             }
           }
+        },
+        "refresh_token_rotation": {
+        "type": "object",
+        "properties": {
+          "grace_period": {
+            "description": "Configures how long a Refresh Token remains valid after it has been used.",
+            "default": "0h",
+            "allOf": [
+              {
+                "$ref": "#/definitions/duration"
+              }
+            ]
+          }
         }
       }
-    },
+    }
+  },
     "secrets": {
       "type": "object",
       "additionalProperties": false,