You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Move the information from the note about using PKI with ACME to the
main instructions, and update the docs to cover a cluster setup as
well.
Signed-off-by: Ruth Fuchss <[email protected]>
Copy file name to clipboardExpand all lines: doc/authentication.md
+38-13Lines changed: 38 additions & 13 deletions
Original file line number
Diff line number
Diff line change
@@ -108,26 +108,59 @@ Alternatively, the clients can provide the token directly when adding the remote
108
108
109
109
In a {abbr}`PKI (Public key infrastructure)` setup, a system administrator manages a central PKI that issues client certificates for all the LXD clients and server certificates for all the LXD daemons.
110
110
111
-
In PKI mode, TLS authentication requires that client certificates are signed be the CA.
111
+
In PKI mode, TLS authentication requires that client certificates are signed be the {abbr}`CA (Certificate authority)`.
112
112
This requirement does not apply to clients that authenticate via [OIDC](authentication-openid).
113
113
114
-
To enable PKI mode, complete the following steps:
114
+
The steps for enabling PKI mode differ slightly depending on whether you use an ACME provider in addition (see {ref}`authentication-server-certificate`).
115
115
116
-
1. Add the {abbr}`CA (Certificate authority)` certificate to all machines:
116
+
`````{tabs}
117
+
````{group-tab} Only PKI
118
+
If you use a PKI system, both the server certificates and the client certificates are issued by a secondary CA.
119
+
120
+
1. Add the CA certificate to all machines:
117
121
- Place the `client.ca` file in the clients' configuration directories (`~/.config/lxc` or `~/snap/lxd/common/config` for snap users).
118
122
- Place the `server.ca` file in the server's configuration directory (`/var/lib/lxd` or `/var/snap/lxd/common/lxd` for snap users).
123
+
124
+
```{note}
125
+
In a cluster setup, the CA certificate must be named `cluster.ca`, and the same file must be added to all cluster members.
126
+
```
127
+
119
128
1. Place the certificates issued by the CA in the clients' configuration directories, replacing the automatically generated `client.crt` and `client.key` files.
120
129
1. If you want clients to automatically trust the server, place the certificates issued by the CA in the server's configuration directory, replacing the automatically generated `server.crt` and `server.key` files.
121
130
122
-
When a client adds a PKI-enabled server as a remote, it checks the server certificate and prompts the user to trust the server certificate only if the certificate has not been signed by the CA.
131
+
```{note}
132
+
In a cluster setup, the certificate files must be named `cluster.crt` and `cluster.key`.
133
+
They must be identical on all cluster members.
134
+
```
135
+
136
+
When a client adds a PKI-enabled server or cluster as a remote, it checks the server certificate and prompts the user to trust the server certificate only if the certificate has not been signed by the CA.
123
137
1. Restart the LXD daemon.
138
+
````
139
+
````{group-tab} PKI and ACME
140
+
If you use a PKI system alongside an ACME provider, the server certificates are issued by the ACME provider, and the client certificates are issued by a secondary CA.
124
141
125
-
Note that CA-signed client certificates are not automatically trusted.
142
+
1. Place the CA certificate for the server (`server.ca`) in the server's configuration directory (`/var/lib/lxd` or `/var/snap/lxd/common/lxd` for snap users), so that the server can authenticate the clients.
143
+
144
+
```{note}
145
+
In a cluster setup, the CA certificate must be named `cluster.ca`, and the same file must be added to all cluster members.
146
+
```
147
+
148
+
1. Place the certificates issued by the CA in the clients' configuration directories, replacing the automatically generated `client.crt` and `client.key` files.
149
+
1. Restart the LXD daemon.
150
+
151
+
````
152
+
`````
153
+
154
+
#### Trusting certificates
155
+
156
+
CA-signed client certificates are not automatically trusted.
126
157
You must still add them to the server in one of the ways described in {ref}`authentication-trusted-clients`.
127
158
128
159
To automatically trust CA-signed client certificates, set the {config:option}`server-core:core.trust_ca_certificates` server configuration to true.
129
160
When `core.trust_ca_certificates` is enabled, any new clients with a CA-signed certificate will have full access to LXD.
130
161
162
+
#### Revoking certificates
163
+
131
164
To revoke certificates via the PKI, place a certificate revocation list in the server's configuration directory as `ca.crl` and restart the LXD daemon.
132
165
A client with a CA-signed certificate that has been revoked, and is present in `ca.crl`, will not be able to authenticate with LXD, nor add LXD as a remote via [mutual TLS](authentication-trusted-clients).
133
166
@@ -166,14 +199,6 @@ This can be achieved by using a reverse proxy such as [HAProxy](http://www.hapro
166
199
Here's a minimal HAProxy configuration that uses `lxd.example.net` as the domain.
167
200
After the certificate has been issued, LXD will be reachable from `https://lxd.example.net/`.
168
201
169
-
```{note}
170
-
A [PKI system](authentication-pki) can be used alongside an ACME provider to verify client certificates.
171
-
In this case, a secondary CA issues certificates to clients.
172
-
A `server.ca` and `ca.crl` file should still be added to the server's configuration directory, but server certificates must not be issued by the secondary CA, as they are managed by the ACME provider.
173
-
Client certificates issued by the secondary CA should be added to the clients' configuration directories, but the `client.ca` file *must not* be added to the clients' configuration directories.
174
-
This is because the server certificates were issued by the ACME provider and not the secondary CA.
0 commit comments