[FEAT-DATSET-14] InvenioRDM Credential Management

[sven1103]

Summary

Implements two user stories from FEAT-DATASET-CONNECTION:

• FEAT-DATSET-14: Add credentials for an InvenioRDM instance

  As a researcher, I want to provide my access token for an available InvenioRDM instance, so that I can connect access-restricted resources in a project.

• FEAT-DATSET-15: Remove credentials for a configured InvenioRDM instance

  As a researcher, I want to remove my access token for an available InvenioRDM instance, because the token is not valid anymore.

These are prerequisites for FEAT-DATSET-05/06 (connecting/viewing restricted datasets). No dependency on other stories.

---

What is implemented

Commit 1 — Credential infrastructure (Checkpoints 1-9)

Schema & Config

• New user_external_credential table — source-agnostic (source_type + instance_id + user_id), supports future providers without schema changes
• Vault config property qbic.security.vault.external-credential.key-alias for dedicated AES master key

Encryption (ADR-0002 S2)

• CredentialEncryptor port (application layer) + AesGcmCredentialEncryptor impl (AES/GCM/NoPadding, 256-bit key, 96-bit nonce, 128-bit tag)
• 10 unit tests: roundtrip, nonce uniqueness, wrong-key failure, corruption detection, key-size validation

Domain model

• UserExternalCredential entity + CredentialStatus enum (VALID / INVALIDATED)
• UserExternalCredentialRepository port + Spring Data JPA impl

Validation layer (composite dispatcher)

• ExternalCredentialValidator port (application layer)
• CredentialValidatorAdapter interface (infrastructure, per-provider)
• InvenioRdmCredentialValidatorAdapter — validates via GET /api/users per InvenioRDM OpenAPI spec (operationId: getAUserById)
• SourceTypeDispatchingCredentialValidator — routes by SourceType, extensible for future providers by adding one bean entry
• CredentialValidationException for transient failures

Client enhancements

• InvenioRdmClient.getAuthenticatedUser() — new endpoint
• InvenioRdmClient.search() / getRecord() — auth-header overloads (backward-compatible)
• SourceInstanceDescriptor extended with sourceType field

Application service

• ExternalCredentialService interface + DefaultExternalCredentialService
• Sealed AddCredentialResult: Success / InvalidToken / ServiceError / UnknownInstance
• Token zeroed in finally block after every call

Spring wiring

• InvenioRdmConfiguration registers all new beans
• Dispatcher configured for INVENIO_RDM today; adding a future provider = implement adapter + register one entry

Commit 2 — UI: Add credentials (Checkpoint 10)

/external-providers route (ExternalProvidersMain)

• Benefit text (AC-6): explains that tokens enable connection of access-restricted datasets
• Instance list loaded from ExternalCredentialService.listCredentialStatuses() — iterates all configured instances
• Status indicators: green check for connected, red X for not configured
• Add Token dialog: PasswordField with no echo, validate-then-save flow, token field cleared on dialog close
• Help text links to standard InvenioRDM token creation page
• Generic toast notifications for success, invalid token, and transient errors (no upstream details leaked to the user)

Commit 3 — UI: Remove credentials (FEAT-DATSET-15)

Disconnect flow (ExternalProvidersMain)

• Disconnect button on each connected/invalidated instance card — VaadinIcon.TRASH, tertiary + error styling
• Confirmation dialog (AlertDialog) — warns the user that the token will be removed and reconnection will be required; requires explicit "Disconnect" confirmation or "Cancel" to abort
• performDisconnect() — calls credentialService.removeCredential(userId, instanceId), shows a toast on success or when no token was found, then re-renders the page
• Card re-renders as "Not connected" — grey tag, descriptive text ("Connect your account to link …"), and a "Connect" button replacing the former "Disconnect" button
• VerificationSidebar refresh — if the sidebar is open during disconnect, it is refreshed to reflect the new NOT_CONFIGURED state

Application service (DefaultExternalCredentialService.removeCredential())

• Resolves the instance from the SourceInstanceRegistry, looks up the credential by user/source-type/instance, and delegates to UserExternalCredentialRepository.deleteByUserIdAndSourceTypeAndInstanceId() (physical row delete)
• Returns true if a credential was removed, false if none existed
• After removal, InvenioRdmDatasetSource.resolveTokenForUser() returns null for that user/instance — no Authorization header is sent, so InvenioRDM will not return access-restricted records

---

Acceptance Criteria status

FEAT-DATSET-14 — Add credentials

AC	Status	Notes
AC-1: User navigates to "External Providers"	✅ Done	Route: /external-providers under UserMainLayout
AC-2: System displays configured instances	✅ Done	Loaded from SourceInstanceRegistry (admin-configured via application.properties)
AC-3: Token validated against InvenioRDM via API	✅ Done	GET /api/users with Bearer auth; 200 = valid
AC-4: Invalid token not added, user informed	✅ Done	Generic "Token validation failed" toast; no token persisted
AC-5: Valid token added, instance connected	✅ Done	"Token validated successfully" toast; status shown as VALID
AC-6: Benefit description shown	✅ Done	Paragraph at top of page explains access-restricted dataset connection

