BookStack: Fix SSO/SAML Login Failure With Windows Hello

Introduction

In this article, we will explore a common issue encountered by BookStack users who utilize Windows Hello for authentication: the failure of Single Sign-On (SSO) or Security Assertion Markup Language (SAML) login. This problem, identified by the error message AADSTS75011, arises when users enrolled in Windows Hello attempt to log in to BookStack using methods such as PIN or biometrics. We will delve into the root causes of this issue, provide a step-by-step guide to troubleshooting, and offer potential solutions to ensure seamless SSO login for Windows Hello users.

The error message AADSTS75011: Authentication method 'X509, MultiFactor, X509Device' by which the user authenticated with the service doesn't match requested authentication method 'Password, ProtectedTransport'. Contact the BookStack application owner. indicates a mismatch in the authentication methods expected by BookStack and those provided by Windows Hello. This discrepancy prevents users from successfully logging in, disrupting their workflow and access to essential information. This comprehensive guide aims to address this issue head-on, providing clear instructions and practical solutions for BookStack administrators and users alike.

Understanding the Issue: SSO/SAML Login Failure with Windows Hello

The core problem lies in the authentication methods employed by Windows Hello and the expectations of the BookStack application when SAML SSO is configured. When a user logs into Windows using Windows Hello (PIN, biometrics, etc.), the authentication method differs from the traditional username/password approach. This difference triggers the AADSTS75011 error because the authentication method presented by Windows Hello (X509, MultiFactor, X509Device) doesn't align with the methods BookStack expects (Password, ProtectedTransport).

To put it simply, BookStack, when configured for SAML SSO, expects a specific type of authentication handshake. Windows Hello, while enhancing security through modern authentication methods, doesn't always play nicely with these expectations out-of-the-box. This mismatch is particularly evident in environments where Entra ID (formerly Azure AD) is used for identity management.

This issue becomes more apparent in specific scenarios: Imagine a user who typically logs into their Windows machine using a password. SAML SSO to BookStack works flawlessly for them. However, the moment they switch to logging in with a PIN or fingerprint via Windows Hello, the SSO process breaks down, resulting in the frustrating AADSTS75011 error. This inconsistent behavior can lead to user confusion and a perceived lack of reliability in the SSO system.

Reproducing the Bug: A Step-by-Step Guide

To effectively troubleshoot this issue, it's crucial to understand the exact steps that lead to the error. Here's a detailed guide to reproduce the bug, ensuring you can accurately identify and address the problem in your BookStack environment:

1. Set up BookStack with SAML SSO: Begin by ensuring your BookStack instance is correctly configured to use SAML SSO. This typically involves integrating BookStack with an Identity Provider (IdP) like Entra ID, Okta, or similar. Verify that the SAML settings in BookStack are accurately configured to match your IdP's requirements. This includes the correct entity ID, SSO URL, and certificate.
2. Enable Windows Hello: On a Windows machine, enable Windows Hello and set up a login method such as a PIN or biometric authentication (fingerprint, facial recognition). Ensure the user can successfully log into Windows using these Windows Hello methods.
3. Initial Login with Username/Password (Successful SSO): Log into Windows using a traditional username and password. Once logged in, attempt to access BookStack via SAML SSO. This should work without issues, confirming that the basic SAML setup is functional.
4. Log out of Windows: Log out of the Windows session to prepare for the Windows Hello test.
5. Log in with Windows Hello (PIN or Biometrics): Log back into Windows using Windows Hello (PIN, fingerprint, etc.). This is the critical step where the issue will manifest.
6. Attempt SAML SSO Login to BookStack (Failure): With the user logged in via Windows Hello, try to access BookStack through SAML SSO. At this point, the AADSTS75011 error should appear, indicating the authentication method mismatch.

By following these steps, you can reliably reproduce the bug and confirm that the issue is indeed related to Windows Hello authentication. This reproducibility is essential for effective troubleshooting and testing potential solutions.

Examining the Error Message: AADSTS75011

The error message AADSTS75011 is a critical clue in diagnosing this issue. Let's break it down to understand its implications:

• AADSTS75011: This is the specific error code assigned by Azure Active Directory (now Entra ID) to indicate an authentication method mismatch.
• Authentication method 'X509, MultiFactor, X509Device': This part of the message reveals the authentication methods that the user employed. In this case, it signifies that Windows Hello was used, which leverages X.509 certificates, Multi-Factor Authentication (MFA), and device-based authentication.
• by which the user authenticated with the service doesn't match requested authentication method 'Password, ProtectedTransport': This highlights the core of the problem. BookStack, or rather the SAML configuration within BookStack, is expecting authentication methods based on passwords and protected transport (HTTPS), which is the standard for web-based authentication.
• Contact the BookStack application owner: This is a standard recommendation, advising the user to reach out to the application administrator for assistance in resolving the issue.

In essence, the error message tells us that the authentication information provided by Windows Hello doesn't align with the authentication methods that BookStack is configured to accept. This mismatch is the root cause of the SSO login failure. Understanding this discrepancy is key to finding a suitable solution.

