From cf3a2bbfe6ea098f7f13d0389a0ba4703754bd78 Mon Sep 17 00:00:00 2001 From: Ken'ichiro Oyama Date: Tue, 25 Aug 2026 13:18:24 +0900 Subject: [PATCH 1/3] docs(auth): explain Microsoft OAuth password auth constraint Document the Entra ID identifier and Platform password-reset delivery constraints that prevent Microsoft OAuth from being combined with password authentication. --- docs/guides/auth/integration/built-in-idp.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/guides/auth/integration/built-in-idp.md b/docs/guides/auth/integration/built-in-idp.md index 07513ba..55d49ea 100644 --- a/docs/guides/auth/integration/built-in-idp.md +++ b/docs/guides/auth/integration/built-in-idp.md @@ -403,6 +403,17 @@ export const builtinIdp = defineIdp("builtin-idp", { `allowMicrosoftOauth` requires both `allowedEmailDomains` and `disablePasswordAuth` to be set. This ensures that only users from specified email domains can authenticate, and that Microsoft OAuth is the sole authentication method. ::: +:::warning Why Microsoft OAuth cannot be combined with password authentication +Microsoft OAuth cannot be enabled together with password authentication when the Built-in IdP uses email addresses as user identifiers (`useNonEmailIdentifier: false`). This is because: + +- The `email` claim from Microsoft Entra ID is not guaranteed to be unique within a tenant and may be empty, so it cannot be used reliably to identify and match users. +- The `preferred_username` claim (UPN) is used instead because it is globally unique. Although it has an email-address-like format, it is not necessarily a deliverable email address. + +The Built-in IdP uses the user's identifier as the destination address for password reset emails sent by the Tailor Platform. Because a UPN is not necessarily a deliverable email address, these messages may be sent to addresses that cannot receive them. To maintain reliable email delivery from the Platform, Microsoft OAuth cannot be combined with password authentication. Google OAuth does not have this conflict because its `email` claim is suitable for user matching and password reset delivery. + +For this reason, configure Microsoft OAuth as the sole authentication method by setting `disablePasswordAuth: true`, or use separate IdP namespaces when both Microsoft OAuth and password authentication are required. +::: + :::warning `allowMicrosoftOauth` cannot be enabled when `useNonEmailIdentifier` is `true`. Microsoft OAuth requires email-based identifiers because Microsoft accounts are identified by their preferred username (UPN). ::: From 370cd51afe72c36b9e4ce14722cc0f4068073548 Mon Sep 17 00:00:00 2001 From: Ken'ichiro Oyama Date: Tue, 25 Aug 2026 15:36:55 +0900 Subject: [PATCH 2/3] docs(auth): clarify Entra ID UPN uniqueness --- docs/guides/auth/integration/built-in-idp.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/auth/integration/built-in-idp.md b/docs/guides/auth/integration/built-in-idp.md index 55d49ea..396b895 100644 --- a/docs/guides/auth/integration/built-in-idp.md +++ b/docs/guides/auth/integration/built-in-idp.md @@ -407,7 +407,7 @@ export const builtinIdp = defineIdp("builtin-idp", { Microsoft OAuth cannot be enabled together with password authentication when the Built-in IdP uses email addresses as user identifiers (`useNonEmailIdentifier: false`). This is because: - The `email` claim from Microsoft Entra ID is not guaranteed to be unique within a tenant and may be empty, so it cannot be used reliably to identify and match users. -- The `preferred_username` claim (UPN) is used instead because it is globally unique. Although it has an email-address-like format, it is not necessarily a deliverable email address. +- The `preferred_username` claim (UPN) is used instead because it is unique within an Entra ID tenant. Although it has an email-address-like format, it is not necessarily a deliverable email address. The Built-in IdP uses the user's identifier as the destination address for password reset emails sent by the Tailor Platform. Because a UPN is not necessarily a deliverable email address, these messages may be sent to addresses that cannot receive them. To maintain reliable email delivery from the Platform, Microsoft OAuth cannot be combined with password authentication. Google OAuth does not have this conflict because its `email` claim is suitable for user matching and password reset delivery. From ab2e5c95097b291076cb8fa7ced5ff12e14c33da Mon Sep 17 00:00:00 2001 From: Ken'ichiro Oyama Date: Tue, 25 Aug 2026 15:41:14 +0900 Subject: [PATCH 3/3] docs(auth): clarify Microsoft OAuth auth constraint --- docs/guides/auth/integration/built-in-idp.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/auth/integration/built-in-idp.md b/docs/guides/auth/integration/built-in-idp.md index 396b895..23759d6 100644 --- a/docs/guides/auth/integration/built-in-idp.md +++ b/docs/guides/auth/integration/built-in-idp.md @@ -404,7 +404,7 @@ export const builtinIdp = defineIdp("builtin-idp", { ::: :::warning Why Microsoft OAuth cannot be combined with password authentication -Microsoft OAuth cannot be enabled together with password authentication when the Built-in IdP uses email addresses as user identifiers (`useNonEmailIdentifier: false`). This is because: +Microsoft OAuth cannot be enabled together with password authentication in the Built-in IdP. When the Built-in IdP uses email addresses as user identifiers (`useNonEmailIdentifier: false`), this restriction is necessary because: - The `email` claim from Microsoft Entra ID is not guaranteed to be unique within a tenant and may be empty, so it cannot be used reliably to identify and match users. - The `preferred_username` claim (UPN) is used instead because it is unique within an Entra ID tenant. Although it has an email-address-like format, it is not necessarily a deliverable email address.