GitHub - MetaCenterCloudPuppet/cesnet-kerberos: MIT Kerberos puppet module

##Kerberos

####Table of Contents

Module Description - What the module does and why it is useful
Setup - The basics of getting started with Kerberos
Usage - Configuration options and additional functionality
Reference - An under-the-hood peek at what the module is doing and how
Limitations - OS compatibility, etc.
Development - Guide for contributing to the module

##Module Description

This module deploys MIT Kerberos client and servers.

##Setup

###What cesnet-kerberos module affects

Files modified:
/etc/krb5.conf
/etc/krb5kdc or /var/kerberos/krb5kdc directory: kdc.conf, stash file, ...
/var/lib/krb5kdc or /var/kerberos/krb5kdc directory: Kerberos database
/usr/local/sbin/kerberos-kprop-all: propagation script on Kerberos admin server
Packages: MIT Kerberos packages as needed (client, kadmin, krb5kdc, kpropd)
Services: MIT Kerberos services as needed (kadmin, krb5kdc, kpropd)

###Setup Requirements

Puppet >= 3.x.

There are required passwords in parameters:

master_password: master password for KDC database (needed only during initial bootstrap)

For multi node setup:

admin_principal: admin principal name
admin_password: password for remote admin principal (needed only during initial bootstrap)

Parameters could be removed after the complete installation.

###Beginning with Kerberos

Everything on one machine (client, admin server, KDC server):

class{'kerberos':
  kadmin_hostname => $::fqdn,
  master_password => 'strong-master-password',
  realm           => 'MONKEY_ISLAND',
}

node default {
  $princ = "host/${::fqdn}@${::kerberos::realm}"
  kerberos::principal{$princ:
    ensure     => present,
    attributes => {
      requires_preauth => true,
    },
    policy     => 'default_host',
  }
  -> kerberos::keytab{'/etc/krb5.keytab':
    principals => [$princ],
  }

  kerberos::policy{'default':
    ensure     => 'present',
    minlength  => 6,
    history    => 2,
    maxlife    => '365 days 0:00:00',
  }

  kerberos::policy{'default_host':
    ensure     => 'present',
    minlength  => 8,
  }
}

Note: as seen in the example: all principals and keytab needs to be specified.

##Usage

Multi-KDC setup

More advanced usage with multiple KDC servers and separated clients:

include ::stdlib

$kadmin_hostname = "kadmin.${domain}"
$kdc_hostnames = [
  "kadmin.${domain}",
  "kdc1.${domain}",
  "kdc2.${domain}",
]
$realm = 'MONKEY_ISLAND'
$host_principals = suffix(prefix($kdc_hostnames, 'host/'), "@${realm}")

class{'kerberos':
  kadmin_hostname   => $kadmin_hostname,
  kdc_hostnames     => $kdc_hostnames,
  admin_principal   => "puppet/admin@${realm}",
  admin_password    => 'good-password',
  master_password   => 'strong-master-password',
  realm             => $realm,
}

node 'kadmin' {
  kerberos::principal{$host_principals:
    ensure     => 'present',
    attributes => {
      'requires_preauth' => true,
    },
    policy     => 'default_host',
  }
  ->kerberos::keytab{'/etc/krb5.keytab':
    principals => ["host/${::fqdn}@${realm}"],
  }

  kerberos::principal{$::kerberos::admin_principal:
    ensure     => 'present',
    attributes => {
      'requires_preauth' => true,
    },
    password   => $::kerberos::admin_password,
    policy     => 'default_host',
  }

  kerberos::policy{'default_host':
    ensure    => 'present',
    minlength => 6,
  }

  kerberos::policy{'default':
    ensure    => 'present',
    history   => 2,
    minlength => 6,
    maxlife   => '365 days 0:00:00',
  }

  cron{'kprop-all':
    command     => '/usr/local/sbin/kerberos-kprop-all > /var/log/kerberos-kprop-all.log 2>&1',
    environment => 'PATH=/sbin:/usr/sbin:/bin:/usr/bin',
    hour        => '*',
    minute      => 0,
  }
}

