From 7d49f3c0099607b21df59472f995365dcf090e65 Mon Sep 17 00:00:00 2001
From: BilalG1 <bg2002@gmail.com>
Date: Fri, 19 Jun 2026 13:04:20 -0700
Subject: [PATCH] docs: clarify Microsoft OAuth email verification and account
 types (#1623)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## What

Adds a **Things to Know About Microsoft OAuth** section to the Microsoft
auth provider docs covering provider-specific behavior:

- **Emails are not marked as verified** — Microsoft doesn't attest
control of the returned email, so Hexclave treats Microsoft emails as
unverified. Links to Microsoft's [claims validation
guidance](https://learn.microsoft.com/en-us/entra/identity-platform/claims-validation#validate-the-subject).
- **Supported account types** (custom OAuth keys only) — explains how
the tenant type set in the dashboard/config maps to Microsoft's
`{tenant}` endpoint segment (`common` / `organizations` / `consumers` /
tenant ID), with the default being `consumers`. Links to Microsoft's
[endpoint
reference](https://learn.microsoft.com/en-us/entra/identity-platform/v2-protocols#endpoints).

Also fixes a leftover branding issue: the dev shared-keys `<Info>`
callout said "Stack" instead of "Hexclave".

## Why

The unverified-email behavior is surprising (sign-in succeeds but the
email isn't verified) and previously undocumented. The account-types
note helps developers using their own OAuth app pick the right tenant
setting.

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds a “Things to Know About Microsoft OAuth” section explaining that
Microsoft emails are treated as unverified and how account types map to
Microsoft tenant endpoints (custom keys only, default is `consumers`).
Also fixes the dev shared-keys callout to correctly use Hexclave
branding and behavior.

<sup>Written for commit 7ae78d6e5250f3c7097b5c62518e1a50d89fdc28.
Summary will update on new commits.</sup>

<a
href="https://cubic.dev/pr/hexclave/hexclave/pull/1623?utm_source=github"
target="_blank" rel="noopener noreferrer"
data-no-image-dialog="true"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img
alt="Review in cubic"
src="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a>

<!-- End of auto-generated description by cubic. -->

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **Documentation**
* Updated Microsoft authentication provider guide to clarify that
Hexclave automatically creates shared development keys and displays its
logo on the OAuth sign-in page.
* Added section explaining Microsoft OAuth email verification behavior
and how account types map to Microsoft tenant settings.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---
 .../apps/authentication/auth-providers/microsoft.mdx       | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/docs-mintlify/guides/apps/authentication/auth-providers/microsoft.mdx b/docs-mintlify/guides/apps/authentication/auth-providers/microsoft.mdx
index 7faf09c11..9a4863728 100644
--- a/docs-mintlify/guides/apps/authentication/auth-providers/microsoft.mdx
+++ b/docs-mintlify/guides/apps/authentication/auth-providers/microsoft.mdx
@@ -6,7 +6,7 @@ description: "Set up Microsoft as an authentication provider with Hexclave"
 This guide explains how to set up Microsoft as an authentication provider with Hexclave. Microsoft OAuth allows users to sign in to your application using their Microsoft account.
 
 <Info>
-  For Development purposes, Hexclave uses shared keys for this provider. Shared keys are automatically created by Stack, but show Stack's logo on the OAuth sign-in page.
+  For Development purposes, Hexclave uses shared keys for this provider. Shared keys are automatically created by Hexclave, but show Hexclave's logo on the OAuth sign-in page.
   You should replace these before you go into production.
 </Info>
 
@@ -35,6 +35,11 @@ This guide explains how to set up Microsoft as an authentication provider with H
   </Step>
 </Steps>
 
+## Things to Know About Microsoft OAuth
+
+- **Emails are not marked as verified.** Microsoft doesn't attest that the user controls the email it returns, so Hexclave treats Microsoft emails as unverified. See Microsoft's [claims validation guidance](https://learn.microsoft.com/en-us/entra/identity-platform/claims-validation#validate-the-subject).
+- **Supported account types control who can sign in** (custom OAuth keys only). When using your own Microsoft OAuth app, you can set the tenant type in the Hexclave dashboard or config. The value maps to the `{tenant}` segment of Microsoft's authorize/token endpoints: `common` (work/school **and** personal accounts), `organizations` (work/school only), `consumers` (personal only, the default), or a specific tenant ID/domain. See [Microsoft's endpoint reference](https://learn.microsoft.com/en-us/entra/identity-platform/v2-protocols#endpoints). This setting does not apply to the shared development keys.
+
 ### Need More Help?
 
 - Check the [Microsoft identity platform Documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/)