Skip to main content

Quickstart

This guide will show you how to:

  • Deploy the Authenticator.
  • Store database credentials in Vault to be retrieved by the Authenticator.
  • Connect to a Postgres database through the Approzium Python SDK.

Deploying the Authenticator

  • Head to our latest release
  • Choose the appropriate binary for your operating system, and run it with a set of commands like:
curl -LO https://github.com/cyralinc/approzium/releases/download/v0.2.0/darwin_amd64.zip
unzip darwin_amd64.zip

export VAULT_ADDR=http://localhost:8200
export VAULT_TOKEN=root
./authenticator --disabletls

For availability, we recommend running the Authenticator in a long-running environment (such as an EC2 instance) rather than in a short-lived environment (like in AWS Lambda).

Storing Credentials in Vault

The Authenticator expects credentials for a single database user as a secret stored against the database user as the key. The secret contains the database password and a set of IAM roles allowed to access the credentials in the following structure.

cat dbuser1-creds.json
{
"dbuser1": {
"password": "asdfghjkl",
"iam_arns": [
"arn:aws:iam::accountid:role/rolename1",
"arn:aws:iam::accountid:role/rolename2"
]
}
}

For database access to be granted to a caller, the caller's exact iam_arn must be listed, unless the caller has assumed a role. For assumed roles, either the role ARN or the assumed role ARN may be used to grant access.

Enable Vault KV Version 1 (see Vault documentation for more information).

vault secrets enable -path=approzium -version=1 kv

Put the secret at path approzium/<DATABASE_HOST:DATABASE_PORT> with your database user as the key.

vault write approzium/1.2.3.4:5432 @dbuser1-creds.json

SDK Usage

Python

Install the SDK in your client.

pip3 install 'approzium[sqllibs]'

Connect to your database as follows. (Note: TLS should not be disabled in production environments, see our Python guide for how to configure them.)

from approzium import AuthClient
from approzium.psycopg2 import connect

# create an Authenticator client
auth = AuthClient('authenticator:6001', disable_tls=True)

# connect using Approzium's connect method without providing a password
conn = connect("host=1.2.3.4 user=dbuser1 dbname=mydbhost", authenticator=auth)

# use the connection as you typically would. very cool!
cur = conn.cursor()
cur.execute('SELECT 1')

Go

The Approzium Go SDK currently supports MD5 authentication to Postgres.

go get github.com/cyralinc/approzium
package main

import (
"fmt"
"log"
"os"

"github.com/cyralinc/approzium"
)

func main() {
// Create a connection to the Approzium authenticator,
// because only the authenticator knows the password.
authClient, err := approzium.NewAuthClient("localhost:6001", &approzium.Config{
DisableTLS: true,
RoleArnToAssume: os.Getenv("TEST_ASSUMABLE_ARN"), // Optional.
})
if err != nil {
log.Fatal(err)
}

// Now create a Postgres connection without a password.
// We also support strings like:
// "postgres://pqgotest:@localhost/pqgotest?sslmode=verify-full"
dataSourceName := "user=postgres dbname=postgres host=localhost port=5432 sslmode=disable"
db, err := authClient.Open("postgres", dataSourceName)
if err != nil {
log.Fatal(err)
}
defer db.Close()

rows, err := db.Query("SELECT 1")
...
}