Potential Solutions and Workarounds

Several approaches can be taken to address the SSO/SAML login failure with Windows Hello in BookStack. Here, we'll explore some potential solutions and workarounds:

1. Adjusting Authentication Context in Entra ID

One of the most effective solutions involves adjusting the authentication context within your Entra ID configuration. This entails specifying the acceptable authentication methods for the BookStack application. Here’s how you can approach this:

• Conditional Access Policies: Entra ID's Conditional Access policies allow you to define specific conditions under which access is granted to applications. You can create a policy that requires Multi-Factor Authentication (MFA) for all users, which aligns with the authentication methods used by Windows Hello.
• Authentication Context Configuration: Entra ID allows you to define custom authentication contexts. You can create a context that includes X509 and other Windows Hello-related methods. Then, configure your BookStack application in Entra ID to accept this context.

By aligning the authentication context in Entra ID with the methods used by Windows Hello, you can bridge the gap and enable successful SSO login.

2. Configuring SAML Request in BookStack

Another approach is to modify the SAML request sent by BookStack to include the desired authentication context. This might involve adjusting the SAML settings within BookStack or using a custom SAML integration.

• RequestedAuthnContext: The SAML standard includes a RequestedAuthnContext element that specifies the acceptable authentication methods. You can configure BookStack to include this element in its SAML requests, explicitly requesting methods compatible with Windows Hello.

However, the feasibility of this solution depends on the flexibility of BookStack's SAML implementation and whether it allows for customization of the SAML request.

3. Browser-Specific Considerations

Sometimes, the issue might be browser-specific due to how different browsers handle Windows Authentication and Windows Hello. Here are some considerations:

• Alternative Browsers: Try using a different browser to access BookStack. Some browsers might handle Windows Hello authentication more seamlessly with SAML SSO.
• Browser Settings: Review your browser settings related to authentication and security. Ensure that no settings are interfering with the SAML SSO process.

4. Temporary Workaround: Password Login

As a temporary workaround, users can log into Windows using their password instead of Windows Hello. This will bypass the authentication method mismatch and allow them to log into BookStack via SAML SSO. However, this is not a long-term solution as it undermines the security benefits of Windows Hello.

Step-by-Step Troubleshooting Guide

To effectively resolve the SSO/SAML login failure with Windows Hello in BookStack, follow this detailed troubleshooting guide:

1. Verify SAML Configuration:
   • Double-check your SAML settings in BookStack and your Identity Provider (e.g., Entra ID). Ensure that the entity ID, SSO URL, certificate, and other parameters are correctly configured.
   • Confirm that the user accounts in BookStack are properly mapped to the corresponding accounts in your IdP.
2. Examine Entra ID Logs:
   • Review the sign-in logs in Entra ID for detailed information about the failed login attempts. These logs often provide specific error messages and insights into the cause of the issue.
   • Look for any discrepancies in the authentication methods or any Conditional Access policies that might be blocking the login.
3. Test with Different Browsers:
   • Try accessing BookStack using different browsers (e.g., Chrome, Firefox, Edge) to see if the issue is browser-specific.
   • Clear the browser cache and cookies to rule out any cached authentication data.
4. Check Windows Hello Configuration:
   • Ensure that Windows Hello is properly configured and that the user can successfully log into Windows using their PIN or biometrics.
   • Verify that the device is properly registered in Entra ID if you are using device-based Conditional Access policies.
5. Implement Entra ID Conditional Access Policies:
   • Create a Conditional Access policy in Entra ID that requires MFA for all users accessing BookStack. This can help align the authentication methods with Windows Hello.
   • Configure the policy to accept authentication methods used by Windows Hello.
6. Adjust SAML Request (If Possible):
   • If BookStack allows customization of the SAML request, try adding the RequestedAuthnContext element to specify acceptable authentication methods.
   • Consult BookStack's documentation or support resources for guidance on customizing the SAML request.
7. Contact BookStack Support:
   • If you have exhausted all troubleshooting steps and are still facing the issue, reach out to BookStack's support team for assistance. Provide them with detailed information about your environment, SAML configuration, and the steps you have taken to troubleshoot the problem.

By following this systematic approach, you can effectively diagnose and resolve the SSO/SAML login failure with Windows Hello in BookStack.

Conclusion

The SSO/SAML login failure for Windows Hello users in BookStack, indicated by the AADSTS75011 error, stems from a mismatch in authentication methods. By understanding the underlying causes and systematically troubleshooting the issue, you can restore seamless SSO access for your users. Implementing Entra ID Conditional Access policies, adjusting SAML requests (if possible), and considering browser-specific factors are key steps in resolving this problem.

Remember to test your solutions thoroughly and consult BookStack's documentation or support resources for further assistance. Ensuring a smooth and secure login experience for your users is crucial for the effective use of BookStack in your organization.

For more information on SAML and SSO, you can visit the SAML Wikipedia page.