{% extends "documentation/base.html" %}

{% block doc_content %}
<h1>Microsoft Entra SSO</h1>

<p class="lead">
  Configure Microsoft Entra sign-in so users can authenticate with their Microsoft account.
</p>

<div class="doc-callout doc-callout-warning">
  <strong>Status:</strong><br>
  This flow is configurable in Settings and available in the application, but should still be validated in your own tenant before production rollout.
</div>

<div class="doc-callout doc-callout-info">
  <strong>Where:</strong><br>
  Open <a href="{{ url_for('main.settings', section='integrations') }}"><strong>Settings -> Integrations</strong></a> and use the <strong>Microsoft Entra SSO</strong> card.
</div>

<h2>Prerequisites</h2>

<ul>
  <li>Admin access to Microsoft Entra (Azure AD).</li>
  <li>Admin access to Backupchecks Settings.</li>
  <li>Stable HTTPS URL for Backupchecks.</li>
</ul>

<h2>Entra App Registration</h2>

<ol>
  <li>Create an app registration in Entra.</li>
  <li>Capture <strong>Tenant ID</strong> and <strong>Client ID</strong>.</li>
  <li>Create and copy a <strong>Client Secret</strong>.</li>
  <li>Add redirect URI: <code>https://your-domain/auth/entra/callback</code>.</li>
</ol>

<h2>Backupchecks Fields</h2>

<ul>
  <li><strong>Enable Microsoft sign-in</strong></li>
  <li><strong>Tenant ID</strong></li>
  <li><strong>Client ID</strong></li>
  <li><strong>Client Secret</strong> (leave empty to keep stored secret)</li>
  <li><strong>Redirect URI</strong> (optional override)</li>
  <li><strong>Allowed domain/tenant</strong> (optional restriction)</li>
  <li><strong>Allowed Entra Group Object ID(s)</strong> (optional hard access gate)</li>
  <li><strong>Auto-provision unknown users as Viewer</strong> (optional)</li>
</ul>

<h2>Group Restriction Notes</h2>

<ul>
  <li>Use Entra security group object IDs (not display names).</li>
  <li>User must be member of at least one configured group.</li>
  <li>Ensure ID token includes <code>groups</code> claim.</li>
  <li>When Entra returns group overage tokens without inline groups, access is denied by design.</li>
</ul>

<h2>User Mapping Behavior</h2>

<ul>
  <li>Existing users are matched by username/email mapping logic.</li>
  <li>If no local user exists:
    <ul>
      <li>Auto-provision disabled: login is rejected.</li>
      <li>Auto-provision enabled: user is created with Viewer role.</li>
    </ul>
  </li>
</ul>

<h2>Troubleshooting</h2>

<ul>
  <li><strong>Button not visible:</strong> verify SSO enabled and required IDs/secrets saved.</li>
  <li><strong>Redirect mismatch:</strong> ensure callback URL matches Entra app configuration exactly.</li>
  <li><strong>Access denied:</strong> verify allowed domain/tenant and group membership settings.</li>
</ul>
{% endblock %}