fix!: allow expires to be an integer wrapped in a string value (#821)

Certain providers, for example Entra ID, return durations as quoted
strings instead of JSON numbers. This is a deviation from the standard.
This change allows for the successful parsing of such quoted duration
strings.

BREAKING CHANGE: The `expires_in field` has changed from type `int64` to
`oidc.Duration` for various token response payloads.

fixes #815

### Definition of Ready

- [x] I am happy with the code
- [x] Short description of the feature/issue is added in the pr
description
- [x] PR is linked to the corresponding user story
- [x] Acceptance criteria are met
- [x] All open todos and follow ups are defined in a new ticket and
justified
- [ ] Deviations from the acceptance criteria and design are agreed with
the PO and documented.
- [x] No debug or dead code
- [x] My code has no repetitions
- [x] Critical parts are tested automatically
- [ ] Where possible E2E tests are implemented
- [ ] Documentation/examples are up-to-date
- [ ] All non-functional requirements are met
- [ ] Functionality of the acceptance criteria is checked manually on
the dev system.

Author: wim07101993

UPGRADING.md

@@ -5,6 +5,36 @@ All commands are executed from the root of the project that imports oidc package
 on non-GNU systems, such as MacOS.
 Alternatively, GNU sed can be installed on such systems. (`coreutils` package?).
 
+## V3 to V4
+
+### oidc
+
+#### `exp` claim in `AccessTokenResponse` and `TokenExchangeResponse`
+
+The type of the `ExpiresIn` field has been changed from an `int64` to an `oidc.Duration` type. 
+Unfortunately this upgrade cannot be described in a sed command and has to be done manually.
+
+Example:
+```go
+validity := 30 * time.Seconds
+oidc.AccessTokenResponse{
+    AccessToken: accessToken,
+    TokenType:   oidc.BearerToken,
+    ExpiresIn:   uint64(validity.Seconds()),
+    Scope:       tokenRequest.GetScopes(),
+}
+```
+becomes
+```go
+validity := 30 * time.Seconds
+oidc.AccessTokenResponse{
+    AccessToken: accessToken,
+    TokenType:   oidc.BearerToken,
+    ExpiresIn:   oidc.Duration(validity),
+    Scope:       tokenRequest.GetScopes(),
+}
+```
+
 ## V2 to V3
 
 **TL;DR** at the [bottom](#full-script) of this chapter is a full `sed` script

pkg/oidc/token.go

@@ -233,7 +233,7 @@ type AccessTokenResponse struct {
 	AccessToken  string              `json:"access_token,omitempty" schema:"access_token,omitempty"`
 	TokenType    string              `json:"token_type,omitempty" schema:"token_type,omitempty"`
 	RefreshToken string              `json:"refresh_token,omitempty" schema:"refresh_token,omitempty"`
-	ExpiresIn    uint64              `json:"expires_in,omitempty" schema:"expires_in,omitempty"`
+	ExpiresIn    Duration            `json:"expires_in,omitempty" schema:"expires_in,omitempty"`
 	IDToken      string              `json:"id_token,omitempty" schema:"id_token,omitempty"`
 	State        string              `json:"state,omitempty" schema:"state,omitempty"`
 	Scope        SpaceDelimitedArray `json:"scope,omitempty" schema:"scope,omitempty"`
@@ -375,7 +375,7 @@ type TokenExchangeResponse struct {
 	AccessToken     string              `json:"access_token"` // Can be access token or ID token
 	IssuedTokenType TokenType           `json:"issued_token_type"`
 	TokenType       string              `json:"token_type"`
-	ExpiresIn       uint64              `json:"expires_in,omitempty"`
+	ExpiresIn       Duration            `json:"expires_in,omitempty"`
 	Scopes          SpaceDelimitedArray `json:"scope,omitempty"`
 	RefreshToken    string              `json:"refresh_token,omitempty"`
 

pkg/oidc/token_test.go

@@ -1,6 +1,7 @@
 package oidc
 
 import (
+	"encoding/json"
 	"testing"
 	"time"
 
@@ -278,3 +279,174 @@ func TestNewLogoutTokenClaims(t *testing.T) {
 
 	assert.Equal(t, want, got)
 }
+
+func TestTokenExchangeResponse_UnmarshalJSON(t *testing.T) {
+	testCases := []struct {
+		marshaled string
+		want      TokenExchangeResponse
+	}{
+		{
+			marshaled: `
+            {
+                "access_token":"access_token",
+                "issued_token_type":"test_token",
+                "token_type":"test_token",
+                "expires_in":12345,
+	        	"scope": "lorem ipsum",
+	        	"refresh_token": "refresh_token",
+	        	"id_token": "id_token"
+            }`,
+			want: TokenExchangeResponse{
+				AccessToken:     "access_token",
+				IssuedTokenType: "test_token",
+				TokenType:       "test_token",
+				ExpiresIn:       Duration(12345 * time.Second),
+				Scopes:          []string{"lorem", "ipsum"},
+				RefreshToken:    "refresh_token",
+				IDToken:         "id_token",
+			},
+		},
+		{
+			marshaled: `
+            {
+                "access_token":"access_token",
+                "issued_token_type":"test_token",
+                "token_type":"test_token",
+                "expires_in":"12345",
+	        	"scope": "lorem ipsum",
+	        	"refresh_token": "refresh_token",
+	        	"id_token": "id_token"
+            }`,
+			want: TokenExchangeResponse{
+				AccessToken:     "access_token",
+				IssuedTokenType: "test_token",
+				TokenType:       "test_token",
+				ExpiresIn:       Duration(12345 * time.Second),
+				Scopes:          []string{"lorem", "ipsum"},
+				RefreshToken:    "refresh_token",
+				IDToken:         "id_token",
+			},
+		},
+	}
+	for _, testCase := range testCases {
+		got := &TokenExchangeResponse{}
+		err := json.Unmarshal([]byte(testCase.marshaled), got)
+		assert.Equal(t, nil, err)
+		assert.Equal(t, testCase.want.AccessToken, got.AccessToken)
+		assert.Equal(t, testCase.want.IssuedTokenType, got.IssuedTokenType)
+		assert.Equal(t, testCase.want.TokenType, got.TokenType)
+		assert.Equal(t, testCase.want.ExpiresIn, got.ExpiresIn)
+		assert.Equal(t, testCase.want.Scopes, got.Scopes)
+		assert.Equal(t, testCase.want.RefreshToken, got.RefreshToken)
+		assert.Equal(t, testCase.want.IDToken, got.IDToken)
+	}
+}
+func TestTokenExchangeResponse_MarshalJSON(t *testing.T) {
+	testCases := []struct {
+		want        string
+		unmarshaled TokenExchangeResponse
+	}{
+		{
+			want: `{"access_token":"access_token","issued_token_type":"test_token","token_type":"test_token","expires_in":12345,"scope":"lorem ipsum","refresh_token":"refresh_token","id_token":"id_token"}`,
+			unmarshaled: TokenExchangeResponse{
+				AccessToken:     "access_token",
+				IssuedTokenType: "test_token",
+				TokenType:       "test_token",
+				ExpiresIn:       Duration(12345 * time.Second),
+				Scopes:          []string{"lorem", "ipsum"},
+				RefreshToken:    "refresh_token",
+				IDToken:         "id_token",
+			},
+		},
+	}
+	for _, testCase := range testCases {
+		got, err := json.Marshal(testCase.unmarshaled)
+		assert.Equal(t, nil, err)
+		assert.Equal(t, testCase.want, string(got))
+	}
+}
+func TestAccessTokenResponse_UnmarshalJSON(t *testing.T) {
+	testCases := []struct {
+		marshaled string
+		want      AccessTokenResponse
+	}{
+		{
+			marshaled: `
+            {
+                "access_token":"access_token",
+                "token_type":"test_token",
+	        	"refresh_token": "refresh_token",
+                "expires_in":12345,
+	        	"id_token": "id_token",
+                "state": "state",
+	        	"scope": "lorem ipsum"
+            }`,
+			want: AccessTokenResponse{
+				AccessToken:  "access_token",
+				TokenType:    "test_token",
+				RefreshToken: "refresh_token",
+				ExpiresIn:    Duration(12345 * time.Second),
+				IDToken:      "id_token",
+				State:        "state",
+				Scope:        []string{"lorem", "ipsum"},
+			},
+		},
+		{
+			marshaled: `
+            {
+                "access_token":"access_token",
+                "token_type":"test_token",
+	        	"refresh_token": "refresh_token",
+                "expires_in":"12345",
+	        	"id_token": "id_token",
+				"state": "state",
+	        	"scope": "lorem ipsum"
+            }`,
+			want: AccessTokenResponse{
+				AccessToken:  "access_token",
+				TokenType:    "test_token",
+				RefreshToken: "refresh_token",
+				ExpiresIn:    Duration(12345 * time.Second),
+				IDToken:      "id_token",
+				State:        "state",
+				Scope:        []string{"lorem", "ipsum"},
+			},
+		},
+	}
+	for _, testCase := range testCases {
+		got := &AccessTokenResponse{}
+		err := json.Unmarshal([]byte(testCase.marshaled), got)
+		assert.Equal(t, nil, err)
+		assert.Equal(t, testCase.want.AccessToken, got.AccessToken)
+		assert.Equal(t, testCase.want.TokenType, got.TokenType)
+		assert.Equal(t, testCase.want.RefreshToken, got.RefreshToken)
+		assert.Equal(t, testCase.want.ExpiresIn, got.ExpiresIn)
+		assert.Equal(t, testCase.want.IDToken, got.IDToken)
+		assert.Equal(t, testCase.want.State, got.State)
+		assert.Equal(t, testCase.want.Scope, got.Scope)
+	}
+}
+func TestAccessTokenResponse_MarshalJSON(t *testing.T) {
+	testCases := []struct {
+		want        string
+		unmarshaled AccessTokenResponse
+	}{
+		{
+			want: `{"access_token":"access_token","token_type":"test_token","refresh_token":"refresh_token","expires_in":12345,"id_token":"id_token","state":"state","scope":"lorem ipsum"}`,
+			unmarshaled: AccessTokenResponse{
+				AccessToken:  "access_token",
+				TokenType:    "test_token",
+				RefreshToken: "refresh_token",
+				ExpiresIn:    Duration(12345 * time.Second),
+				IDToken:      "id_token",
+				State:        "state",
+				Scope:        []string{"lorem", "ipsum"},
+			},
+		},
+	}
+	for _, testCase := range testCases {
+		got, err := json.Marshal(testCase.unmarshaled)
+		assert.Equal(t, nil, err)
+		assert.Equal(t, testCase.want, string(got))
+	}
+}

pkg/oidc/types.go

@@ -5,7 +5,9 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"math"
 	"reflect"
+	"strconv"
 	"strings"
 	"time"
 
@@ -300,3 +302,47 @@ func (r *RequestObject) GetIssuer() string {
 }
 
 func (*RequestObject) SetSignatureAlgorithm(algorithm jose.SignatureAlgorithm) {}
+
+type Duration time.Duration
+
+func (d Duration) AsDuration() time.Duration {
+	return time.Duration(d)
+}
+
+func (d *Duration) UnmarshalJSON(data []byte) error {
+	var v any
+	if err := json.Unmarshal(data, &v); err != nil {
+		return fmt.Errorf("oidc.Duration: %w", err)
+	}
+	switch x := v.(type) {
+	case int64:
+		*d = Duration(time.Second * time.Duration(x))
+	case float64:
+		mod := math.Mod(x, 1)
+		if mod > 0 {
+			return fmt.Errorf("oidc.Duration: unable to parse type %T with value %v", x, x)
+		}
+		*d = Duration(time.Second * time.Duration(x))
+	case string:
+		// Compatibility with EntraID:
+		// https://github.com/zitadel/oidc/issues/815
+		i, err := strconv.Atoi(x)
+		if err != nil {
+			return fmt.Errorf("oidc.Duration: %w", err)
+		}
+		*d = Duration(time.Second * time.Duration(i))
+	case nil:
+		*d = 0
+	default:
+		return fmt.Errorf("oidc.Duration: unable to parse type %T with value %v", x, x)
+	}
+	if *d < 0 {
+		return fmt.Errorf("oidc.Duration: cannot be a negative time (%v)", *d)
+	}
+	return nil
+}
+
+func (d Duration) MarshalJSON() ([]byte, error) {
+	s := int64(d.AsDuration().Seconds())
+	return []byte(strconv.FormatInt(s, 10)), nil
+}

pkg/op/device.go

@@ -343,7 +343,7 @@ func CreateDeviceTokenResponse(ctx context.Context, tokenRequest TokenRequest, c
 		AccessToken:  accessToken,
 		RefreshToken: refreshToken,
 		TokenType:    oidc.BearerToken,
-		ExpiresIn:    uint64(validity.Seconds()),
+		ExpiresIn:    oidc.Duration(validity),
 		Scope:        tokenRequest.GetScopes(),
 	}
 

pkg/op/device_test.go

@@ -523,7 +523,7 @@ func TestCreateDeviceTokenResponse(t *testing.T) {
 				return
 			}
 			require.NoError(t, err)
-			assert.InDelta(t, 300, got.ExpiresIn, 2)
+			assert.InDelta(t, 300, got.ExpiresIn.AsDuration().Seconds(), 2)
 			if tt.wantAccessToken {
 				assert.NotEmpty(t, got.AccessToken, "access token")
 			}

pkg/op/token.go

@@ -57,7 +57,7 @@ func CreateTokenResponse(ctx context.Context, request IDTokenRequest, client Cli
 		}
 	}
 
-	exp := uint64(validity.Seconds())
+	exp := oidc.Duration(validity)
 	return &oidc.AccessTokenResponse{
 		AccessToken:  accessToken,
 		IDToken:      idToken,

pkg/op/token_client_credentials.go

@@ -119,7 +119,7 @@ func CreateClientCredentialsTokenResponse(ctx context.Context, tokenRequest Toke
 	return &oidc.AccessTokenResponse{
 		AccessToken: accessToken,
 		TokenType:   oidc.BearerToken,
-		ExpiresIn:   uint64(validity.Seconds()),
+		ExpiresIn:   oidc.Duration(validity),
 		Scope:       tokenRequest.GetScopes(),
 	}, nil
 }

pkg/op/token_exchange.go

@@ -402,12 +402,11 @@ func CreateTokenExchangeResponse(
 		oidc.ErrInvalidRequest().WithDescription("requested_token_type is invalid")
 	}
 
-	exp := uint64(validity.Seconds())
 	return &oidc.TokenExchangeResponse{
 		AccessToken:     token,
 		IssuedTokenType: tokenExchangeRequest.GetRequestedTokenType(),
 		TokenType:       tokenType,
-		ExpiresIn:       exp,
+		ExpiresIn:       oidc.Duration(validity),
 		RefreshToken:    refreshToken,
 		Scopes:          tokenExchangeRequest.GetScopes(),
 	}, nil

pkg/op/token_jwt_profile.go

@@ -88,7 +88,7 @@ func CreateJWTTokenResponse(ctx context.Context, tokenRequest TokenRequest, crea
 	return &oidc.AccessTokenResponse{
 		AccessToken: accessToken,
 		TokenType:   oidc.BearerToken,
-		ExpiresIn:   uint64(validity.Seconds()),
+		ExpiresIn:   oidc.Duration(validity),
 		Scope:       tokenRequest.GetScopes(),
 	}, nil
 }