Skip to content

feat(#1737): Add OAuth2 JWT authentication support via JAAS LoginModule - #1738

Merged
jbonofre merged 10 commits into
apache:mainfrom
jbonofre:gh-1737
Oct 20, 2026
Merged

jbonofre merged 10 commits into
apache:mainfrom
jbonofre:gh-1737

Conversation

@jbonofre

@jbonofre jbonofre commented Mar 8, 2026 •

Copy link
Copy Markdown
Member

Add OAuth2 JWT authentication to ActiveMQ through a JAAS LoginModule, in a new dedicated activemq-jaas-oauth2 module.

Clients pass the JWT access token as the password (or via OAuth2TokenCallback). The module verifies the signature against a JWKS endpoint, validates iss, exp and optionally aud, and maps claims to UserPrincipal / GroupPrincipal for use with the existing JaasAuthenticationPlugin.

Configuration (login.config)

Option Description
oauth2.jwksUrl (required) JWKS endpoint. Must use https.
oauth2.issuer (required) Expected iss claim
oauth2.audience Expected aud claim
oauth2.usernameClaim Claim used as username (default sub); it is the required claim
oauth2.groupsClaim Claim holding groups (default groups). Accepts a list or comma-separated string, and dotted paths for nested claims such as realm_access.roles
oauth2.networkConnectionGroups Comma-separated groups allowed to register a network connection (bridge). When set, a network connection from a user outside these groups is rejected, and a ConnectionPrincipal carrying the decision is added to the Subject so the broker can enforce it. When unset, network connections are not restricted by this module

Security notes

  • Only asymmetric signature algorithms (RSA, EC, EdDSA) are accepted; HMAC-signed tokens are rejected.
  • Failures return generic messages to the client; validation details are logged server-side only.
  • The password callback buffer is cleared after use.
  • Processors are cached per (jwksUrl, issuer, audience, usernameClaim), bounded to 100 entries.

Packaging

  • New module activemq-jaas-oauth2, included in the assembly under lib/optional (with nimbus-jose-jwt) and in NOTICE.
  • The binary LICENSE now lists Nimbus JOSE+JWT (NOTICE already did).
  • The default conf/login.config is unchanged. A sample activemq-jaas-oauth2 entry ships in examples/conf/login-oauth2.config. The jars must be copied to lib/ to use it.

Tests

OAuth2LoginModuleTest (40 tests) covers valid and invalid tokens, claim mapping, nested and unsupported group claims, https enforcement, and the network connection group check.

@jbonofre
jbonofre requested a review from jeanouii March 8, 2026 08:04
@jbonofre

jbonofre commented Mar 8, 2026

Copy link
Copy Markdown
Member Author

NB: this is a better approach imho to what I did initially in #1035 (with the same goal).

@jbonofre

jbonofre commented Mar 8, 2026

Copy link
Copy Markdown
Member Author

The test failure is related to #1741

@jeanouii jeanouii left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some small details. nothing important

jeanouii
jeanouii previously approved these changes Mar 9, 2026

@jeanouii jeanouii left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@mattrpav

Copy link
Copy Markdown
Contributor

-1 on merging this as part of the activemq-jaas module. This drags in 3rd party dependency to all deployments -- I think this should go into a activemq-jaas-oath2 module.

@mattrpav
mattrpav self-requested a review March 11, 2026 01:27

@mattrpav mattrpav left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this should go into a separate module and get deployed into an extras folder (with the 3rd party) dependency instead of installed into the classpath by default for every running broker.

@jbonofre

Copy link
Copy Markdown
Member Author

I think this should go into a separate module and get deployed into an extras folder (with the 3rd party) dependency instead of installed into the classpath by default for every running broker.

@mattrpav what is the concern about the Nimbus dependency in the JAAS module ?

At the end, regarding the ActiveMQ distribution, it will be a dependency like another (like Jetty or Rome for instance).

Your concern is about the "embedded" ActiveMQ service in application (BrokerService) ?

@jeanouii

jeanouii commented Mar 11, 2026 •

Copy link
Copy Markdown
Contributor

@mattrpav Using LinkedHashSet is a nice to have but not strictly required per spec. Actually Subject.getPrincipals() returns a Set, that's it. The rest is platform dependant. Our JaasAuthenticationBroker for instance gets all the principals and then iterates until it finds an instance of UserPrincipal.
The other login modules all rely on HashSet, so it is now inconsistent with other ActiveMQ LoginModule.

On the dependency, it will be in the final zip anyways, so until it becomes a problem, I'd prefer to keep in in activemq-jaas instead of creating another module for one class only. It is both simpler for us and for our users that don't have to know they need another module to use oauth2 tokens. We could go like this and if it's a problem split later on.
Jasypt is there as optional as well, so it's similar here. It won't be pulled as transitive dependency.
On the other hand, we have a full independant shiro module. Both are valid, Shiro has much more code, so that's understandable. activemq-jaas-oauth2 definitely makes sense, but it's one class for now so splitting now just makes it harder for us.

@jbonofre jbonofre linked an issue Mar 11, 2026 that may be closed by this pull request
@mattrpav

mattrpav commented Mar 14, 2026 •

Copy link
Copy Markdown
Contributor

but it's one class for now so splitting now just makes it harder for us.

I think this line of thinking 'it's just one class' is what gets us into dependency trouble as a project. Yes, it is one class in the ActiveMQ tree, but this pulls in several transitive dependencies-- not just the one listed as optional. Being a security-related component also increases the probability that it will get tagged w/ a vulnerability (or one of its transitive deps will).

I think it would be most correct to have separate modules per security mechanism (the shiro appoarch). We could do an activemq-jaas-extras, but that doesn't seem to make sense b/c rarely are multiple external security providers (used outside of local accounts).

@jbonofre

Copy link
Copy Markdown
Member Author

@mattrpav that's fair. I'm not a big fan of activemq-jaas-extras, I would prefer to have activemq-jaas-oauth2.

I will update the PR accordingly.

@jbonofre

Copy link
Copy Markdown
Member Author

@jeanouii @mattrpav I moved the OAuth2LoginModule in a dedicated activemq-oauth2 module.

@jbonofre
jbonofre requested review from jeanouii and mattrpav March 14, 2026 17:06
@jbonofre

Copy link
Copy Markdown
Member Author

NB: I will update the LICENSE/NOTICE to document nimbus.

@jbonofre

Copy link
Copy Markdown
Member Author

@cshannon @mattrpav I updated this PR:

  • now it's a isolated in a dedicated module (I included in the distribution with LICENSE/NOTICE updated, but not enabled by default, user has to configure the login.config)
  • I added support for network security

@cshannon

Copy link
Copy Markdown
Contributor

This is a very large change and I think it's better to target for 6.5.0 unless @mattrpav has time to review it in detail. We need to finish 6.4.0 and other bug fix releases ASAP and i won't have time to review something this large before then.

Given that this is security related, rushing is a bad idea because we don't want to get a bunch of CVE reports if something is missed so it probably needs more time for review

Comment thread assembly/src/release/conf/login.config Resolved
jbonofre and others added 9 commits October 19, 2026 07:50
…inModule

Add OAuth2LoginModule to activemq-jaas that validates JWT access tokens
using JWKS endpoint for signature verification. Clients pass the JWT as
the password field, and claims are mapped to UserPrincipal/GroupPrincipal
for seamless integration with the existing JaasAuthenticationPlugin.
…h2 module

Extract OAuth2 JWT authentication into its own activemq-oauth2 module
(similar to activemq-shiro) with package org.apache.activemq.oauth2.
Remove nimbus-jose-jwt dependency from activemq-jaas and assembly,
add activemq-oauth2 to parent modules/dependencyManagement and assembly.
Include commented-out OAuth2 configuration example in the distribution
login.config.
…etric algorithms, nested groups, safer errors)
… connection group check, update binary LICENSE
@jbonofre

Copy link
Copy Markdown
Member Author

@cshannon @mattrpav are we good to include in 6.4.0 (as it's addition, I think it's fine, I will just check LICENSE/NOTICE) or do you prefer 6.5.0?

@cshannon

Copy link
Copy Markdown
Contributor

it's probably fine for 6.4.0, maybe we can mark it as experimental/beta in the docs and the code? We have the Experimental annotation we could use just to let people know it's new and needs some testing

@jbonofre

Copy link
Copy Markdown
Member Author

@cshannon agree to flag as experimental. Let me do it 😄

@jbonofre

Copy link
Copy Markdown
Member Author

@cshannon I added experimental in the code and docs.

@mattrpav mattrpav left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@jbonofre
jbonofre merged commit ec05f19 into apache:main Oct 20, 2026
10 checks passed
@github-project-automation github-project-automation Bot moved this from In review to Done in Apache ActiveMQ v6.4.0 Oct 20, 2026
@jbonofre
jbonofre deleted the gh-1737 branch October 20, 2026 16:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

No open projects
Status: Done

Development

Successfully merging this pull request may close these issues.

Add OAuth2 support

4 participants