Enhance badge API to require authorization

[SaberStrat]

Description

Enables Dependency-Track to offer badges in a secure manner and change the badge API from an opt-in-able, unauthenticated one into one requiring authentication with the new permission VIEW_BADGES, either via HTTP header or URI query parameter.

In the currently implementation, this as a breaking change (see Additional Details.)

Addressed Issue

Closes #3596

Additional Details

As a first for DT's API, badges will allow authentication via URI query parameter, as badges are often retrieved from/embedded in clients that do not easily support an injection of headers.

The securing of badges behind API authentication and ACL can be done in two ways, either as a breaking change or gracefully with backwards compatibility: implement authentication with a new permission and

1. remove current checkbox enabling unauthenticated badges support entirely (breaking change)
2. keep a checkbox, but redo it to switch between the settings (backwards compatible change):
   1. disable unauthenticated access (allows authenticated access only, corresponds to the previous "off" setting right after updating to the new DT version containing this PR)
   2. enable unauthenticated access (corresponds to the previous "on" setting)

A grace period is nice. But because the previous way of offering badges represents a security flaw, I would've preferred to make users switch to authenticated badges requests right away.

Downstream changes

DependencyTrack/frontend#967

Upstream requirements

stevespringett/Alpine#641

Checklist

• I have read and understand the contributing guidelines
• This PR fixes a defect, and I have provided tests to verify that the fix is effective
• This PR implements an enhancement, and I have provided tests to verify that it works as intended
• This PR introduces changes to the database model, and I have added corresponding update logic
• This PR introduces new or alters existing behavior, and I have updated the documentation accordingly

[codacy-production]

Coverage summary from Codacy

See diff coverage on Codacy

Coverage variation	Diff coverage
✅ +0.00% (target: -1.00%)	✅ 100.00% (target: 70.00%)

Coverage variation details

	Coverable lines	Covered lines	Coverage
Common ancestor commit (b8d4866)	21934	17253	78.66%
Head commit (8c40c9a)	21931 (-3)	17250 (-3)	78.66% (+0.00%)

Coverage variation is the difference between the coverage for the head and common ancestor commits of the pull request branch: <coverage of head commit> - <coverage of common ancestor commit>

Diff coverage details

	Coverable lines	Covered lines	Diff coverage
