docs: clarify Microsoft OAuth email verification and account types (#1623)

## 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 7ae78d6e52.
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 -->
This commit is contained in:
BilalG1 2026-06-19 13:04:20 -07:00 committed by GitHub
parent 969bf03c5a
commit 7d49f3c009
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194

View File

@ -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/)