feat: add refresh-nonce parameter to control nonce behavior on refresh (#590)

Co-authored-by: Jan-Otto Kröpke <[email protected]>

Author: MisterCalvin

docs/Configuration.md

@@ -76,6 +76,8 @@ Usage of openvpn-auth-oauth2:
     	oauth2 issuer (env: CONFIG_OAUTH2_ISSUER)
   --oauth2.nonce
     	If true, a nonce will be defined on the auth URL which is expected inside the token. (env: CONFIG_OAUTH2_NONCE) (default true)
+  --oauth2.refresh-nonce value
+    	Controls nonce behavior on refresh token requests. Options: auto (try with nonce, retry without on error), empty (always use empty nonce), equal (use same nonce as initial auth). (env: CONFIG_OAUTH2_REFRESH__NONCE) (default auto)
   --oauth2.pkce
     	If true, Proof Key for Code Exchange (PKCE) RFC 7636 is used for token exchange. (env: CONFIG_OAUTH2_PKCE) (default true)
   --oauth2.provider string

docs/Non-interactive session refresh.md

@@ -61,6 +61,17 @@ References:
 
 - https://openvpn.net/community-resources/reference-manual-for-openvpn-2-6/#server-options
 
+# Troubleshooting
+
+## OIDC Provider Issues with Refresh Tokens
+
+Some OIDC providers may generate new refresh tokens or behave unexpectedly during non-interactive refresh requests. If you experience issues where refresh tokens are invalidated or users need to re-authenticate frequently, you can adjust the nonce behavior using the `oauth2.refresh-nonce` parameter:
+
+- `auto` (default): Try with nonce, retry without nonce on error
+- `empty`: Always use empty nonce for refresh requests
+- `equal`: Use the same nonce as initial authentication
+
+For providers like Authentik that return empty nonces on refresh (per OIDC spec), use `refresh-nonce: empty` to avoid retry logic that could invalidate refresh tokens.
 
 ## openvpn-auth-oauth2 config
 

internal/config/defaults.go

@@ -81,12 +81,13 @@ var Defaults = Config{
 			Discovery: types.URL{URL: &url.URL{Scheme: "", Host: ""}},
 			Token:     types.URL{URL: &url.URL{Scheme: "", Host: ""}},
 		},
-		Issuer:      types.URL{URL: &url.URL{Scheme: "", Host: ""}},
-		Nonce:       true,
-		PKCE:        true,
-		UserInfo:    false,
-		GroupsClaim: "groups",
-		Provider:    "generic",
+		Issuer:       types.URL{URL: &url.URL{Scheme: "", Host: ""}},
+		Nonce:        true,
+		RefreshNonce: OAuth2RefreshNonceAuto,
+		PKCE:         true,
+		UserInfo:     false,
+		GroupsClaim:  "groups",
+		Provider:     "generic",
 		Refresh: OAuth2Refresh{
 			Expires:      time.Hour * 8,
 			ValidateUser: true,

internal/config/flags.go

@@ -308,6 +308,15 @@ func (c *Config) flagSetOAuth2(flagSet *flag.FlagSet) {
 		lookupEnvOrDefault("oauth2.nonce", c.OAuth2.Nonce),
 		"If true, a nonce will be defined on the auth URL which is expected inside the token.",
 	)
+	flagSet.TextVar(
+		&c.OAuth2.RefreshNonce,
+		"oauth2.refresh-nonce",
+		lookupEnvOrDefault("oauth2.refresh-nonce", c.OAuth2.RefreshNonce),
+		"Controls nonce behavior on refresh token requests. "+
+			"Options: auto (try with nonce, retry without on error), "+
+			"empty (always use empty nonce), "+
+			"equal (use same nonce as initial auth).",
+	)
 	flagSet.TextVar(
 		&c.OAuth2.AuthStyle,
 		"oauth2.auth-style",

internal/config/types.go

@@ -22,8 +22,8 @@ type Config struct {
 	HTTP       HTTP    `json:"http"    yaml:"http"`
 	Debug      Debug   `json:"debug"   yaml:"debug"`
 	Log        Log     `json:"log"     yaml:"log"`
-	OAuth2     OAuth2  `json:"oauth2"  yaml:"oauth2"`
 	OpenVPN    OpenVPN `json:"openvpn" yaml:"openvpn"`
+	OAuth2     OAuth2  `json:"oauth2"  yaml:"oauth2"`
 }
 
 type HTTP struct {
@@ -78,19 +78,20 @@ type OpenVPNCommonName struct {
 }
 
 type OAuth2 struct {
-	Endpoints       OAuth2Endpoints   `json:"endpoint"         yaml:"endpoint"`
-	Issuer          types.URL         `json:"issuer"           yaml:"issuer"`
-	Client          OAuth2Client      `json:"client"           yaml:"client"`
-	GroupsClaim     string            `json:"groups-claim"     yaml:"groups-claim"`
-	AuthorizeParams string            `json:"authorize-params" yaml:"authorize-params"`
-	Provider        string            `json:"provider"         yaml:"provider"`
-	Scopes          types.StringSlice `json:"scopes"           yaml:"scopes"`
-	Validate        OAuth2Validate    `json:"validate"         yaml:"validate"`
-	Refresh         OAuth2Refresh     `json:"refresh"          yaml:"refresh"`
-	AuthStyle       OAuth2AuthStyle   `json:"auth-style"       yaml:"auth-style"`
-	Nonce           bool              `json:"nonce"            yaml:"nonce"`
-	PKCE            bool              `json:"pkce"             yaml:"pkce"`
-	UserInfo        bool              `json:"user-info"        yaml:"user-info"`
+	Endpoints       OAuth2Endpoints    `json:"endpoint"         yaml:"endpoint"`
+	Issuer          types.URL          `json:"issuer"           yaml:"issuer"`
+	Client          OAuth2Client       `json:"client"           yaml:"client"`
+	GroupsClaim     string             `json:"groups-claim"     yaml:"groups-claim"`
+	AuthorizeParams string             `json:"authorize-params" yaml:"authorize-params"`
+	Provider        string             `json:"provider"         yaml:"provider"`
+	Scopes          types.StringSlice  `json:"scopes"           yaml:"scopes"`
+	Validate        OAuth2Validate     `json:"validate"         yaml:"validate"`
+	Refresh         OAuth2Refresh      `json:"refresh"          yaml:"refresh"`
+	AuthStyle       OAuth2AuthStyle    `json:"auth-style"       yaml:"auth-style"`
+	RefreshNonce    OAuth2RefreshNonce `json:"refresh-nonce"    yaml:"refresh-nonce"`
+	Nonce           bool               `json:"nonce"            yaml:"nonce"`
+	PKCE            bool               `json:"pkce"             yaml:"pkce"`
+	UserInfo        bool               `json:"user-info"        yaml:"user-info"`
 }
 
 type OAuth2Client struct {
@@ -243,6 +244,61 @@ func (s *OAuth2AuthStyle) UnmarshalText(text []byte) error {
 	return nil
 }
 
+type OAuth2RefreshNonce int
+
+const (
+	OAuth2RefreshNonceAuto OAuth2RefreshNonce = iota
+	OAuth2RefreshNonceEmpty
+	OAuth2RefreshNonceEqual
+)
+
+// String returns the string representation of the refresh nonce mode.
+//
+//goland:noinspection GoMixedReceiverTypes
+func (s OAuth2RefreshNonce) String() string {
+	text, err := s.MarshalText()
+	if err != nil {
+		panic(err)
+	}
+
+	return string(text)
+}
+
+// MarshalText implements the [encoding.TextMarshaler] interface.
+//
+//goland:noinspection GoMixedReceiverTypes
+func (s OAuth2RefreshNonce) MarshalText() ([]byte, error) {
+	switch s {
+	case OAuth2RefreshNonceAuto:
+		return []byte("auto"), nil
+	case OAuth2RefreshNonceEmpty:
+		return []byte("empty"), nil
+	case OAuth2RefreshNonceEqual:
+		return []byte("equal"), nil
+	default:
+		return nil, fmt.Errorf("unknown refresh-nonce %d", s)
+	}
+}
+
+// UnmarshalText implements the [encoding.TextUnmarshaler] interface.
+//
+//goland:noinspection GoMixedReceiverTypes
+func (s *OAuth2RefreshNonce) UnmarshalText(text []byte) error {
+	config := strings.ToLower(string(text))
+	switch config {
+	case "auto":
+		*s = OAuth2RefreshNonceAuto
+	case "empty":
+		*s = OAuth2RefreshNonceEmpty
+	case "equal":
+		*s = OAuth2RefreshNonceEqual
+	default:
+		return fmt.Errorf("invalid value %s", config)
+	}
+
+	return nil
+}
+
 //goland:noinspection GoMixedReceiverTypes
 func (c Config) String() string {
 	jsonString, err := json.Marshal(c)

internal/config/types_test.go

@@ -112,3 +112,53 @@ func TestOAuth2AuthStyleGetAuthStyle(t *testing.T) {
 	oAuth2AuthStyle = config.OAuth2AuthStyle(oauth2.AuthStyleAutoDetect).AuthStyle()
 	assert.Equal(t, oauth2.AuthStyleAutoDetect, oAuth2AuthStyle)
 }
+
+func TestOAuth2RefreshNonceUnmarshalText(t *testing.T) {
+	t.Parallel()
+
+	var refreshNonce config.OAuth2RefreshNonce
+
+	require.NoError(t, refreshNonce.UnmarshalText([]byte("auto")))
+	assert.Equal(t, config.OAuth2RefreshNonceAuto, refreshNonce)
+
+	require.NoError(t, refreshNonce.UnmarshalText([]byte("empty")))
+	assert.Equal(t, config.OAuth2RefreshNonceEmpty, refreshNonce)
+
+	require.NoError(t, refreshNonce.UnmarshalText([]byte("equal")))
+	assert.Equal(t, config.OAuth2RefreshNonceEqual, refreshNonce)
+
+	require.Error(t, refreshNonce.UnmarshalText([]byte("unknown")))
+}
+
+func TestOAuth2RefreshNonceMarshalText(t *testing.T) {
+	t.Parallel()
+
+	refreshNonce, err := config.OAuth2RefreshNonceAuto.MarshalText()
+
+	require.NoError(t, err)
+	assert.Equal(t, []byte("auto"), refreshNonce)
+
+	refreshNonce, err = config.OAuth2RefreshNonceEmpty.MarshalText()
+
+	require.NoError(t, err)
+	assert.Equal(t, []byte("empty"), refreshNonce)
+
+	refreshNonce, err = config.OAuth2RefreshNonceEqual.MarshalText()
+
+	require.NoError(t, err)
+	assert.Equal(t, []byte("equal"), refreshNonce)
+
+	_, err = config.OAuth2RefreshNonce(-1).MarshalText()
+
+	require.Error(t, err)
+}
+
+func TestOAuth2RefreshNonceString(t *testing.T) {
+	t.Parallel()
+
+	assert.Equal(t, "auto", config.OAuth2RefreshNonceAuto.String())
+	assert.Equal(t, "empty", config.OAuth2RefreshNonceEmpty.String())
+	assert.Equal(t, "equal", config.OAuth2RefreshNonceEqual.String())
+
+	assert.Panics(t, func() { _ = config.OAuth2RefreshNonce(-1).String() }, "The code did not panic")
+}

internal/oauth2/providers/generic/oidc.go

@@ -6,6 +6,7 @@ import (
 	"fmt"
 	"log/slog"
 
+	"github.com/jkroepke/openvpn-auth-oauth2/internal/config"
 	"github.com/jkroepke/openvpn-auth-oauth2/internal/oauth2"
 	"github.com/jkroepke/openvpn-auth-oauth2/internal/oauth2/idtoken"
 	"github.com/jkroepke/openvpn-auth-oauth2/internal/oauth2/types"
@@ -30,14 +31,28 @@ func (p Provider) GetRefreshToken(tokens idtoken.IDToken) (string, error) {
 func (p Provider) Refresh(ctx context.Context, logger *slog.Logger, relyingParty rp.RelyingParty, refreshToken string) (idtoken.IDToken, error) {
 	ctx = logging.ToContext(ctx, logger)
 
+	// Apply refresh nonce control based on configuration
+	switch p.Conf.OAuth2.RefreshNonce {
+	case config.OAuth2RefreshNonceEmpty:
+		// Always use empty nonce for refresh requests
+		ctx = context.WithValue(ctx, types.CtxNonce{}, "")
+	case config.OAuth2RefreshNonceEqual:
+		// Use the same nonce as initial authentication (default behavior)
+		// No additional action needed - relies on the nonce set by calling code
+	case config.OAuth2RefreshNonceAuto:
+		// Fallback to original behavior: try with nonce, retry without on error
+	}
+
 	tokens, err := rp.RefreshTokens[*idtoken.Claims](ctx, relyingParty, refreshToken, "", "")
-	// OIDC spec says that nonce is optional for refresh tokens
-	// https://openid.net/specs/openid-connect-core-1_0.html#RefreshTokens
-	// This means that we have to retry the refresh without a nonce if we get an error,
-	// However, trying to refresh session with the same refresh token could lead into an error
-	// because refresh token may have a one time use policy
-	// see: https://github.com/zitadel/oidc/issues/509
-	if errors.Is(err, oidc.ErrNonceInvalid) {
+
+	// Only retry for auto mode when we get a nonce error
+	if p.Conf.OAuth2.RefreshNonce == config.OAuth2RefreshNonceAuto && errors.Is(err, oidc.ErrNonceInvalid) {
+		// OIDC spec says that nonce is optional for refresh tokens
+		// https://openid.net/specs/openid-connect-core-1_0.html#RefreshTokens
+		// This means that we have to retry the refresh without a nonce if we get an error,
+		// However, trying to refresh session with the same refresh token could lead into an error
+		// because refresh token may have a one time use policy
+		// see: https://github.com/zitadel/oidc/issues/509
 		ctx = context.WithValue(ctx, types.CtxNonce{}, "")
 		tokens, err = rp.RefreshTokens[*idtoken.Claims](ctx, relyingParty, refreshToken, "", "")
 	}

internal/oauth2/types/errors.go

@@ -4,6 +4,4 @@ import (
 	"errors"
 )
 
-var (
-	ErrInvalidClaimType = errors.New("invalid claim type")
-)
+var ErrInvalidClaimType = errors.New("invalid claim type")

internal/utils/testutils/main.go

@@ -285,7 +285,8 @@ func SetupMockEnvironment(ctx context.Context, tb testing.TB, conf config.Config
 	}
 
 	conf.OAuth2.Issuer = resourceServerURL
-	conf.OAuth2.Nonce = false // not supported by the mock
+	conf.OAuth2.Nonce = true                                  // enable nonce for mock testing
+	conf.OAuth2.RefreshNonce = config.OAuth2RefreshNonceEmpty // use empty nonce for refresh to avoid mock issues
 
 	if conf.OAuth2.Client.ID == "" {
 		conf.OAuth2.Client.ID = clientCredentials.ID

packaging/etc/openvpn-auth-oauth2/config.yaml

@@ -50,6 +50,7 @@
 #    ipaddr: false
 #    issuer: true
 #  nonce: true
+#  refresh-nonce: "auto"  # Options: auto (try with nonce, retry without on error), empty (always use empty nonce for refresh), equal (use same nonce as initial auth)
 #  pkce: true
 #  refresh:
 #    enabled: false