diff options
author | Sol Jerome <solj@ices.utexas.edu> | 2009-12-23 03:23:47 +0000 |
---|---|---|
committer | Sol Jerome <solj@ices.utexas.edu> | 2009-12-23 03:23:47 +0000 |
commit | b60cbe84484c5c71e7d3ebe9b4a47154e227d95f (patch) | |
tree | 577d00c0d91c7cbac4102a5b263261f387364644 /doc/authentication.txt | |
parent | 4bd571c6af51a7c1f8c1ec2e2c1a55d232405b65 (diff) | |
download | bcfg2-b60cbe84484c5c71e7d3ebe9b4a47154e227d95f.tar.gz bcfg2-b60cbe84484c5c71e7d3ebe9b4a47154e227d95f.tar.bz2 bcfg2-b60cbe84484c5c71e7d3ebe9b4a47154e227d95f.zip |
doc: Add RST layout from Thorsten Lockert
All unsorted docs can be found at doc/unsorted/index.txt.
Signed-off-by: Sol Jerome <solj@ices.utexas.edu>
git-svn-id: https://svn.mcs.anl.gov/repos/bcfg/trunk/bcfg2@5630 ce84e21b-d406-0410-9b95-82705330c041
Diffstat (limited to 'doc/authentication.txt')
-rw-r--r-- | doc/authentication.txt | 129 |
1 files changed, 129 insertions, 0 deletions
diff --git a/doc/authentication.txt b/doc/authentication.txt new file mode 100644 index 000000000..aa741903d --- /dev/null +++ b/doc/authentication.txt @@ -0,0 +1,129 @@ +.. -*- mode: rst -*- + +============== +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. :doc:`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 + fingerprint = d8b7423da5d8ccd0f3db29742fc8eed00b9d0848 + + [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. The +fingerprint needs to be manually set, per-server, using the output of +"bcfg2-admin fingerprint". + +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 +==================================== + +As of 1.0pre3, 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 + +#. 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 | + +---------------+------------------------------------------+ |