Authentication Page Restructure

[Oglopf]

While looking at some auth solutions for OOD I noticed some issues with the authentication page's layout and information:
https://osc.github.io/ood-documentation/latest/authentication.html

What is a Protocol vs. a Solution:

• Protocols: protocols like OIDC/OAuth 2.0, CAS (protocol), SAML, and Kerberos define the standards for how authentication and/or authorization are handled. They specify the format and process for exchanging authentication information between systems.
  • Some protocols are defined by RFCs (e.g., OIDC/OAuth 2.0, CAS, and Kerberos), while others are defined by external standards bodies, such as OASIS for SAML.
• Solutions: solutions like Shibboleth, Dex, Keycloak, and CAS (solution) are software implementations or platforms that use these protocols. These solutions act as identity providers (IdPs), service providers (SPs), or intermediaries to enable authentication and authorization using one or more protocols.

With these definitions the following issues become apparent:

1. Confusing Hierarchy. The way the documentation presents these topics seems to mix and match protocols and solutions on the same level:

• OIDC is a protocol, but Shibboleth and CAS as solutions are specific systems or software yet exist at the same level as OIDC.
• OIDC has multiple sections for different solutions for Dex and Keycloak, but these should both just be under an OIDC protocol section as solutions.

2. Inconsistent Structure.

• The way Dex and Keycloak are detailed under OIDC implies they are direct implementations of the OIDC protocol, which makes sense.
• But then Shibboleth and CAS appear at the same level without this kind of breakdown or clarifying their roles:
  • Shibboleth, while most commonly associated with SAML, can also act as an IdP for OIDC or OAuth2 in some setups. This flexibility should be acknowledged, but its primary association with SAML warrants placing it under a SAML section, maybe with a note about its broader capabilities.
  • Similarly, CAS (solution) follows the CAS protocol but is presented in a way that blurs the line between the solution and protocol.

The documentation could be more intuitive and helpful if it followed a more consistent structure, like this:

1. Protocols Overview:

• OpenID Connect (OIDC)
  • General explanation of OIDC
  • Solutions:
    • Dex
    • Keycloak
• SAML
  • General explanation of SAML
  • Solutions:
    • Shibboleth
    • ADFS with mod_auth_mellon
• CAS
  • General explanation of CAS protocol
  • Solution:
    • CAS

2. Authentication Solutions:

• Dex (for OIDC)
  • Installation and configuration steps
• Keycloak (for OIDC)
  • Installation and configuration, including extras like Duo for 2FA
• Shibboleth (for SAML)
  • Configuration details
• CAS
  • Setup and integration

And this is just an idea for the layout to improve the flow and reduce cognitive load on users. I'm certainly open to other structures as long as they achieve the goal of increasing velocity for time-to-compute.

While many admins and developers may have some familiarity with the above concepts, it's not uncommon for these distinctions to be conflated or misunderstood. By restructuring the documentation to clearly differentiate protocols from solutions and providing a logical flow, we can simplify the onboarding process and reduce confusion around one of the more complex aspects of setting up OOD.