Skip to content
Art2link ESB v2.02 LTS HomeDocumentationBlogContact
Core concepts/Authentications

Authentications

Connection details and credentials live in a separate object that ports reference by name — one Authentication type per Adapter type, application-scoped, encrypted at rest, optionally included when you snapshot the application.

An Authentication in Art2link ESB is the object that holds whatever a port's adapter needs to reach its endpoint — for a SQL Adapter that is the connection string, and every other adapter type declares its own fields. The shape is determined by the adapter; the storage and lifecycle are the same in every case.

Authentications are deliberately separated from port and adapter configuration so the connection details can be defined once and referenced from every port that needs them. Each port carries the Authentication's name, not its value — editing the port's other properties does not require seeing or re-entering the secret, and rotating the secret in one place updates every port that uses it.

SEPARATION Ports carry the name. The Authentication holds the secret. PORTS PORT  orders-receive auth: orders-db PORT  orders-archive auth: orders-db PORT  orders-status auth: orders-db references by name AUTHENTICATION orders-db DEFINITION: SQL value: encrypted at rest — never shown in lists Rotate the value here once — every port that names orders-db picks it up at the next resolve.

The same separation is what makes Snapshots safe to share — configuration moves between environments as plain JSON, and Authentications travel only when the operator opts in and supplies a password.

Design choice
One Authentication type per Adapter type

The pairing between Adapters and Authentications is one-to-one at the type level. Every Adapter type defines exactly one Authentication shape; an adapter cannot consume an Authentication that belongs to a different adapter type.

Take SQL as the worked example. A SQL Adapter on a port reaches its database through a SQL Authentication whose value is the connection string. Every other adapter type declares its own Authentication shape with its own fields; an adapter cannot point at an Authentication that belongs to a different adapter type. The pattern is the same throughout: pick the adapter, and the fields the Authentication exposes follow.

Practical effect. When you create an Authentication, the first thing you choose is the adapter type it pairs with. From that point on, the form's fields, validations, and the way the runtime hands the value to the adapter are all determined by that choice.
Reference
Where Authentications live

Authentications are scoped to an Application, owned by it alongside the other artifacts the Application carries — see the catalogue in the Applications article for the full inventory. From the application menu, the Authentications list shows every Authentication that belongs to that application. Each row has these columns:

ColumnDescription
NameHow the Authentication is referenced from a port. Names are unique within the application; they are how a port's adapter configuration points back at this object.
DefinitionThe Adapter type this Authentication pairs with — SQL for a SQL Authentication, and the matching value for every other adapter type. The Definition pins the field shape and dictates which adapters are allowed to reference this Authentication.
ApplicationThe application this Authentication belongs to. Authentications never cross application boundaries; this column appears only when no Application is selected — see Selected Application.

The list view follows the platform's Selected Application behavior — with an Application selected, the list filters to it and the Application column is hidden; with no selection, the list spans every Application you have access to and the column is shown. Creating a new Authentication uses the same flow: with an Application selected, the form opens with that Application preemptively chosen; without one, the form exposes an Application picker.

Field values are not in the list. The values an Authentication carries are never displayed in the list view; the list is a directory of references, and the values themselves are kept under encryption (see Encrypted at rest below).
Concept
Reuse across ports and adapters

A single Authentication can be referenced by any number of ports inside the application, as long as each of those ports uses an adapter of the matching type. Five ports all reaching the same endpoint share one Authentication; its values live in one place and one place only.

This is the practical reason the object exists. The alternative — embedding the values inside each port's adapter configuration — would mean as many copies of the secret as there are ports, as many places to update when something changes, and as many chances for the copies to drift.

SHARED 5 ports → 1 Authentication PORTport-1 PORTport-2 PORTport-3 PORTport-4 PORTport-5 AUTH orders-db one secret Rotate once. Every port picks up the new value at the next resolve. No drift, one source of truth. EMBEDDED 5 ports → 5 copies PORTport-1copy of secret PORTport-2copy of secret PORTport-3copy of secret PORTport-4copy of secret PORTport-5copy of secret Rotate five times. Five chances to miss one and let the copies drift. The model Art2link does not use.
Reuse boundary. Reuse is bounded by adapter type and by application. An Authentication cannot be referenced by an adapter of a different type, and an Authentication in Application A cannot be referenced from a port in Application B. If two applications need the same credential, define it in each.
Runtime
Encrypted at rest

Authentications are always encrypted at rest under a platform-managed key. Their values are written encrypted at save time and decrypted only when an adapter resolves the reference at execution time.

AT REST Encrypted under a platform-managed key — no opt-out FORM — SAVE Server=…Pwd=… plaintext, in memory encrypt STORED — ENCRYPTED 8f3b…a91c…d4e7 decrypt at resolve ADAPTER — RUNTIME Server=…Pwd=… plaintext, in memory Plaintext only at the boundaries. At rest, lists, exports without password — never plaintext.

This is the default and there is no opt-out. The only place encryption changes shape is when an Authentication is exported as part of a Snapshot, where a second layer kicks in — see below.

Related
In Snapshots

Authentications are the one part of an application's configuration that Snapshots include only on request. Taking or exporting a snapshot exposes an Include authentications option:

  • Leave it unchecked and the snapshot captures everything except Authentications. Configuration travels as plain JSON; secrets stay behind.
  • Check it and every Authentication owned by the application is included, with the snapshot password-encrypted under a passphrase the operator supplies at creation or export time. The same passphrase is required to decrypt the file on import.

The platform-managed encryption that protects an Authentication at rest is replaced for the snapshot by this user-supplied password — that is what makes a snapshot file portable across environments without exposing the platform key. The full take / export / import flow, including what happens when the password is missing or forgotten, is documented in the Snapshots article.

⚠️
The snapshot password is unrecoverable. A snapshot can still be imported without it — the configuration comes through, but the encrypted Authentications are discarded and must be recreated on the destination application before the configuration can be applied.

That is the whole shape

Pick an adapter type, define a name, fill in the fields the adapter requires, save. Reference the Authentication by name from every port that needs the same connection. Encrypted at rest by default, included in a snapshot only when you ask, and password-protected when you do.