Add Microsoft Entra ID SAML SSO integration guide

[moredure]

Add docs/cloud/sso/microsoft.md following the Okta/OneLogin template, covering connection setup, Attributes & Claims, SCIM provisioning, troubleshooting (including the spn: Entity ID prefix quirk on older tenants), and certificate rotation. Link the new guide from sso.md, add-sso-connection.md and category.yml.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
documentation	Ready	Preview, Comment	Jul 22, 2026 12:27pm

[qodo-free-for-open-source-projects]

PR Summary by Qodo

Add Microsoft Entra ID SAML SSO integration guide and fix ACS URL examples

📝 Documentation 🕐 20-40 Minutes

AI Description

• Add a Microsoft Entra ID SAML SSO setup guide, including SCIM and troubleshooting.
• Link the new Entra guide from the SSO index and connection-setup docs.
• Correct ACS/Reply URL examples across all SSO provider guides.

Diagram

graph TD
  CAT["docs/cloud/sso/_category_.yml"] --> SSO["docs/cloud/sso/sso.md"] --> ADD["docs/cloud/sso/add-sso-connection.md"]
  SSO --> OKTA["docs/cloud/sso/okta.md"] --> ONE["docs/cloud/sso/onelogin.md"] --> MS["docs/cloud/sso/microsoft.md"]
  ADD --> MS

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Centralize SAML endpoint examples via a shared snippet/variable

• ➕ Prevents future drift (e.g., ACS URL changes) across multiple provider guides
• ➕ Reduces reviewer burden for future doc updates
• ➖ Requires adopting/standardizing a docs include/templating pattern
• ➖ Slightly increases indirection when reading a single page in isolation

2. Create a single 'SAML basics' page and keep provider pages minimal

• ➕ Avoids repeating claim/ACS/cert-rotation guidance in each provider doc
• ➕ Encourages consistent terminology and canonical URLs
• ➖ Users may prefer self-contained provider-specific walkthroughs
• ➖ Requires reworking existing Okta/OneLogin docs structure

Recommendation: The PR’s approach (a full provider-specific Entra guide mirroring existing Okta/OneLogin templates, plus fixing the ACS URL in all guides) is appropriate for usability and discoverability. Consider follow-up work to centralize shared constants/snippets for common URLs (ACS/Reply URL) to avoid similar inconsistencies recurring across multiple SSO docs.

Files changed (6) +289 / -5

Documentation (6) +289 / -5

_category_.ymlUpdate SSO section description to include Microsoft Entra ID +1/-1

Update SSO section description to include Microsoft Entra ID

• Expands the generated SSO docs index description to list Microsoft Entra ID alongside Okta and OneLogin.

docs/cloud/sso/category.yml

add-sso-connection.mdAdd link to Microsoft Entra ID configuration guide +1/-0

Add link to Microsoft Entra ID configuration guide

• Adds Microsoft Entra ID to the list of provider-specific setup guides referenced from the SSO connection creation page.

docs/cloud/sso/add-sso-connection.md

microsoft.mdAdd Microsoft Entra ID SAML SSO + SCIM provisioning guide +282/-0

Add Microsoft Entra ID SAML SSO + SCIM provisioning guide

• Introduces a complete Microsoft Entra ID (Azure AD) SAML 2.0 integration walkthrough, including required claims, metadata configuration options, SCIM provisioning steps, troubleshooting (including the legacy 'spn:' Entity ID quirk), and certificate rotation guidance.

docs/cloud/sso/microsoft.md

okta.mdFix Okta ACS URL example +1/-1

Fix Okta ACS URL example

• Updates the Okta SAML Single Sign-On URL example to use the correct Dragonfly Cloud callback endpoint.

docs/cloud/sso/okta.md

onelogin.mdFix OneLogin ACS/Recipient URL examples +2/-2

Fix OneLogin ACS/Recipient URL examples

• Updates OneLogin Recipient and ACS URL examples to the correct Dragonfly Cloud callback endpoint.

docs/cloud/sso/onelogin.md

sso.mdList Microsoft Entra ID as a first-class SAML provider option +2/-1

List Microsoft Entra ID as a first-class SAML provider option

