fix: consistently handle string-valued boolean fields from non-compliant OIDC providers (#791)

AWS Cognito (and potentially other providers) return `email_verified`
and `phone_number_verified` as strings (`"true"`/`"false"`) instead of
proper JSON booleans, violating the [OIDC
specification](https://openid.net/specs/openid-connect-basic-1_0.html#StandardClaims).

AWS Documentation confirms this:
> Currently, Amazon Cognito returns the values for email_verified and
phone_number_verified as strings.

_Source:
https://docs.aws.amazon.com/cognito/latest/developerguide/userinfo-endpoint.html#get-userinfo-response-sample_

### The Problem

The `zitadel/oidc` library currently handles this inconsistently:
  - ✅ `EmailVerified` uses the custom `Bool` type (added in #139)
  - ❌ `PhoneNumberVerified` uses Go's standard `bool`
  
This forces developers to handle semantically identical fields
differently:

```go
// Currently inconsistent code path
userInfo.EmailVerified = oidc.Bool(emailValue)    // Cast
userInfo.PhoneNumberVerified = phoneValue      // No cast
```

Additionally, the existing `Bool.UnmarshalJSON` implementation meant
that false values couldn't overwrite true.

### Solution

Applied `Bool` type consistently to both fields and simplified
`Bool.UnmarshalJSON` using a direct switch statement to:

  - Handle standard JSON booleans (true/false)
  - Handle AWS Cognito string format ("true"/"false")
  - Return errors on invalid input instead of silently failing
  - Allow false to overwrite true

 Updated tests to match codebase conventions, as well.

 ### Impact

`PhoneNumberVerified` changes from `bool` to `Bool` (type alias of
`bool`). Most consumer code should work as-is since `Bool` is just a
type alias. Direct type assertions would need updating.

### Definition of Ready

- [X] I am happy with the code
- [X] Short description of the feature/issue is added in the pr
description
- [ ] PR is linked to the corresponding user story
- [X] Acceptance criteria are met
- [ ] 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
- [x] Where possible E2E tests are implemented
- [X] Documentation/examples are up-to-date
- [ ] All non-functional requirements are met
- [x] Functionality of the acceptance criteria is checked manually on
the dev system.

Co-authored-by: Wim Van Laer <[email protected]>

Author: bashhack

example/server/storage/storage.go

@@ -676,7 +676,7 @@ func (s *Storage) setUserinfo(ctx context.Context, userInfo *oidc.UserInfo, user
 			userInfo.Locale = oidc.NewLocale(user.PreferredLanguage)
 		case oidc.ScopePhone:
 			userInfo.PhoneNumber = user.Phone
-			userInfo.PhoneNumberVerified = user.PhoneVerified
+			userInfo.PhoneNumberVerified = oidc.Bool(user.PhoneVerified)
 		case CustomScope:
 			// you can also have a custom scope and assert public or custom claims based on that
 			userInfo.AppendClaims(CustomClaim, customClaim(clientID))

pkg/oidc/userinfo.go

@@ -1,5 +1,35 @@
 package oidc
 
+import (
+	"fmt"
+)
+
+type Bool bool
+
+// UnmarshalJSON handles both standard JSON boolean values and string representations.
+// This is necessary because some OIDC providers (notably AWS Cognito) incorrectly return
+// boolean fields like email_verified and phone_number_verified as strings ("true"/"false")
+// instead of proper JSON booleans, violating the OIDC specification.
+//
+// The method first attempts standard boolean unmarshaling, and falls back to string
+// parsing if that fails, making it compatible with both compliant and non-compliant providers.
+//
+// Ref:
+// - https://openid.net/specs/openid-connect-basic-1_0.html#StandardClaims
+// - https://docs.aws.amazon.com/cognito/latest/developerguide/userinfo-endpoint.html
+func (bs *Bool) UnmarshalJSON(data []byte) error {
+	s := string(data)
+	switch s {
+	case "true", `"true"`:
+		*bs = true
+	case "false", `"false"`:
+		*bs = false
+	default:
+		return fmt.Errorf("cannot unmarshal %s into Bool", s)
+	}
+	return nil
+}
+
 // UserInfo implements OpenID Connect Core 1.0, section 5.1.
 // https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims.
 type UserInfo struct {
@@ -64,25 +94,12 @@ type UserInfoProfile struct {
 type UserInfoEmail struct {
 	Email string `json:"email,omitempty"`
 
-	// Handle providers that return email_verified as a string
-	// https://forums.aws.amazon.com/thread.jspa?messageID=949441&#949441
-	// https://discuss.elastic.co/t/openid-error-after-authenticating-against-aws-cognito/206018/11
 	EmailVerified Bool `json:"email_verified,omitempty"`
 }
 
-type Bool bool
-
-func (bs *Bool) UnmarshalJSON(data []byte) error {
-	if string(data) == "true" || string(data) == `"true"` {
-		*bs = true
-	}
-
-	return nil
-}
-
 type UserInfoPhone struct {
 	PhoneNumber         string `json:"phone_number,omitempty"`
-	PhoneNumberVerified bool   `json:"phone_number_verified,omitempty"`
+	PhoneNumberVerified Bool   `json:"phone_number_verified,omitempty"`
 }
 
 type UserInfoAddress struct {

pkg/oidc/userinfo_test.go

@@ -62,58 +62,112 @@ func TestUserInfoMarshal(t *testing.T) {
 	assert.Equal(t, out, out2)
 }
 
-func TestUserInfoEmailVerifiedUnmarshal(t *testing.T) {
+// TestUserInfoVerifiedFieldsUnmarshal ensures email_verified and phone_number_verified
+// handle both standard booleans and AWS Cognito's non-compliant strings.
+func TestUserInfoVerifiedFieldsUnmarshal(t *testing.T) {
 	t.Parallel()
 
-	t.Run("unmarshal email_verified from json bool true", func(t *testing.T) {
-		jsonBool := []byte(`{"email": "[email protected]", "email_verified": true}`)
-
-		var uie UserInfoEmail
+	tests := []struct {
+		name              string
+		json              string
+		wantEmailVerified Bool
+		wantPhoneVerified Bool
+	}{
+		{
+			name:              "booleans true",
+			json:              `{"email_verified": true, "phone_number_verified": true}`,
+			wantEmailVerified: true,
+			wantPhoneVerified: true,
+		},
+		{
+			name:              "booleans false",
+			json:              `{"email_verified": false, "phone_number_verified": false}`,
+			wantEmailVerified: false,
+			wantPhoneVerified: false,
+		},
+		{
+			name:              "strings true",
+			json:              `{"email_verified": "true", "phone_number_verified": "true"}`,
+			wantEmailVerified: true,
+			wantPhoneVerified: true,
+		},
+		{
+			name:              "strings false",
+			json:              `{"email_verified": "false", "phone_number_verified": "false"}`,
+			wantEmailVerified: false,
+			wantPhoneVerified: false,
+		},
+		{
+			name:              "mixed bool/string",
+			json:              `{"email_verified": true, "phone_number_verified": "false"}`,
+			wantEmailVerified: true,
+			wantPhoneVerified: false,
+		},
+	}
 
-		err := json.Unmarshal(jsonBool, &uie)
-		assert.NoError(t, err)
-		assert.Equal(t, UserInfoEmail{
-			Email:         "[email protected]",
-			EmailVerified: true,
-		}, uie)
-	})
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			var got UserInfo
+			err := json.Unmarshal([]byte(tt.json), &got)
+			assert.NoError(t, err)
+			assert.Equal(t, tt.wantEmailVerified, got.EmailVerified)
+			assert.Equal(t, tt.wantPhoneVerified, got.PhoneNumberVerified)
+		})
+	}
+}
 
-	t.Run("unmarshal email_verified from json string true", func(t *testing.T) {
-		jsonBool := []byte(`{"email": "[email protected]", "email_verified": "true"}`)
+// TestBoolUnmarshal verifies the Bool type handles various inputs correctly.
+func TestBoolUnmarshal(t *testing.T) {
+	t.Parallel()
 
-		var uie UserInfoEmail
+	tests := []struct {
+		name    string
+		input   string
+		want    Bool
+		wantErr bool
+	}{
+		{
+			name:  "bool true",
+			input: `true`,
+			want:  true,
+		},
+		{
+			name:  "bool false",
+			input: `false`,
+			want:  false,
+		},
+		{
+			name:  "string true",
+			input: `"true"`,
+			want:  true,
+		},
+		{
+			name:  "string false",
+			input: `"false"`,
+			want:  false,
+		},
+		{
+			name:    "invalid string",
+			input:   `"yes"`,
+			wantErr: true,
+		},
+		{
+			name:    "number",
+			input:   `1`,
+			wantErr: true,
+		},
+	}
 
-		err := json.Unmarshal(jsonBool, &uie)
-		assert.NoError(t, err)
-		assert.Equal(t, UserInfoEmail{
-			Email:         "[email protected]",
-			EmailVerified: true,
-		}, uie)
-	})
-
-	t.Run("unmarshal email_verified from json bool false", func(t *testing.T) {
-		jsonBool := []byte(`{"email": "[email protected]", "email_verified": false}`)
-
-		var uie UserInfoEmail
-
-		err := json.Unmarshal(jsonBool, &uie)
-		assert.NoError(t, err)
-		assert.Equal(t, UserInfoEmail{
-			Email:         "[email protected]",
-			EmailVerified: false,
-		}, uie)
-	})
-
-	t.Run("unmarshal email_verified from json string false", func(t *testing.T) {
-		jsonBool := []byte(`{"email": "[email protected]", "email_verified": "false"}`)
-
-		var uie UserInfoEmail
-
-		err := json.Unmarshal(jsonBool, &uie)
-		assert.NoError(t, err)
-		assert.Equal(t, UserInfoEmail{
-			Email:         "[email protected]",
-			EmailVerified: false,
-		}, uie)
-	})
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			var got Bool
+			err := json.Unmarshal([]byte(tt.input), &got)
+			if tt.wantErr {
+				assert.Error(t, err)
+				return
+			}
+			assert.NoError(t, err)
+			assert.Equal(t, tt.want, got)
+		})
+	}
 }