How Database MFA Works
Components
| Component | Where it runs | What it does |
|---|---|---|
| AuthNull console | AuthNull Cloud, or your on-premises stack | Where admins configure the MFA provider, users, agents, and policies, and where users open connections |
| authn-service | Part of the AuthNull platform | Decides each database login: matches it to a policy and sends the push |
Database agent (db-agent) | A Linux host in your network | Discovers databases, users, and tables; creates and rotates database role passwords; keeps ProxySQL configured |
| ProxySQL | The same host as the agent | Accepts every database connection and asks AuthNull before letting it through. Listens on 6133 (PostgreSQL) and 6033 (MySQL) |
| Your database | Unchanged | Only accepts sessions brokered by ProxySQL, using passwords the agent manages |
| MFA provider | AuthNull Authenticator, Duo, or Okta | Delivers the push to the user's phone |
What Happens During a Login
- A user opens a connection from the Connections screen. The console issues a one-time token, valid for 180 seconds.
- The client connects to ProxySQL as
<database user>,<token>. - ProxySQL sends the token to authn-service, which finds the console user behind it and the database policy that covers them.
- Depending on the policy's action:
- Require MFA - authn-service sends a push to the console user through the organization's MFA provider and waits for the answer.
- Allow - the login proceeds without a push.
- Block - the login is refused, without a push.
- When the push is approved, ProxySQL opens the session to the database as the database user, using the password the agent set.
note
The push goes to the console user who opened the connection (matched by email address), not to the database user. Several console users can share one database user; each one approves their own push.
Why Users Never Handle Database Passwords
When a policy is created, the agent sets a new random password on the database role and stores the same password in ProxySQL. Users authenticate to ProxySQL with their one-time token only, so the real password is never shown, copied, or shared.