• Adds a dedicated Microsoft Entra ID SAML provider entry linking to the new guide, and narrows the 'Custom SAML Provider' examples accordingly.

docs/cloud/sso/sso.md

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. SCIM token placeholder text ✓ Resolved 🐞 Bug ≡ Correctness

Description

In docs/cloud/sso/microsoft.md the SCIM steps include redacted placeholders (e.g., "********" /
"Secret ******") instead of explicitly telling the reader to copy/paste the SCIM bearer token,
making the instructions unclear and the Markdown formatting malformed in that list item.

Code

docs/cloud/sso/microsoft.md[R172-185]

+1. Navigate to your SSO connection in Dragonfly Cloud
+2. Toggle **SCIM Provisioning** to enabled
+3. Copy the **SCIM Endpoint URL** and ******** (you'll need these for Microsoft Entra ID configuration)
+
+### Configuring SCIM in Microsoft Entra ID
+
+1. In the Microsoft Entra admin center, go to your Dragonfly Cloud enterprise application
+2. Navigate to **Provisioning**
+3. Click **Get started** (or **New configuration**)
+4. Set **Provisioning Mode** to **Automatic**
+5. Under **Admin Credentials**, enter:
+   - **Tenant URL**: Paste the SCIM endpoint URL from Dragonfly Cloud
+   - **Secret ****** Paste the bearer token from Dragonfly Cloud
+6. Click **Test Connection** to verify the connection

Evidence

The new Microsoft guide uses placeholders instead of naming the SCIM bearer token and has a
malformed bullet for the Entra "Secret" field, while the existing managed-users SCIM doc clearly
states to copy the "bearer token" and configure it in the IdP.

docs/cloud/sso/microsoft.md[170-186]
docs/cloud/sso/managed-users.md[43-48]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The Microsoft Entra ID SCIM provisioning section contains placeholder/redacted text ("********" and "Secret ******") where the documentation should explicitly instruct the user to copy the SCIM **bearer token** and paste it into Entra’s **Secret Token** field (or whatever the correct UI label is). This currently makes the SCIM configuration steps ambiguous and the list formatting incorrect.
## Issue Context
Other SCIM documentation in this repo refers to the credential as a "bearer token".
## Fix Focus Areas
- docs/cloud/sso/microsoft.md[170-186]
- docs/cloud/sso/managed-users.md[43-48]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. OneLogin validator regex mismatch ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

docs/cloud/sso/onelogin.md updates the Recipient/ACS URL examples to the account.dragonflydb.cloud
host but leaves the ACS URL Validator regex example matching dragonflydb.cloud, creating
contradictory guidance and potentially rejecting the new ACS URL if users copy the regex literally.

Code

docs/cloud/sso/onelogin.md[R71-79]

2. **Recipient**: Enter the ACS URL provided by Dragonfly Cloud
-   - Example: `https://dragonflydb.cloud/auth/saml/callback`
+   - Example: `https://account.dragonflydb.cloud/login/saml/callback`
3. **ACS (Consumer) URL Validator**: Enter a regular expression to validate the ACS URL
- Example: `https://dragonflydb\.cloud/.*`
- Or leave as default: `.*`
4. **ACS (Consumer) URL**: Enter the same ACS URL as Recipient
-   - Example: `https://dragonflydb.cloud/auth/saml/callback`
+   - Example: `https://account.dragonflydb.cloud/login/saml/callback`

Evidence

Within the same OneLogin configuration section, the updated ACS URL examples use the
account.dragonflydb.cloud host while the validator regex example still matches dragonflydb.cloud, so
copying the examples as-is produces a mismatch.

docs/cloud/sso/onelogin.md[68-80]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The OneLogin guide now shows ACS URLs on `https://account.dragonflydb.cloud/...` but the validator regex example still targets `https://dragonflydb\.cloud/.*`. This is inconsistent and may cause misconfiguration for users who copy the regex example.
## Issue Context
The guide notes the validator can be left as default `.*`, which reduces impact, but the host-specific example should still be consistent with the updated ACS URL examples.
## Fix Focus Areas
- docs/cloud/sso/onelogin.md[69-80]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---