node /kdc\d+/ {
  # this will use kerberos::admin_principal and kerberos::admin_password parameters
  kerberos::keytab{'/etc/krb5.keytab':
    principals => ["host/${::fqdn}@${realm}"],
    wait       => 600,
  }
}

# all clients
node default {
  # this will use kerberos::admin_principal and kerberos::admin_password parameters
  kerberos::principal{"host/${::fqdn}@${realm}":
    ensure          => 'present',
    attributes      => {
      'requires_preauth' => true,
    },
    policy          => 'default_host',
  }
  ->kerberos::keytab{'/etc/krb5.keytab':
    principals => ["host/${::fqdn}@${realm}"],
  }
}

Note: bootstrap:

For bootstrap process to work, the Kerberos admin server (kadmin_hostname) should be also a KDC server (in kdc_hostnames). This way the Kerberos host keys can be distributed from admin server to KDC slaves using Kerberos KDC on the admin server. Also admin_principal and admin_password are required.

Several iterations must be performed before deployment is successfully finished:

(will fail) Kerberos admin server initial database setup + creating admin and KDC host keys
(will wait on KDCs) KDC server setup + fetch host keys created in (1.) into keytabs
(success after all KDC ready) propagate database from admin server to slave KDCs using /usr/local/sbin/kerberos-kprop-all
(success on KDCs after propagation from admin server) KDC server finalize - stash files for startup

Note 2: principals and keytabs

All principals and keytabs need to be explicitly created. Better is to put kerberos::principal resource at admin server to minimize admin password usage. kerberos::keytab on remote machines will use admin principal and password once during creating of the keytab files.

Note 3: perform parameter

By default the main kerberos class install services according to set hostnames. It is possible to disable it by perform parameter and place particular classes on the nodes manually.

Note 4: kprop

See the example cron job in kadmin node.

DNS aliases

It is the best-practice to use DNS aliases in krb5.conf. Kerberos puppet module requires real hostnames in its parameters, but aliases can be set using client overrides:

...
class{'kerberos':
  client_properties => {
    'realms' => {
      "${realm}" => {
        'kdc' => ['kadmin-alias', 'kdc1-alias', 'kdc2-alias'],
        'admin_server' => 'kadmin-alias',
      },
    },
  },
  kadmin_hostname   => $kadmin_hostname,
  kdc_hostnames     => $kdc_hostnames,
  ...
}

More Kerberos module resources examples

kerberos::policy{'default':
  ensure               => 'present',
  minlength            => 6,
  history              => 2,
  maxlife              => '365 days 0:00:00',
  failurecountinterval => '0:00:00',
}

kerberos::principal{'[email protected]':
  ensure     => 'present',
  attributes => {
    'allow_tix'        => true,
    'requires_preauth' => true,
  },
  policy     => 'default',
}

Note: defaults

default_attributes and default_policy parameters on kerberos class can be used instead of parameters in kerberos::principal.

krb5.conf only

$kadmin_hostname = "KADMIN.example.com"
$kdc_hostnames = [
  "KADMIN.example.com",
  "KDC1.example.com",
  "KDC2.example.com",
]

class{'kerberos':
  kadmin_hostname   => $kadmin_hostname,
  kdc_hostnames     => $kdc_hostnames,
  realm             => 'EXAMPLE.COM',
  perform           => false,

  # realm-specific config file instead of global config
  #krb5_conf => '/etc/krb5.conf.d/example_com'
}

include ::kerberos::client::config

##Reference

###Classes

kerberos: The main class
kerberos::client: Kerberos client
kerberos::client::config
kerberos::client::install
kerberos::client::service
kerberos::kadmin: kadmin server
kerberos::kadmin::config
kerberos::kadmin::install
kerberos::kadmin::service
kerberos::kdc: KDC server
kerberos::kdc::config
kerberos::kdc::install
kerberos::kdc::service
kerberos::kprop: kpropd server
kerberos::kprop::config
kerberos::kprop::install
kerberos::kprop::service
kerberos::params

`kerberos` class

Parameters

#####acl

