summaryrefslogtreecommitdiffstats
path: root/doc/appendix/guides/authentication.txt
blob: b8ec8259099ef2297016c55b7c057f4f2e093dfd (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
.. -*- mode: rst -*-

.. _appendix-guides-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:`appendix-guides-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 :ref:`Cheetah template
<server-plugins-generators-cfg-cheetah>` 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-foobat
    #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
   floating='true'

#. 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. If  |
|                   | a certificate is used, the password must |
|                   | also be used.                            |
+-------------------+------------------------------------------+
| ``bootstrap``     | Password can be used for one client run, |
|                   | after that only certificate is allowed   |
+-------------------+------------------------------------------+

``cert+password`` is the default.  This can be changed by setting the
``authentication`` parameter in the ``[communcation]`` section of
``bcfg2.conf``.  For instance, to set ``bootstrap`` mode as the global
default, you would add the following to ``bcfg2.conf``::

    [communication]
    authentication = bootstrap

``bootstrap`` mode is currently incompatible with the
:ref:`server-plugins-grouping-metadata-clients-database`.