Merge pull request ceph#60440 from rhcs-dashboard/add-oauth2-sso-doc

doc: mgr/dashboard: add OAuth2 SSO documentation

Reviewed-by: Anthony D'Atri <[email protected]>
Reviewed-by: Afreen Misbah <[email protected]>

Author: zdover23

doc/mgr/dashboard.rst

@@ -43,8 +43,8 @@ The dashboard provides the following features:
   after the first login or after a configurable time period. See
   :ref:`dashboard-user-role-management` for details.
 * **Single Sign-On (SSO)**: The dashboard supports authentication
-  via an external identity provider using the SAML 2.0 protocol. See
-  :ref:`dashboard-sso-support` for details.
+   via an external identity provider using the SAML 2.0 protocol or thse OAuth2 protocol. See
+   :ref:dashboard-saml2-sso-support and :ref:dashboard-oauth2-sso-support for details.
 * **SSL/TLS support**: All HTTP communication between the web browser and the
   dashboard is secured via SSL. A self-signed certificate can be created with
   a built-in command, but it's also possible to import custom certificates
@@ -711,10 +711,10 @@ If no value is set for that option, it will simply fall back to the value of the
 GRAFANA_API_URL option. If set, it will instruct the browser to use this URL to
 access Grafana.
 
-.. _dashboard-sso-support:
+.. _dashboard-saml2-sso-support:
 
-Enabling Single Sign-On (SSO)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Enabling SAML2 Single Sign-On (SSO)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The Ceph Dashboard supports external authentication of users via the
 `SAML 2.0 <https://en.wikipedia.org/wiki/SAML_2.0>`_ protocol. You need to
@@ -775,6 +775,50 @@ To enable SSO:
 
    ceph dashboard sso enable saml2
 
+.. _dashboard-oauth2-sso-support:
+
+Enabling OAuth2 Single Sign-On (SSO)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The Ceph Dashboard supports external authentication of users via the
+`OAuth <https://en.wikipedia.org/wiki/OAuth>`_ protocol. You need to
+have :ref:`cephadm` enabled as your orchestrator with an active
+:ref:`deploy-cephadm-mgmt-gateway` and :ref:`deploy-cephadm-oauth2-proxy` services.
+
+From the IDP of choice, Keycloak is the current recomendation and tested solution,
+configure the IDP's client used in the `oauth2-proxy` service configuration to validate the following redirect URLs
+for login_url: `https://<host_name>|<IP_address>/oauth2/callback` and
+the following logout_url: `https://<host_name>|<IP_address>/ /oauth2/sign_out`
+
+Again, from the IDP, we will need a user with a valid role, this user will be the one to perform
+authorization against, we can create a role like: 'administator' to give admin level access to the user.
+
+Make certain that the ``enable_auth`` flag has been included in the ``ceph orch
+apply mgmt-gateway`` command and that it has been set to ``true`` by running a
+command of the following form:
+
+.. prompt:: bash $
+
+   ceph orch apply mgmt-gateway --enable_auth=true --placement=<ceph-node-02>
+
+To disable SSO:
+
+.. prompt:: bash $
+
+   ceph dashboard sso disable
+
+To check if SSO is enabled:
+
+.. prompt:: bash $
+
+   ceph dashboard sso status
+
+To enable SSO:
+
+.. prompt:: bash $
+
+   ceph dashboard sso enable oauth2
+
 .. _dashboard-alerting:
 
 Enabling Prometheus Alerting