goappauthal

README

goappauthal

Go implementation of the appauth libraries used by various JazzHands utilities.

This is a golang implementation of the appauthal database connection functions.

It covers the most common cases but does not have complte feature parity with the perl and python libraries.

It includes basic support for password and Hasicorp Vault access.

Things missing:

• kerberos support
• jazzhands.appuser/session user magic
• vault library does not suppose just creating and using a vault handle (yet)

These will all be addressed, but at the moment are not.

Typical use is to obtain a databse handle and it's something like this:

package main

import (
        "github.com/jazzhandscmdb/goappauthal/db"
        "github.com/jackc/pgx/v5/stdlib"
        "os"
        "log"
)

func main() {
        app := os.Args[1]


        db, e := godbi.Connect(app)
        if e != nil {
                log.Fatal(e)
        }
        defer db.Close()

        rows, err := db.Query("select count(*) as tally from thing")
        if err != nil {
                log.Fatal(err)
        }
        for rows.Next() {
                var tally int
                err := rows.Scan(&tally)
                if err != nil {
                        log.Fatal(err)
                }
                log.Println(tally)
        }
        err = rows.Err()
        if err != nil {
                log.Fatal(err)
        }
}

NOTE that the underlying database library does need to be included anonymously.

See the appauthal go dodbi go docs for more details.

Documentation

Overview

This provides a generic interface to obtaining and using crednetials. It is primarily for database credentials but others are possible.

This module is not meant to be directly used by mortals; it is meant to provide support functions for other libraries that depend on it.

Files are looked for based on /var/lib/jazzhands/appauth-info or the APPAUTHAL_CONFIG environment variable's config file. Under that directory, the library looks for app.json, and if there is an instance involved looks under app/instance.json and may fall backt to app.json based on sloppy_instance_match.

The library also implements caching via a generic sign in module, and will cache credentials under /run/user/uid or in a directory under /tmp. If the running user does not own that directory and it's not other readable, it will not be used.

This caching is done by the DoCachedLogin call. It is possible to completely disable Caching but setting Caching to false in the general options of a given appauthaal file. The default amount of time to cache a record is set to 86400 seconds, but can be changed via DefaultCacheExpiration in the options field. If the underlying engine (such as vault) includes a lifetime for a credential, it is cached, by default, for half that time. The DefaultCacheDivisor option can be used to change that divisor. There is no way to override that value, just manipulate it.

The AppAuthAL has a hash of many top level stanzas, interpreted by various AppAuthLayer consumers. options is generic across all libraries although may have some module-specific options. database is used for DBI.

An example of one:

{
      "options": {
              "Caching": true,
              "use_session_variables": "yes"
      },
      "database": {
              "DBType": "postgresql",
              "Method": "password",
              "DBHost": "jazzhands-db.example.com",
              "DBName": "jazzhands",
              "Username": "app_stab",
              "Password": "thisisabadpassword"
      }
}

The global configuration file (defaults to /etc/jazzhands/appauth.json) can be used to define system wide defaults. It is optional.

The config file format is JSON. Here is an example:

{
     "onload": {
             "environment": {
                     "ORACLE_HOME": "/usr/local/oracle/libs"
             }
     },
     "search_dirs": [
             ".",
             "/var/lib/appauthal"
     ],
     "sloppy_instance_match": "yes",
     "use_session_variables": "yes"
}

The "onload" describes things that happen during the importing of the AppAuthAL library and are used to setup things that other libraries may require. In this case, environment variables required by Oracle.

The search_dirs parameter is used to search for auth files, and defaults to /var/lib/jazzhands/appauth-info . It will iterate through listed directories until it finds a match. Note that "." means the directory the config file appears in rather than a literal ".". This is typically used to stash all the development connection information in one directory with the config file.

sloppy_instance_match tells the library to use the non-instance version of files if there is no instance match.

use_session_variables tells the library to try to use session variables in underlying libraries to set usernames, if this is available. This is generally a JazzHands-specific thing for databases, but may work in other instances.

Index

• func DoCachedLogin(optmap map[string]interface{}, entry map[string]interface{}, ...) (any, error)
• func FindAndProcessAuth(App string) (interface{}, error)
• func RegisterMethod(name string, helper AppAuthMethod)
• type AppAuthALConfig
• type AppAuthALLoginCallBack
• type AppAuthAuthEntry
• type AppAuthMethod
  • func GetMethod(name string) (AppAuthMethod, error)
