Keeping Credentials Out of the Configuration¶
An EEI product that signs in to one of your systems needs a credential to do it: for a connector, the user name and password it uses to read from a source system. The secrets SDK decides where that credential lives and how the product finds it. This page is for the people who own those accounts and the hosts the products run on: what the store is, what protects it, and how it is managed.
The short version: the credential is not in the configuration. It sits in one store on the host, and the configuration says only that the store should be used.
Why move credentials out of the configuration¶
A connector's configuration is visible to more people than its credentials should be. In Seeq, an administrator can view a connector's configuration, and configuration files are copied into backups, support bundles and change records. A password written in that file goes everywhere the file goes.
With the secrets store, the configuration holds the keyword VFORGE_SECRETS in place of the user
name and password. The credential itself is in a separate file that does not travel with the
configuration.
How it works¶
| What it means | |
|---|---|
| One store per host | A single file, vforge/secrets/credentials.json in the Seeq agent's data folder, shared by every EEI connector on that host. (VForge is short for VirtualForge) |
| Found by connection | Each entry is keyed by the connection's Id, so a product looks up exactly the credential for the connection it is opening. Several connections can share one credential |
| Typed entries | An entry records what kind of credential it is (a user name and password, for example), so a product can tell a complete entry from an unfinished one |
| Safe concurrent use | Products and the management tool take a lock before writing, so two writers on one host never corrupt the file |
| Fails visibly | A damaged entry stops that one connection with an error. It is never silently replaced by an older password from somewhere else |
| Works with Seeq's secrets file | A Seeq SECRETS_FILE: reference is still honored, in the configuration or in the store |
Managing it: vf-agent¶
vf-agent is a command-line tool for the store. It ships with the products that use the store and
is installed on the agent host when a product first starts. With it, an administrator can set, list
and check credentials, and run vf-agent secrets migrate to move passwords out of an existing
configuration into the store.
vf-agent never takes a password on its command line and never prints one, so credentials do not
end up in shell history or in logs. Configuration backups that a product makes are masked for the
same reason.
What protects the store¶
The store is plain text, protected by the host's file permissions. It is not encrypted. An administrator of the agent host can read it, which is the same boundary as Seeq's own secrets file. What the store changes is who else can see a credential: people who can view the configuration, and anyone who receives a copy of it, no longer can.
In practice:
- Use a dedicated, read-only service account for each source system.
- Move every connection to the store, so no configuration still carries a password.
- Restrict the agent data folder to the agent's service account and administrators.
Credentials are used only to authenticate to the system they belong to. They are never logged and never sent to EEI.
If your organization needs more, such as integrated Windows authentication or an encrypted store, tell us. The store's design leaves room for further credential sources behind the same lookup, so a stronger option can be added without changing how products ask for a credential.
Where it is used¶
The store is a capability of the platform rather than of one product, so it can sit wherever an EEI product needs a credential. The first product to use it is the ABB Knowledge Manager connector. A connector upgraded from an earlier release keeps working with the passwords already in its configuration, and asks for them to be moved into the store.
For the steps, see the connector's own pages rather than this one:
- Credentials, in the ABB Knowledge Manager user guide.
- How are the Knowledge Manager credentials stored?, in its FAQ.
- The release notes for what changes on upgrade.
About this SDK¶
| What it is | A shared library, and the vf-agent tool that operates it. Customers do not install it separately: it ships inside each product that uses it |
| Languages | Java, in the ABB Knowledge Manager connector. Python and .NET are planned. Every implementation reads and writes the same store, so products in different languages can share one host's store |
| Availability | Built into EEI products and documented openly. Not offered for third-party development |
See the SDK inventory for the rest of the family.