docs/system/authz.rst

   1 .. _client authorization:
   2
   3 Client authorization
   4 --------------------
   5
   6 When configuring a QEMU network backend with either TLS certificates or SASL
   7 authentication, access will be granted if the client successfully proves
   8 their identity. If the authorization identity database is scoped to the QEMU
   9 client this may be sufficient. It is common, however, for the identity database
  10 to be much broader and thus authentication alone does not enable sufficient
  11 access control. In this case QEMU provides a flexible system for enforcing
  12 finer grained authorization on clients post-authentication.
  13
  14 Identity providers
  15 ~~~~~~~~~~~~~~~~~~
  16
  17 At the time of writing there are two authentication frameworks used by QEMU
  18 that emit an identity upon completion.
  19
  20  * TLS x509 certificate distinguished name.
  21
  22    When configuring the QEMU backend as a network server with TLS, there
  23    are a choice of credentials to use. The most common scenario is to utilize
  24    x509 certificates. The simplest configuration only involves issuing
  25    certificates to the servers, allowing the client to avoid a MITM attack
  26    against their intended server.
  27
  28    It is possible, however, to enable mutual verification by requiring that
  29    the client provide a certificate to the server to prove its own identity.
  30    This is done by setting the property ``verify-peer=yes`` on the
  31    ``tls-creds-x509`` object, which is in fact the default.
  32
  33    When peer verification is enabled, client will need to be issued with a
  34    certificate by the same certificate authority as the server. If this is
  35    still not sufficiently strong access control the Distinguished Name of
  36    the certificate can be used as an identity in the QEMU authorization
  37    framework.
  38
  39  * SASL username.
  40
  41    When configuring the QEMU backend as a network server with SASL, upon
  42    completion of the SASL authentication mechanism, a username will be
  43    provided. The format of this username will vary depending on the choice
  44    of mechanism configured for SASL. It might be a simple UNIX style user
  45    ``joebloggs``, while if using Kerberos/GSSAPI it can have a realm
  46    attached ``joebloggs@QEMU.ORG``.  Whatever format the username is presented
  47    in, it can be used with the QEMU authorization framework.
  48
  49 Authorization drivers
  50 ~~~~~~~~~~~~~~~~~~~~~
  51
  52 The QEMU authorization framework is a general purpose design with choice of
  53 user customizable drivers. These are provided as objects that can be
  54 created at startup using the ``-object`` argument, or at runtime using the
  55 ``object_add`` monitor command.
  56
  57 Simple
  58 ^^^^^^
  59
  60 This authorization driver provides a simple mechanism for granting access
  61 based on an exact match against a single identity. This is useful when it is
  62 known that only a single client is to be allowed access.
  63
  64 A possible use case would be when configuring QEMU for an incoming live
  65 migration. It is known exactly which source QEMU the migration is expected
  66 to arrive from. The x509 certificate associated with this source QEMU would
  67 thus be used as the identity to match against. Alternatively if the virtual
  68 machine is dedicated to a specific tenant, then the VNC server would be
  69 configured with SASL and the username of only that tenant listed.
  70
  71 To create an instance of this driver via QMP:
  72
  73 ::
  74
  75    {
  76      "execute": "object-add",
  77      "arguments": {
  78        "qom-type": "authz-simple",
  79        "id": "authz0",
  80        "identity": "fred"
  81      }
  82    }
  83
  84
  85 Or via the command line
  86
  87 ::
  88
  89    -object authz-simple,id=authz0,identity=fred
  90
  91
  92 List
  93 ^^^^
  94
  95 In some network backends it will be desirable to grant access to a range of
  96 clients. This authorization driver provides a list mechanism for granting
  97 access by matching identities against a list of permitted one. Each match
  98 rule has an associated policy and a catch all policy applies if no rule
  99 matches. The match can either be done as an exact string comparison, or can
 100 use the shell-like glob syntax, which allows for use of wildcards.
 101
 102 To create an instance of this class via QMP:
 103
 104 ::
 105
 106    {
 107      "execute": "object-add",
 108      "arguments": {
 109        "qom-type": "authz-list",
 110        "id": "authz0",
 111        "rules": [
 112           { "match": "fred", "policy": "allow", "format": "exact" },
 113           { "match": "bob", "policy": "allow", "format": "exact" },
 114           { "match": "danb", "policy": "deny", "format": "exact" },
 115           { "match": "dan*", "policy": "allow", "format": "glob" }
 116        ],
 117        "policy": "deny"
 118      }
 119    }
 120
 121
 122 Due to the way this driver requires setting nested properties, creating
 123 it on the command line will require use of the JSON syntax for ``-object``.
 124 In most cases, however, the next driver will be more suitable.
 125
 126 List file
 127 ^^^^^^^^^
 128
 129 This is a variant on the previous driver that allows for a more dynamic
 130 access control policy by storing the match rules in a standalone file
 131 that can be reloaded automatically upon change.
 132
 133 To create an instance of this class via QMP:
 134
 135 ::
 136
 137    {
 138      "execute": "object-add",
 139      "arguments": {
 140        "qom-type": "authz-list-file",
 141        "id": "authz0",
 142        "filename": "/etc/qemu/myvm-vnc.acl",
 143        "refresh": true
 144      }
 145    }
 146
 147
 148 If ``refresh`` is ``yes``, inotify is used to monitor for changes
 149 to the file and auto-reload the rules.
 150
 151 The ``myvm-vnc.acl`` file should contain the match rules in a format that
 152 closely matches the previous driver:
 153
 154 ::
 155
 156    {
 157      "rules": [
 158        { "match": "fred", "policy": "allow", "format": "exact" },
 159        { "match": "bob", "policy": "allow", "format": "exact" },
 160        { "match": "danb", "policy": "deny", "format": "exact" },
 161        { "match": "dan*", "policy": "allow", "format": "glob" }
 162      ],
 163      "policy": "deny"
 164    }
 165
 166
 167 The object can be created on the command line using
 168
 169 ::
 170
 171    -object authz-list-file,id=authz0,\
 172            filename=/etc/qemu/myvm-vnc.acl,refresh=on
 173
 174
 175 PAM
 176 ^^^
 177
 178 In some scenarios it might be desirable to integrate with authorization
 179 mechanisms that are implemented outside of QEMU. In order to allow maximum
 180 flexibility, QEMU provides a driver that uses the ``PAM`` framework.
 181
 182 To create an instance of this class via QMP:
 183
 184 ::
 185
 186    {
 187      "execute": "object-add",
 188      "arguments": {
 189        "qom-type": "authz-pam",
 190        "id": "authz0",
 191        "parameters": {
 192          "service": "qemu-vnc-tls"
 193        }
 194      }
 195    }
 196
 197
 198 The driver only uses the PAM "account" verification
 199 subsystem. The above config would require a config
 200 file /etc/pam.d/qemu-vnc-tls. For a simple file
 201 lookup it would contain
 202
 203 ::
 204
 205    account requisite  pam_listfile.so item=user sense=allow \
 206            file=/etc/qemu/vnc.allow
 207
 208
 209 The external file would then contain a list of usernames.
 210 If x509 cert was being used as the username, a suitable
 211 entry would match the distinguished name:
 212
 213 ::
 214
 215    CN=laptop.berrange.com,O=Berrange Home,L=London,ST=London,C=GB
 216
 217
 218 On the command line it can be created using
 219
 220 ::
 221
 222    -object authz-pam,id=authz0,service=qemu-vnc-tls
 223
 224
 225 There are a variety of PAM plugins that can be used which are not illustrated
 226 here, and it is possible to implement brand new plugins using the PAM API.
 227
 228
 229 Connecting backends
 230 ~~~~~~~~~~~~~~~~~~~
 231
 232 The authorization driver is created using the ``-object`` argument and then
 233 needs to be associated with a network service. The authorization driver object
 234 will be given a unique ID that needs to be referenced.
 235
 236 The property to set in the network service will vary depending on the type of
 237 identity to verify. By convention, any network server backend that uses TLS
 238 will provide ``tls-authz`` property, while any server using SASL will provide
 239 a ``sasl-authz`` property.
 240
 241 Thus an example using SASL and authorization for the VNC server would look
 242 like:
 243
 244 ::
 245
 246    $QEMU --object authz-simple,id=authz0,identity=fred \
 247          --vnc 0.0.0.0:1,sasl,sasl-authz=authz0
 248
 249 While to validate both the x509 certificate and SASL username:
 250
 251 ::
 252
 253    echo "CN=laptop.qemu.org,O=QEMU Project,L=London,ST=London,C=GB" >> tls.acl
 254    $QEMU --object authz-simple,id=authz0,identity=fred \
 255          --object authz-list-file,id=authz1,filename=tls.acl \
 256          --object tls-creds-x509,id=tls0,dir=/etc/qemu/tls,verify-peer=yes \
 257          --vnc 0.0.0.0:1,sasl,sasl-authz=auth0,tls-creds=tls0,tls-authz=authz1