Create a dynamic Oracle secret

A shared database password lives in every app that uses it, and changing it means changing it everywhere at once. A dynamic secret replaces it with a login of its own for each machine: your Burrow creates it in Oracle the moment a machine reads the secret, with only the rights you choose, and removes it when its time is up.

What you need#

• An Oracle database, 19c or later, your Burrow can reach, and a role in your Burrow that can write secrets.

• An admin login there that can create, change and drop users, ideally one made for your Burrow.

• Machines with access to the environment the secret goes in. This guide uses api's prod.

Open a new dynamic secret#

Open the environment in Projects, select the + at the top right of the secrets table and choose Dynamic. The dialog has three steps: Connection, Lease & credential, and Review.

Connect to your database#

Name the secret, such as ORACLE. Machines read it as api/prod/ORACLE, like any other secret. Set Provider to Oracle: each machine's login is then a user in your pluggable database. The other databases work the same way, each with its own kind of login, and SSH user and Windows account, below the line, sign in to hosts instead.

Then fill in where the database is and how your Burrow signs in to it:

• Host and Port: where your Burrow reaches the database's listener. The port starts at 1521; for an encrypted connection, give the port your listener serves TLS on, usually 2484.

• Database: the pluggable database's service, such as ORCLPDB1. Each login is a user in it. The container database's root is refused, since Oracle makes only common users there.

• Admin user and Admin password: the login your Burrow uses to create and remove each machine's login. It never leaves your Burrow, and machines never see it.

Choose how the connection is protected:

The three encrypted options use TLS (TCPS), which your listener serves on a port of its own, usually 2484. For a database without a TLS listener, choose None.

With either checking option, a CA certificate field appears. If your database's certificate comes from your own CA, paste that CA's certificate there. A managed database's certificate is trusted already, so leave it empty.

Select Test connection. Your Burrow signs in with the admin login, checks it may create, change and drop users, then makes a locked user, gives it CREATE SESSION and drops it again. A green check means it passed; if it fails, the reason shows beside the button. Each machine's own login is made when it first reads the secret. Select Continue.

Shape each password#

Every login gets its own random password. Under Password, set its length, which of A to Z, a to z, 0 to 9 and symbols it uses, and whether to leave out characters that look alike, such as 0 and O. Oracle 19c and 21c take passwords of at most 30 characters, so the length goes from 8 to 30, and UUID isn't offered. The example shows the shape; each login's real password is made when it's issued.

Decide what each login may do#

The grants are SQL, run in the pluggable database on each login as it's created, with {{name}} standing for the login. End each statement with a semicolon; a PL/SQL block can't be saved. Without any grants, a login can sign in but can't touch your data. Select Build to write them from a list:

• Access: Read-only reads rows, Read / write also inserts, updates and deletes them, and Full can change the tables too.

• Privileges: tick them one by one instead, under Data (reading, inserting, updating and deleting rows) and Table changes (altering tables, indexes and foreign keys). Any mix that isn't a preset is marked Custom.

• Scope: the schema, app unless you change it, and its tables, each by name. An Oracle grant covers one table, so each table gets a statement of its own, and a table made later needs its own grant.

Nothing in the builder lets a login make tables of its own, which would keep it from being dropped when it ends. The statements show as you choose, and Use these grants puts them in the grants box. Read / write with Delete rows cleared, for an app that never deletes, on orders and customers writes these:

GRANT SELECT, INSERT, UPDATE ON app.orders TO {{name}};
GRANT SELECT, INSERT, UPDATE ON app.customers TO {{name}};

Then select Test the grants. Your Burrow makes a locked user, applies the grants to it and drops it again, so a typo or a missing table shows up now rather than when a machine reads.

Set the lease policy#

The lease policy decides how each login lives. A new secret starts with sensible defaults, so you may not need to change any of them:

Oracle can't expire a user at a set time, so there's no Database expiry setting here: your Burrow drops each login when its lease ends.

Review and create#

Select Continue to see everything on one page, then Create dynamic secret. The admin password and CA certificate are saved with the secret, encrypted like any other value.

Read it from a machine#

A machine reads a dynamic secret the way it reads a structured one, and gets its own login as fields: host, port, database (the service), sslmode, sslrootcert when you gave a CA, username and password. The username starts with RK_ and names the machine and the secret, in capitals as Oracle lists it among its users; your app can type it in either case.

ratel run sets one variable per field, so ORACLE gives ORACLE_HOST, ORACLE_USERNAME, ORACLE_PASSWORD and so on:

ratel run --env api/prod -- ./server

Unless sslmode is disable, your app connects over TLS (TCPS), to the port the fields give. A machine keeps its login across reads until it ends, and the secret's row counts the logins out. With ratel run --watch, the command restarts when its login gets a new password; a renewal keeps the password, so it restarts nothing.

Change it later#

Choose Configure from the secret's row menu. Each tab saves on its own:

The connection and grants are kept as the secret's value, so Version History lists every change, and reverting to an earlier one replaces the logins like any other change.

See and revoke logins#

Choose Logins from the row menu to see every login out: the machine holding it, its username, its state, and when it was issued and ends.

The bin at the end of a row revokes that login now. Your Burrow locks it so it can't sign in, ends its open sessions on every instance where the admin login may, and drops it. Its machine gets a new login on its next read.

Oracle can't hand on what a login made, so a login that made tables of its own isn't dropped with them: it stays locked with its sessions ended, and is dropped once they're moved or dropped.

If a login isn't issued#

Every option in one place: Dynamic secrets in the documentation.