OAuth 2.0 integration

Author: harikrishna-patnala

source/_static/images/oauth-configuration-details.png

@@ -627,6 +627,65 @@ The following global configuration should be configured:
 
 - ``saml2.timeout``: SAML2 IDP Metadata refresh interval in seconds, minimum value is set to 300. Default is 1800
 
+Using OAuth2 Authentication For Users
+------------------------------------------
+
+OAuth2, the industry-standard authorization or authentication framework, simplifies the process of
+granting access to resources. CloudStack supports OAuth2 authentication wherein users can login into
+CloudStack without using username and password. CloudStack currently supports Google and Github providers.
+Other OAuth2 providers can be easily integrated with CloudStack using its plugin framework.
+
+For admins, the following are the settings available at global level to configure OAuth2.
+
+.. cssclass:: table-striped table-bordered table-hover
+
+================================================   ================   ===================================================================
+Global setting                                     Default values     Description
+================================================   ================   ===================================================================
+oauth2.enabled                                     false              Indicates whether OAuth plugin is enabled or not
+oauth2.plugins                                     google,github      List of OAuth plugins
+oauth2.plugins.exclude                                                List of OAuth plugins which are excluded
+================================================   ================   ===================================================================
+
+The login page when the OAuth2 is enabled and corresponding providers are configured.
+
+.. image:: /_static/images/oauth-login.png
+   :width: 400px
+   :align: center
+   :alt: Login page with OAuth logins
+
+"OAuth configuration" sub-section is added under "Configuration" where admins can register the corresponding
+OAuth providers.
+
+.. image:: /_static/images/oauth-sub-section.png
+   :width: 400px
+   :align: center
+   :alt: OAuth configuration section
+
+.. image:: /_static/images/oauth-configuration-details.png
+   :width: 400px
+   :align: center
+   :alt: OAuth configuration details
+
+To register the OAuth provider client ID, redirect URI, secret key have to provided.
+OAuth 2.0 has to be first configured in the corresponding provider to obtain the client ID, redirect URI, secret Key.
+
+For Google, please follow the instructions mentioned here `"Setting up OAuth 2.0 in Google" <https://support.google.com/cloud/answer/6158849?hl=en>`_.
+For Github, please follow the instructions mentioned here `"Setting up OAuth 2.0 in Github" <https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app>`_.
+
+In any OAuth 2.0 configuration admin has to use the redirect URI "http://<management server IP>:<port>/#/verifyOauth"
+
+.. Note:: [Google OAuth 2.0 redirect URI] :
+          Google OAuth 2.0 configuration wont accept '#' in the URI, please use "http://<management server IP>:<port>/verifyOauth"
+
+Email address is the key to identify the user in CloudStack. In case if user belongs to any specific domain, domain name
+has to be provided in the login form and then click on OAuth login.
+
+.. image:: /_static/images/user-domain-login.png
+   :width: 400px
+   :align: center
+   :alt: Login page for user under specific domain
+
 Using Two Factor Authentication For Users
 ------------------------------------------