ACL to Kerberos database. Default: "${admin_principal} admcil" for everything.

#####admin_password

Password of the principal for remote access to KDC. Default: undef.

Required for initial bootstrap of multiple KDC servers.

#####admin_principal

Principal name for remote access to KDC. Default: undef.

Required for initial bootstrap of multiple KDC servers.

#####admin_keytab

Keytab for remote access to KDC. Default: undef.

#####client_packages

List of Kerberos client packages. Default: $::kerberos::params::client_packages.

#####client_properties

Additional client parameters or overrides for krb5.conf. Default: undef.

Example:

client_properties => {
  'realms' => {
    'MONKEY_ISLAND' => {
      'kdc' => ['kadmin-alias', 'kdc1-alias', 'kdc2-alias'],
      'admin_server' => 'kadmin-alias',
    },
  },
},

#####default_attributes

Default attributes used in kerberos::principal resource. Default: undef.

#####default_policy

Default policy name used in kerberos::principal resource. Default: undef.

#####domain

Realm DNS domain. Default: $::domain.

#####kadmin_service

Kerberos admin server service name. Default: by platform.

#####kadmin_packages

Kerberos admin server packages. Default: by platform.

#####kadmin_hostname

Kerberos admin server hostname. Default: $::fqdn.

It should be real hostname, not DNS alias. See client_properties for aliases usage.

#####kdc_conf

KDC config file. Default: *"${::kerberos::kdc_conf_dir}/kdc.conf".

Limitation: no kdc_conf_dir parameter.

#####kdc_service

KDC service name. Default: by platform.

#####kdc_packages

KDC packages name. Default: by platform.

#####kdc_hostnames

KDC hostnames. Default: kadmin_hostname or $::fqdn.

It should be real hostnames, not DNS aliases. See client_properties for aliases usage.

#####kdc_properties

Additional parameters or overrides for kdc.conf. Default: undef.

Example:

kdc_properties => {
  'realms' => {
    'MONKEY_ISLAND' => {
      'supported_enctypes' => 'aes256-sha1:normal aes128-sha1:normal des3-cbc-sha1:normal arcfour-hmac:normal camellia256-cts:normal camellia128-cts:normal',
    },
  },
},

#####krb5_conf

Main kerberos client config file. Default: '/etc/krb5.conf'.

Example:

krb5_conf => '/etc/krb5.conf.d/monkey-island.conf',

#####master_password

KDC database master password. Default: undef.

Required for initial bootstrap.

#####perform

Automagically deploy all services on the nodes. Default: true.

#####realm

Kerberos realm name. Required.

###Resource Types

kerberos::keytab: Kerberos keytab
kerberos::policy: Kerberos policy (using parameters from kerberos class)
kerberos::principal: Kerberos principal (using parameters from kerberos class)
kerberos_principal: Kerberos principal
kerberos_policy: Kerberos policy on admin server

`kerberos_principal` resource

Parameters for kerberos::principal are the same, except admin_keytab, admin_password, admin_principal, which are taken from the main kerberos class parameters.

Parameters

#####title

Kerberos principal name

#####admin_principal

Admin principal. Default: undef.

The admin principal is added to ACL with "acmil" rights.

#####admin_keytab

Admin keytab. Default: undef.

Non-empty parameter will switch from kadmin.local do kadmin in resources.

#####admin_password

Admin password. Default: undef.

Non-empty parameter will switch from kadmin.local do kadmin in resources.

#####attributes

Kerberos principal attributes. Default: undef.

Hash of principal boolean attributes values. Specified attributes are compared with the real values and updated, if needed. Not specified attributes are not checked.

List of known attributes:

allow_postdated
allow_forwardable
allow_tgs_req
allow_renewable
allow_proxiable
allow_dup_skey
allow_tix
allow_svr
requires_preauth
requires_hwauth
needchange
password_changing_service
ok_as_delegate
ok_to_auth_as_delegate
no_auth_data_required
lockdown_keys

Example:

attributes => {
  allow_tix        => true,
  requires_preauth => true,
}

#####local