FEAT-DATSET-15 — Remove credentials

AC	Status	Notes
AC-1: Token deleted, restricted access prevented	✅ Done	Full stack: UI → removeCredential() → JPA delete → downstream token resolution returns null (no auth header sent)
AC-2: User informed of successful removal	✅ Done	Toast notification shown after disconnect
AC-3: Config section reflects removal	✅ Done	Card re-renders as "Not connected" with grey tag, descriptive text, and "Connect" button; sidebar refreshed if open

---

Architecture decisions (from ADRs)

• ADR-0002 S2: Master AES-256 key in PKCS12 vault; per-token AES-GCM blobs in DB (HA-safe)
• ADR-0002 D1: Decryption boundary — plaintext token char[] exists only in infrastructure adapter methods, zeroed after use
• ADR-0002 I2: Instances admin-configured (no UI entry)
• ADR-0002 P2: Stateless DatasetSource port, instance-parameterised
• ADR-0002 T1: Per-user-per-instance tokens, never-borrow-credentials
• Composite dispatcher: Adding a second provider = implement CredentialValidatorAdapter + one bean entry in InvenioRdmConfiguration

---

Security measures

Vector	Mitigation
At-rest	AES-256-GCM with per-token random nonce; dedicated master key in PKCS12 vault
In-flight	HTTPS only (all target instances)
In-memory	Plaintext token as char[], zeroed in finally block
Layer boundary	Application service never holds plaintext beyond the add/validate call scope
Logging	Token values never logged; only user ID + instance ID
Error messages	Generic user-facing; raw upstream errors to server logs only
UI	PasswordField, no echo, field cleared on dialog close
Removal	Physical row delete; confirmation dialog prevents accidental disconnect

---

Files changed

Layer	Files
Schema	sql/migrations/create-user-external-credential.sql, sql/complete-schema.sql
Config	application.properties
Application ports	ExternalCredentialService, ExternalCredentialValidator, CredentialEncryptor, CredentialValidationException, DefaultExternalCredentialService
Domain	UserExternalCredential, CredentialStatus, UserExternalCredentialRepository
Infrastructure	AesGcmCredentialEncryptor, SourceTypeDispatchingCredentialValidator, CredentialValidatorAdapter, InvenioRdmCredentialValidatorAdapter, UserExternalCredentialJpaRepository, UserExternalCredentialRepositoryImpl, InvenioRdmClient (extensions)
Views	ExternalProvidersMain, VerificationSidebar, TokenInput
Wiring	InvenioRdmConfiguration, PropertiesBackedSourceInstanceRegistry, SourceInstanceDescriptor
Tests	AesGcmCredentialEncryptorSpec (10 tests)
Docs	docs/implementation-plan/feat-datset-14-*

---

Verification

• Full compile: BUILD SUCCESS
• 263/263 tests pass (0 failures, 0 errors)
• 10 new AesGcmCredentialEncryptorSpec tests pass

---

Deferred

• Checkpoint 11 integration smoke test (requires live DB + Spring context, planned for CI)
• i18n message keys for toast notifications

---

Checklist

See docs/implementation-plan/feat-datset-14-checklist.md for the per-checkpoint reviewer checklist.

[sven1103]

I think this better be an enum, I dont see the benefit of having free text values passing around for a confined set of values.

[KochTobi]

Warning: Different store and key passwords not supported for PKCS12 KeyStores. Ignoring user-specified -keypass value.

The listed command does not work and fails with the mentioned error. Afterwards, an alias for external-credential-master-key is in the keytool but with unknown content.

[KochTobi]

❯ echo "$AES_KEY" | keytool -importpass \
-alias external-credential-master-key \
-keystore keystore.p12 \
-storepass $DATAMANAGER_VAULT_KEY \
-storetype PKCS12
Enter the password to be stored:  Re-enter password: They don't match. Try again
Enter the password to be stored:  Re-enter password:     

When not choosing a keypass, the key stays empty and I get an java.lang.IllegalArgumentException: Empty key when starting the app. It is good that this is checked and highlights that the command provided here did not work as intended.

[KochTobi]

the echo $AES_KEY command works

[KochTobi]

Please replace the command by the correct one

keytool --importpass \
  -alias external-credential-master.jey \
  -keystore keystore.p12 \
  -storepass $DATAMANAGER_VAULT_KEY \

and then entering the value of the AES_KEY as password for the entry

[KochTobi]

Please replace the command by the correct one

keytool --importpass \
  -alias external-credential-master.jey \
  -keystore keystore.p12 \
  -storepass $DATAMANAGER_VAULT_KEY \

and then entering the value of the AES_KEY as password for the entry

[KochTobi]

Please refine the migration guide. The functionality provided by this PR is great!

[KochTobi]

Great improvements!
For me the command mentioned in the NEXT.md did not work. Did you verify that piping works in this case?

[KochTobi]

lgtm