diff options
author | Fabian Affolter <fabian@bernewireless.net> | 2010-11-09 00:15:43 +0100 |
---|---|---|
committer | Fabian Affolter <fabian@bernewireless.net> | 2010-11-09 00:15:43 +0100 |
commit | 391406c85d86dc931f3fdb2483a14d0f1e7e6355 (patch) | |
tree | 97fe00f6a9dcf5d821139766b213418d57b5d31b /doc/appendix/guides/authentication.txt | |
parent | 553c693618321fad2a88030b16d42d3253befaec (diff) | |
download | bcfg2-391406c85d86dc931f3fdb2483a14d0f1e7e6355.tar.gz bcfg2-391406c85d86dc931f3fdb2483a14d0f1e7e6355.tar.bz2 bcfg2-391406c85d86dc931f3fdb2483a14d0f1e7e6355.zip |
doc: Massive update
Diffstat (limited to 'doc/appendix/guides/authentication.txt')
-rw-r--r-- | doc/appendix/guides/authentication.txt | 143 |
1 files changed, 143 insertions, 0 deletions
diff --git a/doc/appendix/guides/authentication.txt b/doc/appendix/guides/authentication.txt new file mode 100644 index 000000000..b9efbb929 --- /dev/null +++ b/doc/appendix/guides/authentication.txt @@ -0,0 +1,143 @@ +.. -*- mode: rst -*- + +.. _guide-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. :ref:`NAT Howto 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 + #end if + #if $self.metadata.password != None + password = $self.metadata.password + #else + password = my-password-foobar + #end if + + [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 | + +---------------+------------------------------------------+ |