oauth2: add a generic OIDC provider type by nagaboinaramgopal · Pull Request #14205 · apache/cloudstack

nagaboinaramgopal · 2026-09-18T15:20:20Z

Description

The OAuth2 plugin resolves a login to a UserOAuth2Authenticator through a fixed
provider-name to Spring-bean map. Each OIDC vendor is its own bean
(GoogleOAuth2Provider, GithubOAuth2Provider, KeycloakOAuth2Provider) running the
same authorization-code flow with no vendor-specific logic in it. Two consequences:
adding an IdP means shipping a new class, and because provider is simultaneously the
display name and the routing key, a domain can register exactly one keycloak.

This PR decouples the two by adding a type column to oauth_provider:

OAuth2AuthManagerImpl.getUserOAuth2AuthenticationProvider looks the name up in the
bean map first, as before, and only on a miss falls back to the registration's type.
provider becomes an admin-chosen label; type selects the implementation. One bean
can serve any number of registrations under arbitrary names.
getUserOAuth2AuthenticationProvider, verifyUser and verifySecretCodeAndFetchEmail
now carry the registration name, so a shared bean knows which row it is acting for.
Existing google/github/keycloak rows have a null type and continue to dispatch
by name, on the same code path as today.

GenericOIDCOAuth2Provider is registered under type=oidc and configured with the issuer
URL alone. It reads token_endpoint and jwks_uri from the issuer's
.well-known/openid-configuration (cached; the document's issuer must match the
configured value), and validates the id_token before trusting any claim in it: signature
against the JWKS key named by the token kid, then issuer, audience and expiry, via CXF's
JwsJwtCompactConsumer / JwkUtils / JwtUtils. That is cxf-rt-rs-security-jose,
already on the plugin classpath, so no new dependency.

Unlike the vendor providers, it holds no token in an instance field. The code is exchanged
per call, and a code verified through verifyOAuthCodeAndGetUser is cached for 60s and
consumed once, so the oauthlogin that immediately follows does not re-present it to the
IdP.

API / response fix: ListOAuthProvidersCmd and UpdateOAuthProviderCmd derived the
response enabled flag from authenticatorPluginNames.contains(provider), a
name-to-bean check, which reported every generically-named registration as disabled. Both
now also accept a registration whose type resolves to a plugin.

type is settable on register but not on update: changing it would swap the
implementation under an existing row.

Schema: adds type and issuer_url to oauth_provider in the 4.23.0.0 to 24.0.0
upgrade file.

