Skip to content

Federation Add credentials

New to Folio? Start here

Add credentials

A connection defines where a source lives and how it signs in. It never holds the secret itself: workspace files are committed and shared, and Folio raises secret/committed on a password written into one. You bind each secret to a store on your machine, and Folio sends it only to the address the connection named when you bound it.

Before you start

You need a source in your workspace, such as one from Query a database, Query a JSON API or Query CSV, Parquet and Excel files. This guide continues the connection Query a database names in crm.ttl, a PostgreSQL database that needs a username and a password. The steps are the same for the other sources.

1. Say how the source signs in

A connection points to the security scheme it signs in with through td:hasSecurityConfiguration, and a Postgres login is a Basic scheme. The first block of crm.ttl from Query a database already declares both, since crm:db points to crm:dbLogin, so the CRM database needs nothing added. For another source, add the same two parts: the td:hasSecurityConfiguration line on its connection and the scheme it points to.

crm.ttl
@prefix dct:    <http://purl.org/dc/terms/> .
@prefix rml:    <http://w3id.org/rml/> .
@prefix td:     <https://www.w3.org/2019/wot/td#> .
@prefix wotsec: <https://www.w3.org/2019/wot/security#> .
@prefix svdb:   <https://pkg.semvia.io/semvia/rml/connection#> .
@prefix crm:    <https://example.org/crm#> .

# Folio checks this file as an RML mapping.
<> dct:conformsTo <https://pkg.semvia.io/semvia/rml/profiles/rml-mapping> .

# The CRM database. svdb:driver names the ADBC driver that reads it.
# svdb:endpoint is its address, written the way Postgres writes it.
# Put in your own server's address.
# Drop sslmode=disable unless the database is on your own machine.
crm:db a svdb:AdbcConnection ;
  svdb:driver "postgresql" ;
  svdb:endpoint "postgresql://localhost:5432/postgres?sslmode=disable" ;
  td:hasSecurityConfiguration crm:dbLogin .

# The database takes a username and a password. You bind them in Folio, never here.
crm:dbLogin a wotsec:BasicSecurityScheme ;
  wotsec:in "auto" .

Folio requires TLS and checks the server's certificate.

A Bind svwot:secretValue and a Bind svwot:username lens appear above crm:dbLogin, and Secrets lists both fields under Needs a credential. Until both are bound, crm:db and crm:dbLogin carry error marks that read "A secret-marked field has no bound credential". A query that needs the database stops with "nothing is bound for this credential field" until both are bound.

2. Pick a store

Select a Bind lens. A panel opens under it with a choice of where the secret lives:

StoreWhat Folio keepsUse it when
KeychainThe secret, in this machine's OS keychainYour own machine. This is the default.
MemoryThe secret, in the running engine only. It is gone when the engine restarts.A shared or headless machine where nothing should be written to disk.
Env varThe variable's name. The value is read from the engine's environment each time.CI, containers, or anywhere a secret manager already sets variables.
Provider → 1PasswordA reference such as op://Shared/CRM DB/password. The 1Password CLI, from 1Password, supplies the value.1Password already holds it.
Provider → OAuthThe authorization the provider hands back after you sign in, in the keychain. Access tokens live in memory only.The provider offers sign-in instead of a password.
Binding the username. Keychain is selected by default.

Choose a source, fill in the field and select Bind. A pasted secret is never shown again. To change it, bind the field again.

3. Test it

Open Secrets in the activity bar, select a field, then Test. Folio connects with the bound secrets and reports one verdict, such as Connection OK, Authentication failed or Host unreachable, without showing the secret or the server's reply.

Each secret is pinned to an address

When you bind a secret, Folio records the address it may be sent to:

A database
Its whole address, database name and TLS mode included, and the driver that reads it.
A JSON API
The origins of the forms in its Thing Description.
CSV, Parquet or Excel files in a bucket
The bucket, prefix and endpoint.

If an edit later moves the connection somewhere else, Folio stops sending the secret. To send it to the new address, open Secrets and confirm each field: select it, then Test. Test reports Destination not confirmed. Check the new address and select Confirm destination, or bind the field again.

What each source asks for

SourceSchemeFields to bind
Postgres (svdb:AdbcConnection)wotsec:BasicSecurityScheme with wotsec:in "auto"svwot:username, svwot:secretValue
JSON API with a key (td:Thing)wotsec:APIKeySecurityScheme with wotsec:in and wotsec:name, or wotsec:BearerSecuritySchemesvwot:secretValue
JSON API with sign-in (td:Thing)wotsec:OAuth2SecuritySchemeBind with Provider → OAuth
CSV, Parquet or Excel files in an Amazon S3 bucket (svdb:BlobConnection)svdb:SigV4SecuritySchemesvwot:username (the access key ID), svwot:secretValue
CSV, Parquet or Excel files in Azure Blob Storage (svdb:BlobConnection)svdb:SharedKeySecuritySchemesvwot:secretValue

On a JSON API's Thing, declare the scheme with td:definesSecurityScheme and apply it with td:hasSecurityConfiguration.

CSV, Parquet and Excel files in the workspace or at a public URL need no scheme.

Ask your agent to…

  • Move the database connection in crm.ttl to db2.example.com, and tell me what I need to confirm in Folio.