• type AppAuthPasswordEntry
  • func (a *AppAuthPasswordEntry) BuildAuthenticateMap() (map[string]string, error)
  • func (a *AppAuthPasswordEntry) GetExpiration() time.Time
• type AppAuthPasswordMethod
  • func (a *AppAuthPasswordMethod) BuildAppAuthAL(inmap interface{}) (AppAuthAuthEntry, error)
  • func (a *AppAuthPasswordMethod) BuildCacheKey(entry AppAuthAuthEntry) string
  • func (a *AppAuthPasswordMethod) GetName() string
  • func (a *AppAuthPasswordMethod) Initialize(inmap interface{}, globals map[string]interface{}) error
  • func (a *AppAuthPasswordMethod) ShouldCache() bool
• type CachedAuth
  • func (c CachedAuth) MarshalJSON() ([]byte, error)
  • func (c *CachedAuth) UnmarshalJSON(data []byte) error

Functions

func DoCachedLogin

func DoCachedLogin(optmap map[string]interface{}, entry map[string]interface{}, callback AppAuthALLoginCallBack, state any) (any, error)

func FindAndProcessAuth

func FindAndProcessAuth(App string) (interface{}, error)

other implementations do app, instance, section, with the second two being optional, so just ignoring those for the moment

func RegisterMethod

func RegisterMethod(name string, helper AppAuthMethod)

Types

type AppAuthALConfig

type AppAuthALConfig struct {
	Onload              map[string]interface{} `json:"onload";omitempty`
	SearchPath          []string               `json:"search_dirs";omitempty`
	SloppyMatch         string                 `json:"sloppy_instance_match";omitempty`
	UseSessionVariables string                 `json:"use_session_variables;omitempty"`
}

type AppAuthALLoginCallBack

type AppAuthALLoginCallBack func(map[string]string, any) (any, error)

type AppAuthAuthEntry

type AppAuthAuthEntry interface {
	BuildAuthenticateMap() (map[string]string, error)
	GetExpiration() time.Time
}

This is a parsed entry

type AppAuthMethod

type AppAuthMethod interface {
	GetName() string
	ShouldCache() bool
	Initialize(interface{}, map[string]interface{}) error
	BuildAppAuthAL(interface{}) (AppAuthAuthEntry, error)
	BuildCacheKey(AppAuthAuthEntry) string
}

func GetMethod

func GetMethod(name string) (AppAuthMethod, error)

type AppAuthPasswordEntry

type AppAuthPasswordEntry struct {
	// contains filtered or unexported fields
}

This must match type AppAuthAuthEntry interface

func (*AppAuthPasswordEntry) BuildAuthenticateMap

func (a *AppAuthPasswordEntry) BuildAuthenticateMap() (map[string]string, error)

entry

func (*AppAuthPasswordEntry) GetExpiration

func (a *AppAuthPasswordEntry) GetExpiration() time.Time

type AppAuthPasswordMethod

type AppAuthPasswordMethod struct {
	// contains filtered or unexported fields
}

This must match type AppAuthMethod interface

func (*AppAuthPasswordMethod) BuildAppAuthAL

func (a *AppAuthPasswordMethod) BuildAppAuthAL(inmap interface{}) (AppAuthAuthEntry, error)

convert the basic structure to something that can be used by the db connector, this is basically a copy since password is the simpliest of connection methods

func (*AppAuthPasswordMethod) BuildCacheKey

func (a *AppAuthPasswordMethod) BuildCacheKey(entry AppAuthAuthEntry) string

unnecessary if caching is not implemented

func (*AppAuthPasswordMethod) GetName

func (a *AppAuthPasswordMethod) GetName() string

returns the name of the method, for sanity reasons

func (*AppAuthPasswordMethod) Initialize

func (a *AppAuthPasswordMethod) Initialize(inmap interface{}, globals map[string]interface{}) error

func (*AppAuthPasswordMethod) ShouldCache

func (a *AppAuthPasswordMethod) ShouldCache() bool

indicates if it makes any sense to cache these values

type CachedAuth

type CachedAuth struct {
	Auth   map[string]string `json:"auth"`
	Expire time.Time         `json:"expired_whence"; omitempty"`
}

func (CachedAuth) MarshalJSON

func (c CachedAuth) MarshalJSON() ([]byte, error)

func (*CachedAuth) UnmarshalJSON

func (c *CachedAuth) UnmarshalJSON(data []byte) error