.. -*- mode: rst -*-

.. _authentication:

==============
Authentication
==============

Scenarios
=========

1. Cluster nodes that are frequently rebuilt

   Default settings work well; machines do not float, and a per-client
   password is not required.

2. `NAT_HOWTO <http://trac.mcs.anl.gov/projects/bcfg2/wiki/NAT_HOWTO>`_

 * Build client records in advance with bcfg2-admin, setting a uuid
   for each new client.

 * Set the address attribute for each to the address of the NAT.

 * Optionally, set a per-client password for each, and set into secure
   mode.

   .. note::

      This will require the use of the uuid and password from each
      client, and will require that they come through the NAT address.

Building bcfg2.conf automatically
=================================

This is a TCheetah template that automatically constructs per-client
bcfg2.conf from the per-client metadata::

    [communication]
    protocol = xmlrpc/ssl
    #if $self.metadata.uuid != None
    user = $self.metadata.uuid
    #endif
    #if $self.metadata.password != None
    password = $self.metadata.password
    #else
    password = my-password-foobat
    #endif

    [components]
    bcfg2 = https://localhost:6789

In this setup, this will cause any clients that have uuids established
to be set to use them in bcfg2.conf. It will also cause any clients
with passwords set to use them instead of the global password.

How Authentication Works
========================

#. First, the client is associated with a client record. If the client
   specifies a uuid, it uses this instead of the results of a dns or
   address lookup.

#. Next, the ip address is verified against the client record. If the
   address doesn't match, then the client must be set to
   location=floating

#. Finally, the password is verified. If the client is set to secure
   mode, the only its per-client password is accepted. If it is not set
   to secure mode, then either the global password or per-client password
   will be accepted

Failure during any of these stages results in authentication
failure. Note that clients set into secure mode that do not have
per-client passwords set will not be able to connect.

SSL Cert-based client authentication
====================================

SSL-based client authentication is supported. This requires several
things:

#. Certificate Authority (to sign all keys)

#. Server key and cert signed by the CA

#. Client key and cert signed by the CA

A variety of CAs can be used, but these keys can be simply generated
using the following set of steps:

#. Setup a CA

   http://www.flatmtn.com/article/setting-openssl-create-certificates

#. Create keys for each client and server, signing them with the CA
   signing cert

   http://www.flatmtn.com/article/setting-ssl-certificates-apache

   .. note::
       The client CN must be the FQDN of the client (as returned by a
       reverse DNS lookup of the ip address. Otherwise, you will end up
       with an error message on the client that looks like::

           Server failure: Protocol Error: 401 Unauthorized
	   Failed to download probes from bcfg2
	   Server Failure

       You will also see an error message on the server that looks
       something like::

           cmssrv01 bcfg2-server[9785]: Got request for cmssrv115 from incorrect address 131.225.206.122
           cmssrv01 bcfg2-server[9785]: Resolved to cmssrv115.fnal.gov

#. Distribute the keys and certs to the appropriate locations

#. Copy the ca cert to clients, so that the server can be authenticated

Clients authenticating themselves with a certificate will be
authenticated that way first; clients can be setup to either
authenticate solely with certs, use certs with a fallback to password,
or password only. Also a bootstrap mode will be added shortly; this
will allow a client to authenticate with a password its first time,
requiring a certificate all subsequent times. This behavior can be
controlled through the use of the auth attribute in
Metadata/clients.xml::

    <Clients>
      <Client name='testclient' auth='cert'/>
    </Clients>

Allowed values are:

    +---------------+------------------------------------------+
    | **Auth Type** | **Meaning**                              |
    +---------------+------------------------------------------+
    | cert          | Certificates must be used                |
    +---------------+------------------------------------------+
    | cert+password | Certificate or password may be used      |
    +---------------+------------------------------------------+
    | bootstrap     | Password can be used for one client run, |
    |               | after that certificate is required       |
    +---------------+------------------------------------------+