authz.rst (8146B)
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