From: Pedro Gonzalez Gomez <pegonzal@redhat.com>
Date: Tue, 22 Oct 2024 19:11:56 +0000 (+0200)
Subject: doc: mgr/dashboard: add OAuth2 SSO documentation
X-Git-Url: http://git.apps.os.sepia.ceph.com/?a=commitdiff_plain;h=cb5687caa37f0dc982a5edede0a353741ea54ad2;p=ceph.git

doc: mgr/dashboard: add OAuth2 SSO documentation

Signed-off-by: Pedro Gonzalez Gomez <pegonzal@redhat.com>
(cherry picked from commit 3e63860433a53d7d92d593beb3a4a02643b6ea98)

doc: mgr/dashboard: add --enable-auth flag

Add an instruction that includes the --enable-auth flag in a "git orch
apply mgmt-gateway" command, in accordance with a request made by
afreen23 here: https://github.com/ceph/ceph/pull/60440#discussion_r1953530599

Signed-off-by: Zac Dover <zac.dover@proton.me>
(cherry picked from commit 30dc60b81493537daf0805faf50b47460c2f80d1)
---

diff --git a/doc/mgr/dashboard.rst b/doc/mgr/dashboard.rst
index 4e0999b97b46b..f86a7019d1d4d 100644
--- a/doc/mgr/dashboard.rst
+++ b/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