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

{% block doc_content %}
<h1>Login & Authentication</h1>

<p class="lead">
  Learn how to log in to BackupChecks and manage your authentication session.
</p>

<h2>Logging In</h2>

<p>BackupChecks supports local username/password authentication and, optionally, Microsoft Entra (Azure AD) Single Sign-On.</p>

<h3>Login Steps</h3>

<ol>
  <li>Navigate to the BackupChecks URL in your web browser</li>
  <li>You will be automatically redirected to the login page if not authenticated</li>
  <li>Enter your <strong>username</strong> in the username field</li>
  <li>Enter your <strong>password</strong> in the password field</li>
  <li>If the login captcha is enabled, solve the simple math problem (e.g., "3 + 5 = ?")</li>
  <li>Click the <strong>Login</strong> button</li>
</ol>

<p>If your credentials are correct (and the captcha, if shown, is solved), you will be redirected to the dashboard.</p>

<div class="doc-callout doc-callout-info">
  <strong>💡 Captcha is configurable:</strong><br>
  The login captcha is controlled by the <code>login_captcha_enabled</code> setting in
  <strong>Settings → General</strong>. It is enabled by default; administrators can disable it
  for restricted internal deployments where the extra step is unnecessary.
</div>

<h3>First Login</h3>

<p>When you log in for the first time:</p>

<ol>
  <li>You will land on the <strong>Dashboard</strong> page</li>
  <li>Review any news announcements or system updates</li>
  <li>If you have multiple roles, select your preferred active role from the dropdown in the navigation bar</li>
  <li>Consider changing your password via <a href="{{ url_for('documentation.page', section='users', page='profile-settings') }}">Profile Settings</a></li>
</ol>

<div class="doc-callout doc-callout-tip">
  <strong>💡 Tip:</strong><br>
  Bookmark the BackupChecks URL for quick access. The system will remember your last active role between sessions.
</div>

<h2>Authentication Methods</h2>

<p>BackupChecks supports the following authentication methods:</p>

<ul>
  <li><strong>Local Username/Password:</strong> Credentials are stored hashed in the database</li>
  <li><strong>Microsoft Entra SSO (OAuth/OIDC):</strong> Optional Single Sign-On via Microsoft Entra (Azure AD), configurable in <strong>Settings → Integrations → Entra SSO</strong>. See <a href="{{ url_for('documentation.page', section='settings', page='entra-sso') }}">Entra SSO setup</a>.</li>
  <li><strong>Session-Based:</strong> After login, a secure session is created and stored in a cookie</li>
  <li><strong>No Two-Factor Authentication:</strong> 2FA is not currently implemented</li>
</ul>

<div class="doc-callout doc-callout-warning">
  <strong>⚠️ Entra SSO is implemented but not yet validated in production:</strong><br>
  The integration is wired up end-to-end (login flow, token exchange, optional auto-provisioning,
  group filtering) but has not been tested against a live tenant in our deployment. Treat it as a
  preview feature until verified. Local username/password remains the recommended login method.
</div>

<div class="doc-callout doc-callout-info">
  <strong>💡 Note:</strong><br>
  User accounts are created and managed by administrators via Settings → User Management.
</div>

<h2>Login Failures</h2>

<h3>Common Login Issues</h3>

<table>
  <thead>
    <tr>
      <th>Issue</th>
      <th>Possible Cause</th>
      <th>Solution</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Invalid credentials error</td>
      <td>Incorrect username or password</td>
      <td>Double-check username and password (case-sensitive). Contact your administrator if you've forgotten your credentials.</td>
    </tr>
    <tr>
      <td>Page doesn't load after login</td>
      <td>Session or cookie issue</td>
      <td>Clear your browser cookies and cache, then try again.</td>
    </tr>
    <tr>
      <td>Redirected back to login</td>
      <td>Session expired or browser issue</td>
      <td>Try a different browser or incognito/private mode to rule out browser-specific issues.</td>
    </tr>
  </tbody>
</table>

<div class="doc-callout doc-callout-warning">
  <strong>⚠️ Password Reset:</strong><br>
  BackupChecks does not currently have a self-service password reset feature. If you forget your password, contact your system administrator to reset it.
</div>

<h2>Session Management</h2>

<h3>Session Duration</h3>

<p>BackupChecks uses persistent sessions:</p>

<ul>
  <li>Sessions remain active as long as you keep using the application</li>
  <li>Sessions may expire after extended periods of inactivity (browser-dependent)</li>
  <li>Closing the browser tab does not immediately end your session</li>
  <li>The session cookie is set to expire when the browser closes (unless "Remember Me" is implemented)</li>
</ul>

<h3>Automatic Redirects</h3>

<p>If your session expires or becomes invalid:</p>

<ol>
  <li>You will be automatically redirected to the login page</li>
  <li>After logging in again, you may be redirected to the page you were trying to access</li>
</ol>

<h2>Logging Out</h2>

