Skip to content

feat: add API token authentication for REST API access#8402

Open
cnewkirk wants to merge 1 commit into
OpenNMS:release-35.xfrom
cnewkirk:api-tokens-clean-tmp
Open

feat: add API token authentication for REST API access#8402
cnewkirk wants to merge 1 commit into
OpenNMS:release-35.xfrom
cnewkirk:api-tokens-clean-tmp

Conversation

@cnewkirk
Copy link
Copy Markdown
Contributor

Summary

Adds API token authentication to OpenNMS Horizon, allowing users to generate long-lived bearer tokens as an alternative to basic auth for REST API access.

  • Tokens are cryptographically secure: 32 random bytes, hex-encoded with an onms_ prefix (enabling secret scanning), stored as SHA-256 hashes only — plaintext is shown once at creation and never retrievable again
  • Tokens have configurable expiry with an admin-enforced maximum (org.opennms.api.tokens.max-expiry-days, default 365)
  • Admins can create, list, and revoke tokens for any user; users can manage their own
  • Three access points: REST API (/api/v2/apiTokens), web UI (self-service + admin pages), and Karaf shell commands
  • Token auth inherits the user's full role set, matching existing basic auth behavior
  • last_used_at is updated on successful authentication, debounced to avoid write amplification

Changes

  • features/api-tokens/ — new Maven module (api, impl, shell submodules): ApiToken entity, ApiTokenDao, ApiTokenService, ApiTokenServiceImpl, Karaf shell commands
  • features/springframework-security/ApiTokenAuthenticationFilter added to all four REST <http> blocks via <custom-filter before="BASIC_AUTH_FILTER">
  • opennms-webapp-rest/ApiTokenRestService JAX-RS resource at /api/v2/apiTokens
  • opennms-webapp/ — self-service JSP (/account/selfService/apiTokens.jsp) and admin JSP (/admin/userGroupView/users/apiTokens.jsp)
  • core/schema/ — Liquibase changeset adding api_tokens table
  • container/features/opennms-api-tokens Karaf feature definition
  • smoke-test/ApiTokenIT covering auth, lifecycle, admin ops, validation, and bulk revocation

Test plan

  • Unit tests: ApiTokenServiceImplTest (9 tests), ApiTokenAuthenticationFilterTest (8 tests)
  • Smoke tests: ApiTokenIT — run with -Dsmoke -Dtest=ApiTokenIT
  • Manual verification: basic auth still works, bearer tokens authenticate, revoked tokens are rejected, JSP pages render and function

@github-actions github-actions Bot added the docs label Mar 29, 2026
@github-actions github-actions Bot requested a review from indigo423 March 29, 2026 07:03
@marshallmassengill
Copy link
Copy Markdown
Contributor

This should be for: NMS-19642

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants