Step-up Auth: Add documentation link when not authenticated

🛠️ with ❤️ at Siemens

Problem: Unclear Guidance for Users When Step-Up Authentication Fails

Currently, when step-up authentication fails, users receive a generic "Re-authentication required" message (see screenshot). This message lacks actionable guidance, leaving users unsure how to resolve the issue, particularly regarding identity provider configuration. This can lead to user frustration and increased support requests.

Impact: This leads to a poor user experience, increases the support burden, and raises potential security concerns. Users are blocked from accessing resources without clear instructions, driving them to seek support and potentially resort to insecure workarounds.

Proposal: Enhanced Error Messaging with Documentation Link

Provide users with a direct link to relevant documentation when step-up authentication fails. This documentation should guide them on setting up and managing the identity provider for step-up authentication within their organization.

This will be achieved by:

1. Adding a documentation_link field to the OAuth provider configuration. This field will store the URL to custom (internal) documentation specific to the identity provider configuration.

   # The `documentation_link` field is a URL to custom (internal) documentation that explains
   # the identity provider configuration. Use this to provide guidance on how to set up
   # and manage the identity provider for step-up authentication in your organization.
   documentation_link: "<Link to internal documentation of the OIDC step-up mechanism>"

2. Modifying the step-up authentication failure message. The system will check for a configured documentation_link and append it to the existing rejection message. The link text will be clear and informative (e.g., "For more information on configuring step-up authentication, see our documentation.")

Key Benefits

• Improved User Experience: Provides users with immediate, actionable guidance to resolve authentication issues.
• Reduced Support Costs: Enables self-service troubleshooting, reducing the volume of support requests.
• Enhanced Security: Encourages users to follow secure authentication practices.

Implementation Plan

• Update the OAuth provider configuration:
  • Add a documentation_link field to the OAuth provider configuration (e.g., in config/gitlab.yml or the database).
• Modify the step-up authentication failure message:
  • When step-up authentication fails (user is not authenticated), check if a documentation_link is configured for the relevant OAuth provider.
  • If a documentation_link is present, append it to the existing rejection message. The link text should be clear, e.g., "For more information on configuring step-up authentication, see our documentation."
• Frontend changes:
  • Ensure the documentation link is properly displayed in the UI.
• Testing:
  • Add unit and integration tests to verify that the documentation link is displayed correctly when step-up authentication fails and that the link points to the correct URL.

Questions for Discussion

• Where should the documentation_link be stored (e.g., config/gitlab.yml, database, or other)?
• What is the best way to ensure the documentation link is relevant and up-to-date?
• What specific metrics should we track to measure the success of this change (e.g., reduction in support requests, user satisfaction)?