<p>To log out of BackupChecks:</p>

<ol>
  <li>Click the <strong>Logout</strong> button in the top-right corner of the navigation bar</li>
  <li>Your session will be terminated immediately</li>
  <li>You will be redirected to the login page</li>
</ol>

<div class="doc-callout doc-callout-tip">
  <strong>💡 Best Practice:</strong><br>
  Always log out when using a shared or public computer. This ensures your session is properly terminated and prevents unauthorized access.
</div>

<h2>Security Considerations</h2>

<h3>Password Security</h3>

<ul>
  <li><strong>Use Strong Passwords:</strong> Choose passwords with a mix of uppercase, lowercase, numbers, and symbols</li>
  <li><strong>Don't Share Credentials:</strong> Each user should have their own account</li>
  <li><strong>Change Default Passwords:</strong> If your administrator provides a temporary password, change it immediately</li>
  <li><strong>Regular Updates:</strong> Consider changing your password periodically</li>
</ul>

<h3>Browser Security</h3>

<ul>
  <li><strong>Use HTTPS When Applicable:</strong> If BackupChecks is exposed externally via a domain name, ensure you're connecting via HTTPS (check for the padlock icon in your browser). For internal deployments accessed via IP address, HTTPS may not be configured.</li>
  <li><strong>Keep Browser Updated:</strong> Use the latest version of your browser for security patches</li>
  <li><strong>Avoid Public WiFi:</strong> If accessing externally, don't log in from untrusted networks without a VPN</li>
  <li><strong>Clear Cookies on Shared Computers:</strong> Clear browser data after using a shared machine</li>
</ul>

<div class="doc-callout doc-callout-info">
  <strong>💡 Deployment Context:</strong><br>
  BackupChecks is typically deployed in restricted internal environments (accessed via IP address). For external access via a public domain, HTTPS should be configured using a reverse proxy or certificate.
</div>

<div class="doc-callout doc-callout-warning">
  <strong>⚠️ Security Alert:</strong><br>
  If you suspect unauthorized access to your account, contact your administrator immediately to reset your password and review audit logs.
</div>

<h2>Role Selection After Login</h2>

<p>If you have multiple roles assigned:</p>

<ol>
  <li>After login, your last active role will be automatically selected</li>
  <li>If this is your first login or the role is no longer valid, your first assigned role will be activated</li>
  <li>You can switch roles at any time using the role dropdown in the navigation bar</li>
</ol>

<p>See <a href="{{ url_for('documentation.page', section='users', page='users-and-roles') }}">Users & Roles</a> for more information about role switching.</p>

<h2>Troubleshooting Login Issues</h2>

<h3>Can't Remember Username</h3>

<p>Contact your system administrator. They can look up your username in Settings → User Management.</p>

<h3>Can't Remember Password</h3>

<p>Contact your system administrator. They can reset your password for you.</p>

<h3>Account Locked or Disabled</h3>

<p>BackupChecks does not currently implement account lockouts. If you cannot log in:</p>

<ol>
  <li>Verify your username and password are correct</li>
  <li>Contact your administrator to verify your account exists and is active</li>
  <li>Ask your administrator to check the audit logs for any issues</li>
</ol>

<h2>Browser Compatibility</h2>

<p>BackupChecks is designed to work with modern web browsers:</p>

<table>
  <thead>
    <tr>
      <th>Browser</th>
      <th>Minimum Version</th>
      <th>Status</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><strong>Mozilla Firefox</strong></td>
      <td>88+</td>
      <td><strong>Recommended - Most tested</strong></td>
    </tr>
    <tr>
      <td>Google Chrome</td>
      <td>90+</td>
      <td>Supported</td>
    </tr>
    <tr>
      <td>Microsoft Edge</td>
      <td>90+</td>
      <td>Supported</td>
    </tr>
    <tr>
      <td>Safari</td>
      <td>14+</td>
      <td>Supported</td>
    </tr>
  </tbody>
</table>

<div class="doc-callout doc-callout-tip">
  <strong>💡 Best Experience:</strong><br>
  Mozilla Firefox is the most thoroughly tested browser for BackupChecks and provides the best experience. While other modern browsers are supported, Firefox is recommended for optimal compatibility.
</div>

<div class="doc-callout doc-callout-warning">
  <strong>⚠️ Not Supported:</strong><br>
  Internet Explorer is not supported. Please use a modern browser (Firefox recommended).
</div>

<h2>Next Steps</h2>

<ul>
  <li><a href="{{ url_for('documentation.page', section='users', page='profile-settings') }}">Profile Settings</a> - Customize your profile and change your password</li>
  <li><a href="{{ url_for('documentation.page', section='getting-started', page='first-login') }}">First Login & Dashboard</a> - Learn about the dashboard interface</li>
  <li><a href="{{ url_for('documentation.page', section='users', page='users-and-roles') }}">Users & Roles</a> - Understand user roles and permissions</li>
</ul>

{% endblock %}