Pull request (#4059)	34	34	100.00%

Diff coverage is the percentage of lines that are covered by tests out of the coverable lines that the pull request added or modified: <covered lines added or modified>/<coverable lines added or modified> * 100%

See your quality gate settings    Change summary preferences

_{Codacy stopped sending the deprecated coverage status on June 5th, 2024. Learn more}

[SaberStrat]

Forgot readying the PR for the frontend, will remain a draft until then

[nscuro]

@SaberStrat master has Alpine 3.1.0 now, which includes the change required for this.

[SaberStrat]

Not sure how to repro the error locally. The unit tests are successful.

[nscuro]

Just a flaky test. I restarted CI workflow.

[nscuro]

Looks good, and I agree with your assessment of intentionally making this a breaking change due to the security implications of the current implementation.

In the original issue, Steve suggested to create a default team with the VIEW_BADGE permission. I think we should follow that. You can add a new default team here:

dependency-track/src/main/java/org/dependencytrack/persistence/DefaultObjectGenerator.java

Lines 138 to 173 in edb95ce

	private void loadDefaultPersonas() {
	try (QueryManager qm = new QueryManager()) {
	if (!qm.getManagedUsers().isEmpty() && !qm.getTeams().isEmpty()) {
	return;
	}
	LOGGER.info("Adding default users and teams to datastore");
	LOGGER.debug("Creating user: admin");
	ManagedUser admin = qm.createManagedUser("admin", "Administrator", "admin@localhost",
	new String(PasswordService.createHash("admin".toCharArray())), true, true, false);
	LOGGER.debug("Creating team: Administrators");
	final Team sysadmins = qm.createTeam("Administrators", false);
	LOGGER.debug("Creating team: Portfolio Managers");
	final Team managers = qm.createTeam("Portfolio Managers", false);
	LOGGER.debug("Creating team: Automation");
	final Team automation = qm.createTeam("Automation", true);
	final List<Permission> fullList = qm.getPermissions();
	LOGGER.debug("Assigning default permissions to teams");
	sysadmins.setPermissions(fullList);
	managers.setPermissions(getPortfolioManagersPermissions(fullList));
	automation.setPermissions(getAutomationPermissions(fullList));
	qm.persist(sysadmins);
	qm.persist(managers);
	qm.persist(automation);
	LOGGER.debug("Adding admin user to System Administrators");
	qm.addUserToTeam(admin, sysadmins);
	admin = qm.getObjectById(ManagedUser.class, admin.getId());
	admin.setPermissions(qm.getPermissions());
	qm.persist(admin);
	}
	}

[nscuro]

Oh, and consider adding a migration to remove the badge.enabled column from the CONFIGPROPERTY table. Note that #4143 also edits this file so there might be merge conflicts.

[savek-cc]

As this is a breaking change:
Multiple projects are using the current badge feature to create overview tables in confluence.
Once we update to 4.12, this would be broken directly as I understand. Do you plan on enabling a smooth transition by making it possible to still use unauthenticated access for at least this one version for migration - so that both authenticated and the old way without authkey can co-exist for a grace period?
E.g. having an env_var like REALLY_BAD_IDEA_ENABLE_UNAUTHENTICATED_BADGES_FOR_THIS_ONE_VERSION?

[nscuro]

@SaberStrat Thoughts on @savek-cc's remarks? Would you be willing to refactor your work to enable backward-compatibility?

[savek-cc]

Maybe a different approach: Could we (in order to prepare for the preparation) create an AuthKey in DT 4.11 and include that in todays API requests (they would be ignored for now) and then give that team/API-key the new permission with DT 4.12?
So we could prepare (but not test) the transition with DT 4.11 and should be good once we update?

[SaberStrat]

Alright then.

Now I'll need help with organising the change in direction, i.e. project management decisions.
What would be the best way to turn this PR and its issue about a breaking change into a deprecation for (probably) 4.12 and a breaking change in a later version?

1. Repurpose it--i.e. edit their descriptions and continue on the branch--into a deprecation for 4.12. For the feature removal, create a new issue and PR that'll be for later (e.g. 4.13)
2. Keep it for the feature removal later, finish it and mark it for a future release (e.g. 4.13) and fix future conflicts for when we get closer to that release. For the deprecation for 4.12, create a new issue and PR.

[savek-cc]

I don't think it should be an either or (authenticated OR unauthenticated) - but rather an override to allow access without an API key if none is provided. If one is provided, it should be checked as currently implemented.
The idea is to enable the authentication and onboard the projects one after another - but keep the old links working (those without key) for the transition period. Once all status pages/projects did add their (in our case probably the same for all) authKey to the request, this override can be disabled.
The override can then be completely removed in e.g. 4.13.

So the change is as already implemented - but there is an override (e.g. as env-var) that makes it not only accept valid authKeys - but also the empty one (as in none supplied).

What are your thoughts?

[SaberStrat]

You mean as a configuration or property for the application like these here https://docs.dependencytrack.org/getting-started/configuration/?

So basically turning the current switch from an either-or into an enabler for unauthentic access and moving it from the UI into a property?

Unless I misunderstood, it would be a neat middle ground for everyone involved. Gives users a grace period, I don’t have to do as much extra coding (I think) and the setting is hidden a bit more, thus advertising the authentication-way more/authentication-less way less.

[savek-cc]

Correct - but even if that override is enabled, your code should still check the AuthKey - just on the "no auth key present" path there is an override to grant access anyway IF that config var is set. Everything in the UI stays as currently implemented in your PR. Code changes should(?) be minimal and not require you to rework a lot.

This way, projects can already start using (and testing - as an invalid key would still be rejected) the new authentication.

@nscuro your thoughts?

[nscuro]

Wouldn't it be easier to just leave the existing badge.enabled toggle in place then?

Off: Disable unauthenticated, allow authenticated+authorized
On: Enable unauthenticated, allow authenticated+authorized

Users who already have it enabled won't have to do anything when upgrading to v4.12.

For v4.13, we remove this toggle and only allow authenticated access.

I think moving the toggle from UI to env vars in v4.12 will just be confusing.

[savek-cc]

Wouldn't it be easier to just leave the existing badge.enabled toggle in place then?

Looking at the current documentation https://docs.dependencytrack.org/integrations/badges/ I too think that this is the best idea. The current option is specifically about enabling unauthenticated access (pre 4.12)- and there is no need to disable badges if the only access is authenticated (4.13+).
So we add authenticated access independent of config - and make clear that the "unauthenticated access" toggle feature will go away with 4.13 in the release notes?

[SaberStrat]

Then I’m modifying this PR and issue and its frontend counterpart and create a separate pair for the removal for 4.13?

[nscuro]

@SaberStrat Yeah I think that would be the easiest.

[nscuro]

@SaberStrat Do you have a rough idea as to how soon you'd be able to complete this work? No pressure, just curious WRT planning the v4.12 release.

[SaberStrat]

@nscuro Estimate by feeling: good case this week, bad case by end of next week. What’s the deadline for v4.12?

[nscuro]

We were hoping for early next week, since the next community meeting is on Wednesday.

[SaberStrat]

I'm actually struggling to come up with a way to toggle authentication on and off for a resource at runtime.

DT is using alpine-server to apply an authentication filter for incoming requests, which has the method annotation @AuthenticationNotRequired to deactivate that filter for requests of that method.

Previously, the 'Badges-way' was implemented like this: deactivate authentication in general for all methods of the resource with that annotation (static), and the ConfigProperty/general setting toggle made the resource methods return an empty body (dynamic)

Now what we want is for the toggle to basically do what the annotation did, but let the user control it, at runtime, i.e. dynamically. I'd either need to inject and query state of a ConfigProperty either in alpine-server or somewhere in DT where Alpine classes plug into DT. Or maybe work with Reflections and modify the annotation at runtime?

Either way, my thoughts lead down complicated paths with lots of effort, that I'm not sure is justifiable for a temporary deprecation. I'd be thankful for suggestions of justifiable implementations. Otherwise, I'm at the point where @savek-cc's idea of adding a apiKey query parameter to badge requests in 4.11 sounds more reasonable 😅 .

[nscuro]

I think you could simply implement the permission check "manually" in the method body, instead of relying on the annotation.

There is a qm.hasPermission method that you can use, and getPrincipal gets you access to the user or API key if you need it (note: will be null for unauthenticated access).

You can access the apiKey parameter using the @QueryParam annotation as usual.

Yes it's a bit of duplicated code, but ultimately it's not a lot, and it's only in this specific endpoint, and only for v4.12. So I believe this is a reasonable option.

[nscuro]

Looks good @SaberStrat! Could you please look into fixing the failing tests? Happy to merge once those are resolved.

 Error:  Failures: 
Error:    DefaultObjectGeneratorTest.testContextInitialized:38->testLoadDefaultPersonas:96 expected:<3> but was:<4>
Error:    DefaultObjectGeneratorTest.testLoadDefaultPersonas:96 expected:<3> but was:<4>

[SaberStrat]

I think you could simply implement the permission check "manually" in the method body, instead of relying on the annotation.

There is a qm.hasPermission method that you can use, and getPrincipal gets you access to the user or API key if you need it (note: will be null for unauthenticated access).

You can access the apiKey parameter using the @QueryParam annotation as usual.

Yes it's a bit of duplicated code, but ultimately it's not a lot, and it's only in this specific endpoint, and only for v4.12. So I believe this is a reasonable option.

Thank you for the help! It makes sense and goes in a similar direction that ACL is implemented in the badge resource.

[SaberStrat]

Can't repro the test failure locally.

[nscuro]

Likely flaky. Triggered a re-run of the workflow.

[nscuro]

Seems like the CPAN registry is slow to respond, causing the test failure. Will merge, since the failing test is unrelated to this change.