## PUBLIC REPOSITORY ##

Steve Shipway
SMX

# INSTALL

Requires op_connect Ruby Gem to be installed on Puppet Master: 
'gem install op_connect'

Use gem 0.1.3 with the fix or later
Fix: partydrone/connect-sdk-ruby#8

Set up the 1password.yml file on the puppetmaster with the configuration

Include the class op::test to run some basic tests

Inclue the class op if you want to be able to set op::user_passwords in hiera
and manage a set of passwords.

Use the op::user{} define to explicitly manage user passwords

Use the op::*() functions to set or retrieve secrets in manifests

# PARAMETERS

Set these in Heira, or in the 1password.yml on the server(s) under /etc/puppetlabs/puppet

apikey
endpoint
default_vault

# PASSWORD CLASS
Change password if older than 30 days, updating the 1password.com
database to reflect changes.

Allows you to have regularly rotating passwords, stored centrally and audited, 
but with noone actually knowing what they are.

This will also change and update if password is not yet defined 
It will NOT verify that 1P record contains the correct password though as
this is not necessarily possible with various backends

Only users with UID<500 are checked; to change this, edit the facter module
to set facts for ALL users. (see comments at start of lib/facter/password.rb )
Note that ubuntu/debian people may wish to make this threshold <1000 instead.

Facter should set facts: pwage_(.*) for all accounts <500

To use:
   op::user { 'root': }
   op::user { 'oracle': maxage=>60, vault=>'Oracle Passwords' }

Attributes:
   maxage: number of days old a password must be before it gets auto changed
           default is 30
   vault: which vault to place the secret into, if not the default
   username: (namevar) username to set password for
   minreset: minimum number of days before password can be changed by user
           default is 0 (may not be supported by your unix)
   password_length: length of password to create
   secret: text for secret name (default is $username@$fqdn)

1Password:
   The new password is of type LOGIN
   The secret name is $username@$fqdn

Assumptions:
   1. The specified vault exists, is writeable, and defaults to appropriate
      sharing rules
   2. All passwords for servers are shared with the puppet user
   3. All newly created passwords will be with standard type
   4. Passwords can be changed via /usr/sbin/chpasswd (install this if it is
      not present).  This works for ubuntu, debian, redhat, centos, fedora,
      and solaris (if chpasswd is installed from sunfreeware)
   5. Password ages are in /etc/shadow in standard format (OK for redhat, 
      centos, fedora, ubuntu, debian, solaris)
   6. OnePassword API available

# Retrieval function

    $vaultname = op::default_vault()
    Return name of default vault
    Return undef for error

    $daysold = password_age($username)
    Return how many whole days old the password for the user is (0+)
    Return undef for user does not exist

    $exists = op::check($secretname)
    Return true or false depending on if the secret exists ( exact match )

    $password = generate_password($length=12)
    Generate a random password.  Use 12 if length not specified.

    $secret = op::get_secret( $secretname )
    $secret = op::get_secret( $secretname, $exact=true, $vault=$default )
    Retrieve secret value.  $exact is optional, if false then does partial match
    If a vault is not specified, then all available vaults are scanned
    Return undef if secret not found, or if multiple matches are found

    $status = op::set_secret( $secretname, $value )
    $status = op::set_secret( $secretname, $value, $exact=true, $vault=$default )
    Set secret to given value.  If secret doesnt exist, then create it in the
    default vault (or specified vault).  Search for secret to update using 
    partial match if exact=false.
    Return undef IF SUCCESSFUL else return error string
    Multiple matches is handled as an error

    $content = op::get_file( $secretname )
    $content = op::get_file( $secretname, $exact=true, $vault=$default )
    $content = op::get_file( $secretname, $filename=".", $exact=true, $vault=$default )
    Retrieve content of file attached to secret.  If $exact=false then use
    partial match.  Use the first attached file unless $filename is given
    in which case use this as a regexp to match against the filename.
    Return undef if not found

# Errors

If trying to retrieve or update a secret, and more than one potential match are
found, then this will be handled as an error (not found, or update failed)
Fatal errors will be raised in puppet and cause a halt.
set_secret will return error strings on failure.
Errors are logged in puppetserver logs

# Configuring

* Install op_connect ruby gem into the puppetserver ruby ( puppetserver gem install op_connect )
* Config in /etc/puppetlabs/puppet/1password.yaml
* Must set default_vault, endpoint, apikey

The lookuptest.sh script tests against the local user's puppet install, copying
the module in and configuring dynamically.  DO NOT RUN THIS AS ROOT.