Prefer kadmin.local over kadmin. Default: (false when admin_keytab or admin_password parameters non-empty)

#####password

Kerberos principal password. Default: undef (=randomized key).

Passwords are not changed. This parameter is used only when creating a new Kerberos principal.

#####policy

Kerberos policy of the principal. Default: undef.

`kerberos_keytab` resource

Parameters admin_keytab, admin_password, admin_principal are taken from the main kerberos class parameters.

Parameters

#####title

Keytab file.

#####principals

Principals to add into keytab. Required.

#####owner

Keytab file owner. Default: undef.

#####group

Keytab file group. Default: undef.

#####local

Prefer kadmin.local over kadmin. Default: (autodetect by FQDN)

Requirements:

remote administration using kadmin: kerberos::admin_keytab or kerberos::admin_password parameter
local administration using kadmin.local: placement on Kerberos kadmin server

#####mode

Keytab file mode. Default: '0600'.

#####wait

Repeated tries time. Default: 0 (try once).

`kerberos_policy` resource

Parameters for kerberos::policy are the same, except admin_keytab, admin_password, admin_principal, which are taken from the main kerberos class parameters.

The times can be specified as:

number of seconds
HH:MM:SS
N day HH:MM:SS
N days HH:MM:SS

Parameters

#####title

Kerberos policy name.

#####admin_password

Password of the principal for remote access to KDC. Default: undef.

Non-empty parameter will switch from kadmin.local do kadmin in resources.

#####admin_principal

Principal name for remote access to KDC. Default: undef.

#####admin_keytab

Keytab for remote access to KDC. Default: undef.

Non-empty parameter will switch from kadmin.local do kadmin in resources.

#####maxlife

Maximum password life. Default: undef ('0 days 00:00:00').

#####minlife

Minimum password life. Default: undef ('0 days 00:00:00').

#####minlength

Minimum password length. Default: undef (1).

#####minclasses

Minimum number of password character classes. Default: undef (1).

#####history

Number of old keys kept. Default: undef (1).

#####maxfailure

Maximum password failures before lockout. Default: undef (0).

#####failurecountinterval

Password failure count reset interval. Default: undef ('0 days 00:00:00').

#####lockoutduration

Password lockout duration. Default: undef ('0 days 00:00:00').

##Limitations

For automatic bootstrap, kadmin must be collocated with KDC, see Beginning with Kerberos. Another option is to bootstrap manually - copy host key and database from admin server to KDC slaves.

There is no special care for the password parameters (master_password, admin_password). After initial deployment, it is possible to remove master_password from parameters. It will be needed only when adding another KDC server.

##Development

Repository: https://github.com/MetaCenterCloudPuppet/cesnet-kerberos

Name		Name	Last commit message	Last commit date
Latest commit History 38 Commits
lib/puppet		lib/puppet
manifests		manifests
spec		spec
templates		templates
.fixtures.yml		.fixtures.yml
.gitignore		.gitignore
.rspec		.rspec
.travis.yml		.travis.yml
CONTRIBUTING.md		CONTRIBUTING.md
CONTRIBUTORS		CONTRIBUTORS
Gemfile		Gemfile
Guardfile		Guardfile
LICENSE		LICENSE
Modulefile		Modulefile
README.markdown		README.markdown
Rakefile		Rakefile
metadata.json		metadata.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Multi-KDC setup

DNS aliases

More Kerberos module resources examples

krb5.conf only

`kerberos` class

Parameters

`kerberos_principal` resource

Parameters

`kerberos_keytab` resource

Parameters

`kerberos_policy` resource

Parameters

About

Releases

Packages

Languages

License

MetaCenterCloudPuppet/cesnet-kerberos

Folders and files

Latest commit

History

Repository files navigation

Multi-KDC setup

DNS aliases

More Kerberos module resources examples

krb5.conf only

kerberos class

Parameters

kerberos_principal resource

Parameters

kerberos_keytab resource

Parameters

kerberos_policy resource

Parameters

About

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Languages

`kerberos` class

`kerberos_principal` resource

`kerberos_keytab` resource

`kerberos_policy` resource

Packages