View source for SystemAdministration/KerberosAdministration

Kerberos is a frequently misunderstood monster that lives in darkness, and eating unaware explorers. This guide is your 5 minute introduction to krb5, and how to manage it effectively

== What Is Kerberos ==

Kerberos is a single-sign on service. When a user is autheticated by kerberos, they can access all kerberosized services without having to re-autheticate. This allows for things like node-to-node scps to work without having to deal with setting up per user public/private keys. The main unit in kerberos is the principle, which is simply an account which tickets can be issued for. Users and hosts have kerberos accounts to autheticate with themselves and other nodes across the network. Tickets are granted to users which are handed to kerberosed services to facility authetication.

As of writing, the only kerberosized services we're running is SSH and Apache. icinga uses kerberosized ssh to access other nodes for status information.

== Kerberos Teminology ==
=== Principles ===

Principles are generated through the kadmin tool; you have to kinit as an krb admin before you can run this command, they're a string, and a password; with the string determining what it is, here are some examples

* mcasadevall@LI694-22 - a user
* krb/admin@LI694-22 - krb admin (admin accounts end in /admin, normal admins should use krb/admin for admin work)
* host/hydrogen.li694-22@LI694-22 - a host. Hosts must be FQDN against the internal domain to allow them to resolve correctly. hosts always have a random password

Straight forward, right?

=== Keytabs ===

Keytabs are used for host-to-host authetication and preauthorization. They act as the kerberos equivelent of SSH keys, with the advantage that they can be generated on demand. Both users and hosts can have keytabs, and they can be specified to kinit to generate a ticket without passwords. This is extremely useful for cronjobs running across the network (backup and icinga), as we can easily nuke the account by blowing away the kerberos principle. We should never use SSH private keys internally; kerberos is easier to manage, and it validates rdns as it goes in an attempt to help prevent spoofing attacks.

== kadmin ==

To access kadmin, you need to autheticate as an administrator and get a ticket. You should use the krb/admin account, the password is in the master_password file on helium.

<pre>mcasadevall@lithium:~# kinit krb/admin # (password is in master_passwd on ldap-master)
Password for krb/admin@LI694-22: 
mcasadevall@lithium:~$ kadmin
Authenticating as principal krb/admin@LI694-22 with password.
Password for krb/admin@LI694-22: 
kadmin:
</pre>

Kerberos admins are controlled by an ACL on the master server (helium) in /etc/krb5kdc/kadmin.acl

'''NOTE:''' if you're on helium, you can also use kadmin.local to edit the kerberos realm. This edits the realm directly instead of of going through the DB. This is useful if we're locked out due to kerberos loosing its mind. It functions identically to kadmin expect you don't need to kinit first.

=== Seeing What's In Kerberos ===
The list_principles command is used for this purpose

<pre>kadmin:  list_principals 
K/M@LI694-22
audioguy@LI694-22
host/boron.li694-22@LI694-22
host/carbon.li694-22@LI694-22
...
</pre>

=== Creating Users ===

Creating users is the most common task, and doing so is very simple. Just add_principle, set a password, and you're done

'''add_principal martyb'''

<pre>kadmin:  add_principal martyb
WARNING: no policy specified for martyb@LI694-22; defaulting to no policy
Enter password for principal "martyb@LI694-22": 
Re-enter password for principal "martyb@LI694-22": 
Principal "martyb@LI694-22" created.
kadmin:  q
root@helium:/root# 
</pre>

=== Creating hosts ===
'''NOTE: You shouldn't need to do this under normal cirmstances except during host setup. Changing a hosts principle will break tickets issued and require users to kdestroy them.'''

See the node setup guide for a more in-depth instructions. Creating a host principle is similar to a user except we generate a random password (which isn't used for anything since hosts use keytabs), then generate a keytab. You must be root to write the keytab file

'''add_principal -randkey host/carbon.li694-22@LI694-22'''
'''ktadd host/carbon.li694-22@LI694-22'''

<pre>kadmin: add_principal -randkey host/carbon.li694-22@LI694-22
WARNING: no policy specified for host/carbon.li694-22@LI694-22; defaulting to no policy
add_principal: Principal or policy already exists while creating "host/carbon.li694-22@LI694-22".
kadmin: ktadd host/carbon.li694-22@LI694-22
(lots of information)
kadmin: quit</pre>

=== Deleting Principles ===

Deletion is done with the delete_principle command. This will cause tickets to fail to validate, and for hosts, require a new keytab be generated. This shouldn't be a frequent operation

== Creating keytabs ==

keytabs, as described above can allow something to generate a kerberos ticket without a password. They can be used with the kinit command in shell scripts to do single-sign on.

<pre>kinit -k -t $KEYTAB $USER</pe>

They're generated by a kerberos admin with the ktadd command

<pre>kadmin: ktadd -k *filename* *principle</pre>

Treat these like SSH private keys, and read only to the user that can access it. 

== KRB5 Replication ==

TBD, I have it semi-working, *but* replication disabled. Document it when its fully setup