WPB-24006 rename validate sam lemails to require external email verification and deprecate legacy feature flag endpoint (#5118)

Author: battermann

changelog.d/4-docs/WPB-24006

@@ -0,0 +1 @@
+Updated docs for the team feature `validateSAMLemails`

docs/src/developer/reference/config-options.md

@@ -288,15 +288,17 @@ The lock status for individual teams can be changed via the internal API (`PUT /
 
 The feature status for individual teams can be changed via the public API (if the feature is unlocked).
 
-### Validate SAML Emails
+### Require External Email Verification
 
-The feature only affects email address changes originating from SCIM or SAML.  Personal users and team users provisioned through the team management app will *always* be validated.
+The external feature name `validateSAMLemails` is kept for backward compatibility, but it is misleading: the feature applies to email addresses originating from both SCIM and SAML, and it controls ownership verification rather than generic email validation.
 
-`enabled` means "user has authority over email address": if a new user account with an email address is created, the user behind the account will receive a validation email.  If they follow the validation procedure, they will be able to receive emails about their account, eg., if a new device is associated with the account.  If the user does not validate their email address, they can still use it to login.
+The feature only affects email address changes originating from SCIM or SAML. Personal users and team users provisioned through the team management app will *always* go through email verification.
 
-`disabled` means "team admin has authority over email address, and by extension over all member accounts": if a user account with an email address is created, the address is considered valid immediately, without any emails being sent out, and without confirmation from the recipient.
+`enabled` means "user has authority over email address": if a new user account with an email address is created, the user behind the account will receive a verification email. If they complete the verification flow, they will be able to receive emails about their account, eg., if a new device is associated with the account. If they do not verify their email address, they can still use it to log in.
 
-Validate SAML emails is enabled by default.  To disable, use the following syntax:
+`disabled` means "team admin has authority over email address, and by extension over all member accounts": if a user account with an email address is created, the address is auto-activated immediately, without any verification email being sent and without confirmation from the recipient. The user can still receive later account notifications on that address, eg., if a new device is associated with the account.
+
+This feature is enabled by default. To disable it, use the following syntax:
 
 ```yaml
 # galley.yaml

integration/integration.cabal

@@ -158,6 +158,7 @@ library
     Test.FeatureFlags.MlsE2EId
     Test.FeatureFlags.MlsMigration
     Test.FeatureFlags.OutlookCalIntegration
+    Test.FeatureFlags.RequireExternalEmailVerification
     Test.FeatureFlags.SearchVisibilityAvailable
     Test.FeatureFlags.SearchVisibilityInbound
     Test.FeatureFlags.SelfDeletingMessages
@@ -167,7 +168,6 @@ library
     Test.FeatureFlags.StealthUsers
     Test.FeatureFlags.User
     Test.FeatureFlags.Util
-    Test.FeatureFlags.ValidateSAMLEmails
     Test.Federation
     Test.Federator
     Test.LegalHold

…/Test/FeatureFlags/ValidateSAMLEmails.hs …lags/RequireExternalEmailVerification.hsintegration/test/Test/FeatureFlags/ValidateSAMLEmails.hs renamed to integration/test/Test/FeatureFlags/RequireExternalEmailVerification.hs integration/test/Test/FeatureFlags/ValidateSAMLEmails.hs renamed to integration/test/Test/FeatureFlags/RequireExternalEmailVerification.hs

@@ -15,19 +15,19 @@
 -- You should have received a copy of the GNU Affero General Public License along
 -- with this program. If not, see <https://www.gnu.org/licenses/>.
 
-module Test.FeatureFlags.ValidateSAMLEmails where
+module Test.FeatureFlags.RequireExternalEmailVerification where
 
 import SetupHelpers
 import Test.FeatureFlags.Util
 import Testlib.Prelude
 
-testPatchValidateSAMLEmails :: (HasCallStack) => App ()
-testPatchValidateSAMLEmails =
+testPatchRequireExternalEmailVerification :: (HasCallStack) => App ()
+testPatchRequireExternalEmailVerification =
   checkPatch OwnDomain "validateSAMLemails"
     $ object ["status" .= "disabled"]
 
-testValidateSAMLEmailsInternal :: (HasCallStack) => App ()
-testValidateSAMLEmailsInternal = do
+testRequireExternalEmailVerification :: (HasCallStack) => App ()
+testRequireExternalEmailVerification = do
   (alice, tid, _) <- createTeam OwnDomain 0
   withWebSocket alice $ \ws -> do
     setFlag InternalAPI ws tid "validateSAMLemails" disabled

integration/test/Test/Spar.hs

@@ -887,12 +887,12 @@ testSsoLoginAndEmailVerification = do
     user %. "email" `shouldMatch` email
 
 -- | This test may be covered by `testScimUpdateEmailAddress` and maybe can be removed.
-testSsoLoginNoSamlEmailValidation :: (HasCallStack) => TaggedBool "validateSAMLEmails" -> App ()
-testSsoLoginNoSamlEmailValidation (TaggedBool validateSAMLEmails) = do
+testSsoLoginNoSamlEmailValidation :: (HasCallStack) => TaggedBool "requireExternalEmailVerification" -> App ()
+testSsoLoginNoSamlEmailValidation (TaggedBool requireExternalEmailVerification) = do
   (owner, tid, _) <- createTeam OwnDomain 1
   emailDomain <- randomDomain
 
-  let status = if validateSAMLEmails then "enabled" else "disabled"
+  let status = if requireExternalEmailVerification then "enabled" else "disabled"
   assertSuccess =<< setTeamFeatureStatus owner tid "validateSAMLemails" status
 
   void $ setTeamFeatureStatus owner tid "sso" "enabled"
@@ -910,7 +910,7 @@ testSsoLoginNoSamlEmailValidation (TaggedBool validateSAMLEmails) = do
       eid = CI.original $ uref ^. SAML.uidSubject . to SAML.unsafeShowNameID
   eid `shouldMatch` email
 
-  when validateSAMLEmails $ do
+  when requireExternalEmailVerification $ do
     getUsersId OwnDomain [uid] `bindResponse` \res -> do
       res.status `shouldMatchInt` 200
       user <- res.json & asList >>= assertOne
@@ -936,11 +936,11 @@ testSsoLoginNoSamlEmailValidation (TaggedBool validateSAMLEmails) = do
     user %. "email" `shouldMatch` email
 
 -- | create user with non-email externalId.  then use put to add an email address.
-testScimUpdateEmailAddress :: (HasCallStack) => TaggedBool "extIdIsEmail" -> TaggedBool "validateSAMLEmails" -> App ()
-testScimUpdateEmailAddress (TaggedBool extIdIsEmail) (TaggedBool validateSAMLEmails) = do
+testScimUpdateEmailAddress :: (HasCallStack) => TaggedBool "extIdIsEmail" -> TaggedBool "requireExternalEmailVerification" -> App ()
+testScimUpdateEmailAddress (TaggedBool extIdIsEmail) (TaggedBool requireExternalEmailVerification) = do
   (owner, tid, _) <- createTeam OwnDomain 1
 
-  let status = if validateSAMLEmails then "enabled" else "disabled"
+  let status = if requireExternalEmailVerification then "enabled" else "disabled"
   assertSuccess =<< setTeamFeatureStatus owner tid "validateSAMLemails" status
 
   void $ setTeamFeatureStatus owner tid "sso" "enabled"
@@ -991,7 +991,7 @@ testScimUpdateEmailAddress (TaggedBool extIdIsEmail) (TaggedBool validateSAMLEma
     res.status `shouldMatchInt` 200
     res.json %. "emails" `shouldMatch` [object ["value" .= newEmail]]
 
-  when validateSAMLEmails $ do
+  when requireExternalEmailVerification $ do
     getUsersId OwnDomain [uid] `bindResponse` \res -> do
       res.status `shouldMatchInt` 200
       user <- res.json & asList >>= assertOne
@@ -1164,11 +1164,11 @@ testScimUpdateEmailAddressAndExternalId = do
     user %. "status" `shouldMatch` "active"
     user %. "email" `shouldMatch` newEmail1
 
-testScimLoginNoSamlEmailValidation :: (HasCallStack) => TaggedBool "validateSAMLEmails" -> App ()
-testScimLoginNoSamlEmailValidation (TaggedBool validateSAMLEmails) = do
+testScimLoginNoSamlEmailValidation :: (HasCallStack) => TaggedBool "requireExternalEmailVerification" -> App ()
+testScimLoginNoSamlEmailValidation (TaggedBool requireExternalEmailVerification) = do
   (owner, tid, _) <- createTeam OwnDomain 1
 
-  let status = if validateSAMLEmails then "enabled" else "disabled"
+  let status = if requireExternalEmailVerification then "enabled" else "disabled"
   assertSuccess =<< setTeamFeatureStatus owner tid "validateSAMLemails" status
 
   void $ setTeamFeatureStatus owner tid "sso" "enabled"
@@ -1187,7 +1187,7 @@ testScimLoginNoSamlEmailValidation (TaggedBool validateSAMLEmails) = do
     res.status `shouldMatchInt` 200
     res.json %. "id" `shouldMatch` uid
 
-  when validateSAMLEmails $ do
+  when requireExternalEmailVerification $ do
     getUsersId OwnDomain [uid] `bindResponse` \res -> do
       res.status `shouldMatchInt` 200
       user <- res.json & asList >>= assertOne

integration/test/Test/Spar/GetByEmail.hs

@@ -28,10 +28,10 @@ import Testlib.Prelude
 -- | Test the /sso/get-by-email endpoint with multi-ingress setup
 testGetSsoCodeByEmailWithMultiIngress ::
   (HasCallStack) =>
-  TaggedBool "validateSAMLemails" ->
+  TaggedBool "requireExternalEmailVerification" ->
   TaggedBool "idpScimToken" ->
   App ()
-testGetSsoCodeByEmailWithMultiIngress (TaggedBool validateSAMLemails) (TaggedBool isIdPScimToken) = do
+testGetSsoCodeByEmailWithMultiIngress (TaggedBool requireExternalEmailVerification) (TaggedBool isIdPScimToken) = do
   let ernieZHost = "nginz-https.ernie.example.com"
       bertZHost = "nginz-https.bert.example.com"
 
@@ -65,7 +65,7 @@ testGetSsoCodeByEmailWithMultiIngress (TaggedBool validateSAMLemails) (TaggedBoo
       assertSuccess =<< setTeamFeatureStatus domain tid "sso" "enabled"
 
       -- The test should work for both: SCIM user with and without email confirmation
-      let status = if validateSAMLemails then "enabled" else "disabled"
+      let status = if requireExternalEmailVerification then "enabled" else "disabled"
       assertSuccess =<< setTeamFeatureStatus owner tid "validateSAMLemails" status
 
       -- Create IdP for ernie domain
@@ -98,7 +98,7 @@ testGetSsoCodeByEmailWithMultiIngress (TaggedBool validateSAMLemails) (TaggedBoo
       createScimUser domain scimToken scimUser >>= assertSuccess
 
       if isIdPScimToken
-        then when validateSAMLemails $ do
+        then when requireExternalEmailVerification $ do
           -- Activate the email so the user can be found by email
           activateEmail domain userEmail
         else
@@ -124,15 +124,15 @@ testGetSsoCodeByEmailWithMultiIngress (TaggedBool validateSAMLemails) (TaggedBoo
         ssoCodeStr `shouldMatch` idpIdBert
 
 -- | Test the /sso/get-by-email endpoint with regular (non-multi-ingress) setup
-testGetSsoCodeByEmailRegular :: (HasCallStack) => (TaggedBool "validateSAMLemails") -> (TaggedBool "idpScimToken") -> App ()
-testGetSsoCodeByEmailRegular (TaggedBool validateSAMLemails) (TaggedBool isIdPScimToken) =
+testGetSsoCodeByEmailRegular :: (HasCallStack) => (TaggedBool "requireExternalEmailVerification") -> (TaggedBool "idpScimToken") -> App ()
+testGetSsoCodeByEmailRegular (TaggedBool requireExternalEmailVerification) (TaggedBool isIdPScimToken) =
   withModifiedBackend def {sparCfg = setField "enableIdPByEmailDiscovery" True}
     $ \domain -> do
       (owner, tid, _) <- createTeam domain 1
       void $ setTeamFeatureStatus owner tid "sso" "enabled"
 
       -- The test should work for both: SCIM user with and without email confirmation
-      let status = if validateSAMLemails then "enabled" else "disabled"
+      let status = if requireExternalEmailVerification then "enabled" else "disabled"
       assertSuccess =<< setTeamFeatureStatus owner tid "validateSAMLemails" status
 
       -- Create IdP without domain binding
@@ -156,7 +156,7 @@ testGetSsoCodeByEmailRegular (TaggedBool validateSAMLemails) (TaggedBool isIdPSc
       createScimUser domain scimToken scimUser >>= assertSuccess
 
       if isIdPScimToken
-        then when validateSAMLemails $ do
+        then when requireExternalEmailVerification $ do
           -- Activate the email so the user can be found by email
           activateEmail domain userEmail
         else

libs/wire-api/src/Wire/API/Routes/Features.hs

@@ -36,4 +36,6 @@ type family FeatureErrors cfg where
 type family FeatureAPIDesc cfg where
   FeatureAPIDesc EnforceFileDownloadLocationConfig =
     "<p><b>Custom feature: only supported on some dedicated on-prem systems.</b></p>"
+  FeatureAPIDesc RequireExternalEmailVerificationConfig =
+    "<p>Controls whether externally managed email addresses (from SAML or SCIM) must be verified by the user, or are auto-activated.</p><p>The external feature name is kept as <code>validateSAMLemails</code> for backward compatibility. That name is misleading because the feature also applies to SCIM-managed users, and it controls email ownership verification rather than generic email validation.</p>"
   FeatureAPIDesc _ = ""

libs/wire-api/src/Wire/API/Routes/Public/Galley/Feature.hs

@@ -42,7 +42,7 @@ type FeatureAPI =
     :<|> FeatureAPIGetPut SearchVisibilityAvailableConfig
     :<|> SearchVisibilityGet
     :<|> SearchVisibilitySet
-    :<|> FeatureAPIGet ValidateSAMLEmailsConfig
+    :<|> FeatureAPIGet RequireExternalEmailVerificationConfig
     :<|> FeatureAPIGet DigitalSignaturesConfig
     :<|> FeatureAPIGetPut AppLockConfig
     :<|> FeatureAPIGetPut FileSharingConfig
@@ -108,7 +108,7 @@ type DeprecatedFeatureConfigs =
   [ LegalholdConfig,
     SSOConfig,
     SearchVisibilityAvailableConfig,
-    ValidateSAMLEmailsConfig,
+    RequireExternalEmailVerificationConfig,
     DigitalSignaturesConfig,
     AppLockConfig,
     FileSharingConfig,
@@ -129,7 +129,7 @@ type family AllDeprecatedFeatureConfigAPI cfgs where
 type DeprecatedFeatureAPI =
   FeatureStatusDeprecatedGet DeprecationNotice1 SearchVisibilityAvailableConfig V2
     :<|> FeatureStatusDeprecatedPut DeprecationNotice1 SearchVisibilityAvailableConfig V2
-    :<|> FeatureStatusDeprecatedGet DeprecationNotice1 ValidateSAMLEmailsConfig V2
+    :<|> FeatureStatusDeprecatedGet DeprecationNotice1 RequireExternalEmailVerificationConfig V2
     :<|> FeatureStatusDeprecatedGet DeprecationNotice2 DigitalSignaturesConfig V2
 
 type FeatureAPIGet cfg =

libs/wire-api/src/Wire/API/Team/Feature.hs

@@ -61,7 +61,7 @@ module Wire.API.Team.Feature
     SearchVisibilityAvailableConfig (..),
     SelfDeletingMessagesConfigB (..),
     SelfDeletingMessagesConfig,
-    ValidateSAMLEmailsConfig (..),
+    RequireExternalEmailVerificationConfig (..),
     DigitalSignaturesConfig (..),
     ConferenceCallingConfigB (..),
     ConferenceCallingConfig,
@@ -256,7 +256,7 @@ data FeatureSingleton cfg where
   FeatureSingletonLegalholdConfig :: FeatureSingleton LegalholdConfig
   FeatureSingletonSSOConfig :: FeatureSingleton SSOConfig
   FeatureSingletonSearchVisibilityAvailableConfig :: FeatureSingleton SearchVisibilityAvailableConfig
-  FeatureSingletonValidateSAMLEmailsConfig :: FeatureSingleton ValidateSAMLEmailsConfig
+  FeatureSingletonRequireExternalEmailVerificationConfig :: FeatureSingleton RequireExternalEmailVerificationConfig
   FeatureSingletonDigitalSignaturesConfig :: FeatureSingleton DigitalSignaturesConfig
   FeatureSingletonConferenceCallingConfig :: FeatureSingleton ConferenceCallingConfig
   FeatureSingletonSndFactorPasswordChallengeConfig :: FeatureSingleton SndFactorPasswordChallengeConfig
@@ -753,29 +753,35 @@ instance ToSchema SearchVisibilityAvailableConfig where
 type instance DeprecatedFeatureName V2 SearchVisibilityAvailableConfig = "search-visibility"
 
 --------------------------------------------------------------------------------
--- ValidateSAMLEmails feature
+-- RequireExternalEmailVerification feature
 
--- | This feature does not have a PUT endpoint. See Note [unsettable features].
-data ValidateSAMLEmailsConfig = ValidateSAMLEmailsConfig
+-- | Controls whether externally managed email addresses (from SAML or SCIM)
+-- must be verified by the user, or are auto-activated. When disabled, no
+-- verification email is sent, but the address is still activated immediately
+-- and can receive later account notifications such as new-device emails.
+-- The external feature name is kept for backward compatibility.
+--
+-- (This feature does not have a PUT endpoint. See Note [unsettable features].)
+data RequireExternalEmailVerificationConfig = RequireExternalEmailVerificationConfig
   deriving (Eq, Show, Generic, GSOP.Generic)
-  deriving (Arbitrary) via (GenericUniform ValidateSAMLEmailsConfig)
-  deriving (RenderableSymbol) via (RenderableTypeName ValidateSAMLEmailsConfig)
-  deriving (ParseDbFeature, Default) via (TrivialFeature ValidateSAMLEmailsConfig)
+  deriving (Arbitrary) via (GenericUniform RequireExternalEmailVerificationConfig)
+  deriving (RenderableSymbol) via (RenderableTypeName RequireExternalEmailVerificationConfig)
+  deriving (ParseDbFeature, Default) via (TrivialFeature RequireExternalEmailVerificationConfig)
 
-instance ToSchema ValidateSAMLEmailsConfig where
-  schema = object "ValidateSAMLEmailsConfig" objectSchema
+instance ToSchema RequireExternalEmailVerificationConfig where
+  schema = object "RequireExternalEmailVerificationConfig" objectSchema
 
-instance Default (LockableFeature ValidateSAMLEmailsConfig) where
+instance Default (LockableFeature RequireExternalEmailVerificationConfig) where
   def = defUnlockedFeature
 
-instance ToObjectSchema ValidateSAMLEmailsConfig where
-  objectSchema = pure ValidateSAMLEmailsConfig
+instance ToObjectSchema RequireExternalEmailVerificationConfig where
+  objectSchema = pure RequireExternalEmailVerificationConfig
 
-instance IsFeatureConfig ValidateSAMLEmailsConfig where
-  type FeatureSymbol ValidateSAMLEmailsConfig = "validateSAMLemails"
-  featureSingleton = FeatureSingletonValidateSAMLEmailsConfig
+instance IsFeatureConfig RequireExternalEmailVerificationConfig where
+  type FeatureSymbol RequireExternalEmailVerificationConfig = "validateSAMLemails"
+  featureSingleton = FeatureSingletonRequireExternalEmailVerificationConfig
 
-type instance DeprecatedFeatureName V2 ValidateSAMLEmailsConfig = "validate-saml-emails"
+type instance DeprecatedFeatureName V2 RequireExternalEmailVerificationConfig = "validate-saml-emails"
 
 --------------------------------------------------------------------------------
 -- DigitalSignatures feature
@@ -2207,7 +2213,7 @@ type Features =
     SSOConfig,
     SearchVisibilityAvailableConfig,
     SearchVisibilityInboundConfig,
-    ValidateSAMLEmailsConfig,
+    RequireExternalEmailVerificationConfig,
     DigitalSignaturesConfig,
     AppLockConfig,
     FileSharingConfig,

libs/wire-api/src/Wire/API/Team/FeatureFlags.hs

@@ -182,19 +182,19 @@ newtype instance FeatureDefaults SearchVisibilityInboundConfig
   deriving (FromJSON, ToJSON) via Defaults (Feature SearchVisibilityInboundConfig)
   deriving (ParseFeatureDefaults) via OptionalField SearchVisibilityInboundConfig
 
-newtype instance FeatureDefaults ValidateSAMLEmailsConfig
-  = ValidateSAMLEmailsDefaults (Feature ValidateSAMLEmailsConfig)
+newtype instance FeatureDefaults RequireExternalEmailVerificationConfig
+  = RequireExternalEmailVerificationDefaults (Feature RequireExternalEmailVerificationConfig)
   deriving stock (Eq, Show)
   deriving newtype (Default, GetFeatureDefaults)
-  deriving (FromJSON, ToJSON) via Defaults (Feature ValidateSAMLEmailsConfig)
+  deriving (FromJSON, ToJSON) via Defaults (Feature RequireExternalEmailVerificationConfig)
 
-instance ParseFeatureDefaults (FeatureDefaults ValidateSAMLEmailsConfig) where
+instance ParseFeatureDefaults (FeatureDefaults RequireExternalEmailVerificationConfig) where
   parseFeatureDefaults obj =
     do
       -- Accept the legacy typo in config input for backward compatibility,
       -- but prefer the canonical feature key when both are present.
-      mCanonical :: Maybe (FeatureDefaults ValidateSAMLEmailsConfig) <- obj .:? featureKey @ValidateSAMLEmailsConfig
-      mLegacy :: Maybe (FeatureDefaults ValidateSAMLEmailsConfig) <- obj .:? "validateSAMLEmails"
+      mCanonical :: Maybe (FeatureDefaults RequireExternalEmailVerificationConfig) <- obj .:? featureKey @RequireExternalEmailVerificationConfig
+      mLegacy :: Maybe (FeatureDefaults RequireExternalEmailVerificationConfig) <- obj .:? "validateSAMLEmails"
       pure $ fromMaybe def (mCanonical <|> mLegacy)
 
 data instance FeatureDefaults DigitalSignaturesConfig = DigitalSignaturesDefaults