The road to Passbolt version 5 - Getting started with the new resource types (beta)

Passbolt 5 introduces a full redesign together with major changes to the security model. At the heart of these changes is encrypted metadata, the foundation on which the new resource types and capabilities (such as multiple urls, icons, custom fields, etc.) are built. 

As of version 5.3.0, organisations keen to explore new resource types can already enable them, test the new capabilities, and plan their rollout steps through the available configuration settings. If you are an existing passbolt user but are new to this topic, check out this introduction article for more background.

Requirements:

• Passbolt API >= version 5.3.0
• Passbolt API self hosted

Why are the new resource types not enabled by default?

While this new architecture has already passed a full Cure53 security audit (see the report), it will stay in beta for a few more weeks. The beta label will be removed once the last rough edges are polished, tentatively scheduled for version 5.4 in August. 

To help you decide when the feature set is ready for your environment, here is the remaining work scheduled for Passbolt 5.4:

• Streamline administrator onboarding and guidance. Improve the first‑time experience and give administrators clearer steps for turning on the new resource types.
• KeePass (KDBX) import and export. Add support for icons, multiple URIs, and custom fields when exchanging data with KeePass. Many community members rely on KeePass as a backup or complementary tool, so this integration is essential.
• Fix latest performance hurdles. Most importantly we need to fix a bug in the cache system, when the cache becomes corrupted, in order for clients not to experience performance degradation.
• Zero‑knowledge mode. Offer an option to keep metadata fully confidential and not accessible to the server, for organisations that favour confidentiality over auditability. Read more about it here.
• Metadata key rotation. Provide an administrative mechanism for rotating the key used to encrypt shared resources metadata.

Even after these items ship in version 5.4, some gaps will remain that you may want to evaluate before enabling the feature:

• Cryptographic verification of metadata origin. A signature mechanism is planned to confirm who encrypted each piece of metadata. Cure53 flagged this as an outstanding risk. A mitigation is in the work, see the proposal for details.
• Limited auditability. Organisations that rely on syslog or custom SIEM integrations will lose visibility into operations on v5 content because metadata remains encrypted.
• Passbolt  CLI compatibility. The command‑line utility is still being updated for the new resource types. If you have automations that depend on it, consider waiting.
• Custom integrations. Any bespoke integrations that call the API will need to handle the additional encryption layer and therefore will break if not adapted prior to the migration of the existing content. Updated SDKs are planned but not yet scheduled for release.

Enable the new resource types

To start using new features like icons, multiple URIs, and custom fields, encrypted metadata needs to be enabled. This setting has to be turned on manually by an administrator in the admin settings. The next section walks through the steps. For more details on each option, see the administrator documentation. 

Create a metadata key

Encrypted metadata requires an organization-wide shared metadata key, and this key must be created manually by an administrator.

1. Navigate to Administration > Metadata key.
2. In the Shared metadata keys section, click on Generate key.
3. Save the settings.

Enable encrypted metadata

Encrypted metadata is one of the key structural changes in v5 resource types. It must be enabled and set as the default format to take full advantage of the new capabilities.

1. Navigate to Administration > Encrypted metadata.
2. In the Support metadata section, toggle on the “Enable encrypted metadata” setting to make v5 resource types available to all users.
3. In the Default metadata type section, enable the “Encrypted metadata” setting. This ensures that client applications (web and mobile) will create resources using the v5 format by default.
4. In the Self served migration section, enable the “Allow users to upgrade their content” if you want all the users to be able to update their existing content manually to the new resource types and benefit from the new capabilities.

Migrate existing content

Encrypted metadata is now active, so every new item already benefits from icons, multiple URIs, and custom fields. The next step is to bring the same capabilities to the existing resources you created before the switch. This is the most delicate phase of the rollout. Make a verified backup of your instance before you begin; if anything goes wrong, a backup is your only safety net. 

Once your integrations are migrated and you are ready, here the final migration procedure follows.

1. Navigate to Administration > Migrate metadata.
2. In Items to migrate, switch on Resource to include every resource.
3. In Migration scope, switch on All content so resources from all users are covered.
4. Click Migrate and wait for the process to finish. How long it takes depends on the size of your workspace.

Conclusion

Thank you for taking the time to try these new features. They have been a long-running effort, and your experience matters to us. If you encounter any issues or have suggestions, please post on the community forum, the team is eager to hear your feedback.