This is an automated email from the ASF dual-hosted git repository.
harikrishna-patnala pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/cloudstack-documentation.git
The following commit(s) were added to refs/heads/main by this push:
new fa79c720 Add OAuth2 configuration details for domain-specific
providers (#647)
fa79c720 is described below
commit fa79c720fe01d4c3cdf0a223d083d8d7d3f266ba
Author: Daman Arora <[email protected]>
AuthorDate: Thu Jul 9 07:01:45 2026 -0400
Add OAuth2 configuration details for domain-specific providers (#647)
---
source/adminguide/accounts.rst | 101 +++++++++++++++++++++++++++++++++++++++--
1 file changed, 98 insertions(+), 3 deletions(-)
diff --git a/source/adminguide/accounts.rst b/source/adminguide/accounts.rst
index b70515c0..399fa504 100644
--- a/source/adminguide/accounts.rst
+++ b/source/adminguide/accounts.rst
@@ -653,14 +653,17 @@ granting access to resources. CloudStack supports OAuth2
authentication wherein
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.
+For admins, the following are the settings available to configure OAuth2.
``oauth2.enabled``
+can be configured at both the global and domain scopes; ``oauth2.plugins`` and
+``oauth2.plugins.exclude`` are global-only.
.. cssclass:: table-striped table-bordered table-hover
================================================ ================
===================================================================
-Global setting Default values
Description
+Setting Default values
Description
================================================ ================
===================================================================
-oauth2.enabled false
Indicates whether OAuth plugin is enabled or not
+oauth2.enabled false
Indicates whether OAuth plugin is enabled or not. Configurable at
+ global
and domain scopes (see Per-Domain OAuth Providers below).
oauth2.plugins google,github List of
OAuth plugins
oauth2.plugins.exclude List of
OAuth plugins which are excluded
================================================ ================
===================================================================
@@ -730,6 +733,98 @@ has to be provided in the login form and then click on
OAuth login.
:align: center
:alt: Login page for user under specific domain
+Per-Domain OAuth Providers
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In addition to globally registered OAuth providers, admins can register OAuth
providers
+at the domain level. This is useful in multi-tenant deployments where each
domain
+(representing a customer, department, or team) needs to authenticate users
against
+its own identity provider — for example, two domains can each have their own
GitHub
+OAuth application, with separate client IDs and secrets.
+
+A provider registered without a domain remains a *global* provider and is
available
+to all users. A provider registered against a domain is a *domain-specific*
provider
+and is only used when the user logs in under that domain.
+
+Enabling OAuth for a domain
+'''''''''''''''''''''''''''
+
+The ``oauth2.enabled`` setting uses a strict scope at the domain level:
domains do
+**not** inherit the global value. Each domain that should use OAuth must
explicitly
+set ``oauth2.enabled=true`` at the domain scope, regardless of whether the
global
+value is ``true`` or ``false``. The table below summarizes the resulting
behavior:
+
+.. cssclass:: table-striped table-bordered table-hover
+
+===================== ===================== ==========================
+Global oauth2.enabled Domain oauth2.enabled OAuth available in domain?
+===================== ===================== ==========================
+false not set No
+false true Yes
+false false No
+true not set No
+true true Yes
+true false No
+===================== ===================== ==========================
+
+.. TODO: Add screenshot showing the oauth2.enabled setting at the domain scope
(Domain details > Settings tab, with oauth2.enabled toggled to true).
+
+Registering a domain-specific provider
+''''''''''''''''''''''''''''''''''''''
+
+The "OAuth configuration" sub-section under "Configuration" now accepts an
optional
+**Domain** field when registering a provider. Leave the Domain field empty to
register
+a global provider, or pick a domain to register a provider that only applies
to users
+of that domain.
+
+The same fields described in the previous section (Provider, Description,
Provider
+Client ID, Redirect URI, Secret Key) apply. Only one provider of a given type
+(``google``, ``github``, ...) may exist per domain — and at most one global
provider
+of each type — so attempting to register a duplicate will be rejected.
+
+.. TODO: Add screenshot of the "Register OAuth provider" dialog showing the
new Domain selector field, with a domain selected.
+
+.. TODO: Add screenshot of the OAuth configuration list view showing both
global and domain-specific providers, with the new Domain column populated for
domain-specific entries.
+
+CloudMonkey API call to register a domain-specific provider:
+
+ - register oauthprovider provider=github description="Engineering GitHub"
+ clientid="Iv1.abc123" secretkey="secret456"
+ redirecturi="https://cloudstack.example.com/?verifyOauth";
+ domainid=<domain-uuid>
+
+To list providers visible to a particular domain (returns both that domain's
+providers and any global providers):
+
+ - list oauthproviders domainid=<domain-uuid>
+
+Login behavior
+''''''''''''''
+
+When the login page first loads, only global OAuth providers are shown on the
OAuth
+Login tab. Once the user enters a domain path in the login form, the UI
re-queries
+for providers visible to that domain and updates the buttons accordingly:
+
+ - If the domain has its own provider configured, the domain-specific
provider
+ buttons replace the global ones for that login attempt.
+
+ - If the domain has no providers configured and OAuth is enabled at that
domain,
+ the message "No OAuth providers configured for this domain" is shown.
+
+ - If OAuth is not enabled for that domain (``oauth2.enabled`` is not
``true`` at
+ the domain scope), the OAuth tab is not usable for that domain.
+
+ - If no global providers exist but at least one domain has providers, the
OAuth
+ tab prompts the user to enter their domain to see available providers.
+
+.. TODO: Add screenshot of the login page showing global OAuth providers
(default state, no domain entered).
+
+.. TODO: Add screenshot of the login page after a domain path has been
entered, showing the domain-specific OAuth provider buttons.
+
+The selected provider's stored credentials (client ID and secret) for the
resolved
+domain are then used to exchange the OAuth authorization code for an access
token
+and identify the user by email.
+
Using Two Factor Authentication For Users
------------------------------------------