UI: Login.vue renders a button per registered oidc provider (in addition to the
existing google/github/keycloak buttons), labelled "Sign in with ". Clicking it
reads the issuer's authorization_endpoint from discovery and starts the
authorization-code flow. As with the keycloak provider, the registered redirecturi must
carry verifyOauth (for example https://<ui-host>/client?verifyOauth) so the callback
lands on the verify handler.

Fixes: #9609

Types of changes

Breaking change (fix or feature that would cause existing functionality to change)
New feature (non-breaking change which adds functionality)
Bug fix (non-breaking change which fixes an issue)
Enhancement (improves an existing feature and functionality)
Cleanup (Code refactoring and cleanup, that may add test cases)
Build/CI
Test (unit or integration test code)

Feature/Enhancement Scale or Bug Severity

Feature/Enhancement Scale

Major
Minor

Screenshots (if appropriate):

How Has This Been Tested?

Unit tests - oauth2 module, 103 tests green.

GenericOIDCOAuth2ProviderTest (27 tests) generates an RSA keypair, publishes the
matching JWKS, and asserts that a genuinely signed token is accepted while these are
rejected: a token with altered claims, one signed by a different key, one naming a kid
absent from the JWKS, and issuer / audience / expiry mismatches. Also covers discovery
document validation (issuer mismatch) and that a verified code is redeemed exactly once.
OAuth2AuthManagerImplTest covers the type fallback, an unknown type rejected at
register time, and a real bean name winning without a DB lookup.
Vendor provider tests updated for the name-carrying signatures.
DatabaseUpgradeCheckerTest green with the new schema file.

Integration - KVM advanced zone against Keycloak 25. Registered an oidc provider
pointing at a Keycloak realm and logged a real user in through the Keycloak form:
verifyOAuthCodeAndGetUser validates the RS256 signature against the realm JWKS and
returns the email, oauthlogin with the same code issues the session, and
listOauthProviders reports the generically-named provider as enabled.

How did you try to break this feature and the system with this change?

A login presenting a valid, correctly signed token but claiming a different CloudStack
user's email - rejected, no session.
Replay of an already-consumed code - rejected, no session.
A bogus/garbage code - rejected, no session.
After each of the above, a fresh correct login still succeeds.
Existing google/github/keycloak registrations are untouched and still log in
(name-based dispatch, null type).
Discovery document whose issuer does not match the configured issuer URL - rejected.

nagaboinaramgopal · 2026-09-18T15:28:41Z

This is the generic OIDC provider from the discussion on #13854: one oidc type that serves any number of registrations under admin-chosen names, with discovery and full id_token validation, so a new IdP no longer needs its own class.

It overlaps #13499 (ForgeRock), which @bddvlpr put on hold in favour of doing the generic feature. My GenericOIDCOAuth2Provider is separate from the AbstractOIDCOAuth2Provider there, but three files touch the same code: RegisterOAuthProviderCmd, spring-oauth2-context.xml and Login.vue. Whichever lands second is a small rebase and I am happy for that to be mine.

@bddvlpr @Damans227 this builds on your design, so please review. If you would rather fold the ForgeRock case in here as an oidc registration, or keep it as a named provider on top, either works.

nagaboinaramgopal · 2026-09-21T15:53:37Z

@DaanHoogland @weizhouapache Could you pls take a look

DaanHoogland · 2026-09-24T10:54:47Z

@blueorangutan package

codecov · 2026-09-24T11:00:21Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 3.70%. Comparing base (1a48a87) to head (a8db372).

❗ There is a different number of reports uploaded between BASE (1a48a87) and HEAD (a8db372). Click for more details.

HEAD has 1 upload less than BASE

Flag BASE (1a48a87) HEAD (a8db372)

unittests 1 0

Additional details and impacted files

@@              Coverage Diff              @@
##               main   #14205       +/-   ##
=============================================
- Coverage     19.91%    3.70%   -16.21%     
=============================================
  Files          6373      487     -5886     
  Lines        577230    42001   -535229     
  Branches      70696     7943    -62753     
=============================================
- Hits         114950     1558   -113392     
+ Misses       449713    40217   -409496     
+ Partials      12567      226    -12341

Flag	Coverage Δ
uitests	`3.70% <ø> (-0.01%)`	⬇️
unittests	`?`

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

github-actions · 2026-09-24T11:23:06Z

This pull request has merge conflicts. Dear author, please fix the conflicts and sync your branch with the base branch.

github-actions · 2026-09-28T17:24:43Z

This pull request has merge conflicts. Dear author, please fix the conflicts and sync your branch with the base branch.

Copilot

Copilot review overview

🟡 Changes recommended

Authentication state handling, domain cache isolation, and several OIDC interoperability issues must be corrected.

Review effort: Balanced
Findings: 3 · 4 · 3

Open (10)

Include domain identity in one-time cache keys · New
Require verified email claims for login · New
Validate cryptographically random OAuth state · New
Normalize persisted registration type · New
Preserve and restore global provider list · New
Resolve OIDC discovery server-side · New
Preserve existing authorization endpoint query parameters · New
Use 24.0.0 in parameter since metadata · New
Use 24.0.0 in parameter since metadata · New
Use 24.0.0 in since metadata · New

What changed in this PR

Adds reusable generic OIDC authentication, separating provider labels from implementation types.

Changes:

Adds OIDC discovery, token validation, and registration-type dispatch.
Extends schema and APIs with provider type and issuer URL.
Adds generic OIDC login UI and tests.

File	Description
`ui/src/views/auth/Login.vue`	Adds generic OIDC login buttons and discovery.
`ui/public/locales/en.json`	Adds OIDC login messages.
`ui/public/assets/oidc.svg`	Adds the OIDC logo.
`plugins/user-authenticators/oauth2/src/test/java/org/apache/cloudstack/oauth2/oidc/GenericOIDCOAuth2ProviderTest.java`	Tests OIDC validation and code caching.
`plugins/user-authenticators/oauth2/src/test/java/org/apache/cloudstack/oauth2/OAuth2UserAuthenticatorTest.java`	Updates provider-aware authentication tests.
`plugins/user-authenticators/oauth2/src/test/java/org/apache/cloudstack/oauth2/OAuth2AuthManagerImplTest.java`	Tests type-based provider dispatch.
`plugins/user-authenticators/oauth2/src/main/resources/META-INF/cloudstack/oauth2/spring-oauth2-context.xml`	Registers the generic OIDC bean.
`plugins/user-authenticators/oauth2/src/main/java/org/apache/cloudstack/oauth2/vo/OauthProviderVO.java`	Maps type and issuer fields.
`plugins/user-authenticators/oauth2/src/main/java/org/apache/cloudstack/oauth2/oidc/GenericOIDCOAuth2Provider.java`	Implements generic OIDC authentication.
`plugins/user-authenticators/oauth2/src/main/java/org/apache/cloudstack/oauth2/OAuth2UserAuthenticator.java`	Passes registration context during login.
`plugins/user-authenticators/oauth2/src/main/java/org/apache/cloudstack/oauth2/OAuth2AuthManagerImpl.java`	Resolves providers by registration type.
`plugins/user-authenticators/oauth2/src/main/java/org/apache/cloudstack/oauth2/OAuth2AuthManager.java`	Extends the manager contract.
`plugins/user-authenticators/oauth2/src/main/java/org/apache/cloudstack/oauth2/api/response/OauthProviderResponse.java`	Exposes type and issuer URL.
`plugins/user-authenticators/oauth2/src/main/java/org/apache/cloudstack/oauth2/api/command/UpdateOAuthProviderCmd.java`	Supports issuer URL updates.
`plugins/user-authenticators/oauth2/src/main/java/org/apache/cloudstack/oauth2/api/command/RegisterOAuthProviderCmd.java`	Supports generic OIDC registration.
`plugins/user-authenticators/oauth2/src/main/java/org/apache/cloudstack/oauth2/api/command/ListOAuthProvidersCmd.java`	Reports type-backed providers correctly.
`engine/schema/src/main/resources/META-INF/db/schema-42300to2400.sql`	Adds type and issuer columns.
`api/src/main/java/org/apache/cloudstack/auth/UserOAuth2Authenticator.java`	Adds registration-aware default methods.
`api/src/main/java/org/apache/cloudstack/api/ApiConstants.java`	Adds the issuer URL API constant.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

        Long domainId = normalizeGlobalScope(resolveDomainIdFromIdOrPath(cmd.getDomainId(), cmd.getDomainPath()));
        String authorizeUrl = StringUtils.trim(cmd.getAuthorizeUrl());
        String tokenUrl = StringUtils.trim(cmd.getTokenUrl());
+        String type = StringUtils.trim(cmd.getType());


Damans227

can you rebase? there are conflicts with main

The OAuth2 plugin resolves a login to a UserOAuth2Authenticator through a fixed provider-name to Spring-bean map, and each OIDC vendor is its own bean running the same authorization-code flow with no vendor-specific logic. A new IdP needs a new class, and since provider is both the display name and the routing key, a domain can register only one keycloak. This adds a type column to oauth_provider. OAuth2AuthManagerImpl looks the name up in the bean map first and only on a miss falls back to the registration's type, so provider becomes an admin-chosen label and type selects the implementation. One bean then serves any number of registrations under arbitrary names. Existing google, github and keycloak rows carry a null type and dispatch by name as before. GenericOIDCOAuth2Provider is registered under type oidc and configured with the issuer URL. It reads the token and JWKS endpoints from the issuer's discovery document (the issuer must match), and validates the id_token before trusting it: signature against the JWKS key named by the token kid, then issuer, audience and expiry, using the CXF JOSE library already on the classpath. It holds no token state between logins, and a code verified through verifyOAuthCodeAndGetUser is redeemed once so the following oauthlogin does not re-present it. ListOAuthProvidersCmd and UpdateOAuthProviderCmd derived the response enabled flag from a name-to-bean check, which reported every generically-named registration as disabled; both now also accept a registration whose type resolves to a plugin. The schema change adds type and issuer_url to oauth_provider in the 4.23.0.0 to 24.0.0 upgrade file. Login.vue renders the OAuth buttons from the registered provider list so a generic oidc provider gets a Sign in with <label> button and starts the flow from the issuer's authorize endpoint, resolved from discovery.

nagaboinaramgopal · 2026-10-01T17:04:48Z

Thanks @Damans227, good catch. I've rebased it onto the latest main now, so the conflicts should be gone. Please let me know if you spot anything else.

- fall back to the id_token header algorithm when a published JWK omits alg (Entra ID does this), so verification no longer fails for those providers - cache the JWKS per issuer like the discovery document, refetching once on an unknown key id for rotation, instead of fetching on every login - reject registering an OIDC type under a name reserved by a built-in provider, where the name would shadow the type during dispatch - log the provider's raw token-exchange error server side and return a generic message to the caller

- require a verified email (email_verified) in the id_token before using it as the account identity, so an unverified address cannot claim a user - key the single-use verified-email cache by domain as well, so a code verified for one domain cannot be consumed for another - store the provider type lowercased so list, update and the UI agree with the case-insensitive dispatch lookup - correct the since metadata on the new type/issuerUrl parameters and response fields from 4.24.0 to 24.0.0

DaanHoogland · 2026-10-02T14:44:18Z

@blueorangutan package

blueorangutan · 2026-10-02T14:46:05Z

@DaanHoogland a [SL] Jenkins job has been kicked to build packages. It will be bundled with no SystemVM templates. I'll keep you posted as I make progress.

blueorangutan · 2026-10-02T15:42:52Z

Packaging result [SF]: ✖️ el8 ✖️ el9 ✖️ debian ✖️ suse15. SL-JID 19384

boring-cyborg Bot added component:api component:UI labels Sep 18, 2026

github-actions Bot added the status:has-conflicts label Sep 24, 2026

nagaboinaramgopal force-pushed the feature/generic-oidc-provider branch from 2725b94 to 876bd68 Compare September 25, 2026 18:39

github-actions Bot added status:has-conflicts and removed status:has-conflicts labels Sep 25, 2026

nagaboinaramgopal force-pushed the feature/generic-oidc-provider branch from 876bd68 to 2a72050 Compare September 29, 2026 15:40

github-actions Bot removed the status:has-conflicts label Sep 29, 2026

DaanHoogland requested a balanced review from Copilot October 1, 2026 15:41

Copilot started reviewing on behalf of DaanHoogland October 1, 2026 15:49 View session

Copilot AI reviewed Oct 1, 2026

View reviewed changes

Damans227 reviewed Oct 1, 2026

View reviewed changes

nagaboinaramgopal force-pushed the feature/generic-oidc-provider branch from 2a72050 to f98eb11 Compare October 1, 2026 17:04

Damans227 mentioned this pull request Oct 1, 2026

Forgerock OAuth provider #13499

Closed

2 of 14 tasks

nagaboinaramgopal mentioned this pull request Oct 2, 2026

oauth2: OIDC login nonce and per-attempt CSRF state #14296

Draft

1 of 7 tasks

Conversation

nagaboinaramgopal commented Sep 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Types of changes

Feature/Enhancement Scale or Bug Severity

Feature/Enhancement Scale

Screenshots (if appropriate):

How Has This Been Tested?

How did you try to break this feature and the system with this change?

Uh oh!

nagaboinaramgopal commented Sep 18, 2026

Uh oh!

nagaboinaramgopal commented Sep 21, 2026

Uh oh!

DaanHoogland commented Sep 24, 2026

Uh oh!

codecov Bot commented Sep 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

github-actions Bot commented Sep 24, 2026

Uh oh!

github-actions Bot commented Sep 28, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Damans227 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nagaboinaramgopal commented Oct 1, 2026

Uh oh!

DaanHoogland commented Oct 2, 2026

Uh oh!

blueorangutan commented Oct 2, 2026

Uh oh!

blueorangutan commented Oct 2, 2026

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

nagaboinaramgopal commented Sep 18, 2026 •

edited

Loading

codecov Bot commented Sep 24, 2026 •

edited

Loading