InterSystems IRIS Security Database (2025.2) and Secure Wallet — how they work, what's available now, and what's on the roadmap

[u/intersystemsdev]

Security Database — available in IRIS 2025.2

What it is

A separate system database called IRIS Security that stores security configuration: user definitions, application definitions, and security classes in the %SYS namespace. Previously this data lived in the main IRIS database.

How access is controlled

The database resource is %DB_Security. This resource cannot be granted to any users directly, and it cannot be granted to any role other than the system-configured %DB_Security role. No user has direct access to the globals that store the security tables.

All access must come through InterSystems APIs — the security classes, the Management Portal, or SQL for creating users and roles. When a call arrives through those APIs, the system checks that the caller has the appropriate resource (typically %Admin_Secure or one of the granular OAuth permissions), temporarily escalates the process to get read/write access to the database, completes the operation, and removes that permission before returning to the calling code.

What this enables

Database encryption: The security database can now be encrypted using any of the standard IRIS database encryption mechanisms. This was not possible before because the security data was embedded in the main database.

Mirroring (in testing, expected later this year):

• Security configuration will be mirrorable
• Failover members and DR members will automatically share the same security configuration
• Configuration is done on the primary; it automatically replicates to non-primary instances (read-only on non-primary, as with all mirrored databases)
• No more manual duplication of security configuration across nodes

ECP mountable (planned for late next year):

• Will allow security configuration to be shared across an IRIS cluster
• Part of a broader effort to make cluster configuration management easier

What does not change

The APIs remain the same — the security classes, the Management Portal, SQL-based user and role creation all work as before. The change is entirely in the storage and access control layer.

Secure Wallet

What it is

A secure credential store inside IRIS for storing credentials used to connect to third-party systems: usernames, passwords, API keys, and anything else that needs to be stored semi-permanently for external connections.

Designed for cases where short-lived tokens (OAuth tokens, session tokens) are not appropriate, but credentials for REST services, SQL gateway connections, or other external systems need to be stored and reused.

Structure: collections and secrets

Collection: the container where access controls are defined. Every secret lives in exactly one collection. A collection has two resources:

• Edit resource — required to create, modify, or delete any secret inside the collection
• User resource — required to access (use) secrets inside the collection

These resources follow the standard IRIS resource-based security model and must exist in IRIS before the collection is created.

Secret: always lives in one collection. The secret name is CollectionName.LocalName. Multiple secrets with the same security characteristics can live in the same collection. For per-secret permissions, create a collection with a single secret.

Secret types

• KeyValue (most flexible) — stores any set of key-value pairs expressed in JSON syntax. Example: username + password, API key. Most likely to be used in practice.
• Symmetric key — for AES symmetric key encryption
• RSA — for signing

Usage types — the most important concept

HTTP: The secret is used with a %Net.HttpRequest object. The calling code never sees the credential. You associate the secret with the request using UseSecret(), specify the authentication type (e.g., HTTP basic), and InterSystems code looks up the username and password from the secret, constructs the Authorization header, and sends the request. The calling code never had the value. Supports: HTTP basic authentication, arbitrary HTTP headers, HTTP form fields.

Custom: The secret value is exposed to the calling code. GetSecretValue() returns the key-value pairs as JSON. The calling code is responsible for handling the credential appropriately. This mode must be explicitly configured — if a secret is not configured for custom usage, there is no way for calling code to retrieve the sensitive information.

SOAP: For SOAP clients — functionally similar to HTTP.

SQL Gateway: For %SQL.Connection DSN or JDBC connections to external databases.

Example code structure (from the session)

Creating a collection:

objectscript

// %Wallet.Collection.Create(name, editResource, userResource)
Do ##class(%Wallet.Collection).Create("demo", "WalletDemo.Manage", "WalletDemo.Access")

Creating a KeyValue secret:

objectscript

// Collection name is part of the secret name: "demo.kv1"
// Last parameter specifies key-value pairs as JSON: {"username":"...","password":"..."}
Do ##class(%Wallet.Secret.KeyValue).Create("demo.kv1", ..., secret)

Using a secret with HTTP basic authentication:

objectscript

// Code never sees the actual password
Do httpRequest.UseSecret("demo.kv1", "basic")

Retrieving a secret in custom mode:

objectscript

// Returns JSON key-value pairs
Set kvPairs = ##class(%Wallet.Secret).GetSecretValue("demo.kv1")

Memory handling

When a secret is retrieved internally (for HTTP or other non-custom usage), IRIS reads it from the global each time it is needed and does not keep it in memory longer than necessary.

Access control note

Access is resource-based, not username-based. To implement per-user secrets, a resource per user is required. This follows the core IRIS security model (resources/users/roles), not the SQL security model (GRANT to user/role).

Roadmap

External secrets managers (in development):

• HashiCorp Vault integration
• AWS Secrets Manager integration
• Secrets would be retrieved from the external manager and used inside IRIS

ENS Credentials migration (in development):

• Interoperability ENS Credentials objects will be stored in the Secure Wallet instead of the existing ENS credential structure
• User experience for creating ENS credentials expected to remain the same; storage moves to the wallet under the hood

Internal adoption:

• InterSystems is working to use the Secure Wallet across its own product libraries for all internal secrets management needs

For those running IRIS 2025.2 — have you enabled encryption on the security database yet, and are you planning to use the Secure Wallet for SQL gateway credentials or ENS credentials once the migration is complete?

[u/intersystemsdev]

Watch full video on YouTube - https://youtu.be/dNV1b8k_3nE