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")
    ...
}