taigrr/nats.docs
1
0
Fork 0
mirror of https://github.com/taigrr/nats.docs synced 2025-01-18 04:03:23 -08:00
Code Issues Projects Releases Wiki Activity

wip

Browse Source
This commit is contained in:
Alberto Ricart 2019-05-16 15:26:01 -05:00
parent e02ebdf16e
commit 3371eddd4c
14 changed files with 407 additions and 454 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
SUMMARY.md
View File

@ -10,11 +10,14 @@
* [Flags](nats_server/flags.md)
* [Configuration](nats_server/configuration.md)
* [Securing NATS](nats_server/securing_nats.md)
* [TLS Security](nats_server/tls.md)
* [Authentication](nats_server/authentication.md)
* [TLS Authentication](nats_server/tls_auth.md)
* [Enabling TLS](nats_server/tls.md)
* [Authentication](nats_server/auth_intro.md)
* [Tokens](nats_server/tokens.md)
* [Username/Password](nats_server/username_password.md)
* [TLS Authentication](nats_server/tls_mutual_auth.md)
* [Authorization](nats_server/authorization.md)
* [Clustering](nats_server/clustering.md)
* [TLS Authentication](nats_server/cluster_tls.md)
* [Logging](nats_server/logging.md)
* [Monitoring](nats_server/monitoring.md)

13
nats_server/auth_intro.md Normal file
View File

@ -0,0 +1,13 @@
# Authentication
The NATS server provides various ways of authenticating clients:
- Token Authentication
- Username/Password credentials
- TLS Certificate
- NKEY with Challenge
- JWTs with Challenge
Authentication deals with allowing a NATS client to connect to the server.
With the exception of JWT authentication, authentication and authorization configuration is in the `authorization` block of the configuration.

111
nats_server/authentication.md
View File

@ -1,111 +0,0 @@
## NATS Server Authentication
You can enable authentication on the NATS server so that a client must authenticate its identity when connecting. The NATS server supports single user authentication via the command line or using a configuration file, and multi-user authentication via a configuration file. Single user authentication is truly single user. The server will accept one set of credentials and no other.
## Command Line Options
You can start the NATS server with single-user authentication enabled by passing in the required credentials on the command line. The following server authentication options are supported on the command line:
--user user User required for connections
--pass password Password required for connections
--auth token Authorization token required for connections
Token is mutually exclusive from user and password, so only use one of those.
For example:
```sh
nats-server -DV --user foo --pass bar
```
will allow the user `foo` to log in with the password `bar`, but no other users to access the server.
Using the command line with an authorization token:
```sh
nats-server -DV -auth 'S3Cr3T0k3n!'
```
will allow clients with that token to connect, and no others.
## Single User Configuration Options
Single-user authentication can be configured in the configuration file:
```ascii
authorization {
user: derek
password: T0pS3cr3t
timeout: 1
}
```
If the server is part of a cluster, you can set up single-user authentication for route connections as well:
```ascii
cluster {
authorization {
user: route_user
password: T0pS3cr3tT00!
timeout: 0.5
}
}
```
Both of these configurations set a user and password as well as a connect timeout. The `auth` option can also be set to use tokens *instead of* user/password.
## Multi-User Authentication
Multi-user Authentication can only be set up in the configuration file. Users are defined in a list with user/password pairs.
For example, to define two users `alice` and `bob`:
```ascii
authorization {
users = [
{user: alice, password: foo}
{user: bob, password: bar}
]
}
```
You can also use [variables](/documentation/managing_the_server/configuration) to set user and password values. For example, here a password is declared as a variable named PASS and assigned to Joe.
```ascii
authorization {
PASS: abcdefghijklmnopqrstuvwxyz0123456789
users = [
{user: alice, password: foo}
{user: bob, password: bar}
{user: joe, password: $PASS}
]
}
```
The nats-server source code includes a tool that can be used to bcrypt passwords for the config file:
```sh
> go run mkpasswd.go -p
> password: password
> bcrypt hash: $2a$11$1oJy/wZYNTxr9jNwMNwS3eUGhBpHT3On8CL9o7ey89mpgo88VG6ba
```
This allows you to store hashed passwords instead of plain text ones.
## Client connection string
To connect to the server as an authenticated client, you can pass in the credentials in the connection string.
For example, user 'foo' with password 'bar':
```sh
nats://foo:bar@localhost:4222
```
Using token 'S3Cr3T0k3n!'
```sh
nats://S3Cr3T0k3n!@localhost:4222
```
The server also supports TLS mutual authentication documented in the [Security/Encryption section](/documentation/managing_the_server/security). Other methods are also discussed in the [developer doc](/documentation/writing_applications/secure_connection).

25
nats_server/cluster_tls.md Normal file
View File

@ -0,0 +1,25 @@
## Cluster TLS Mutual Authentication
When setting up clusters all servers in the cluster, if using TLS, will both verify the connecting endpoints and the server responses. So certificates are checked in both directions. Certificates can be configured only for the server's cluster identity, keeping client and server certificates separate from cluster formation.
```
cluster {
listen: 127.0.0.1:4244
tls {
# Route cert
cert_file: "./configs/certs/srva-cert.pem"
# Private key
key_file: "./configs/certs/srva-key.pem"
# Optional certificate authority verifying connected routes
# Required when we have self-signed CA, etc.
ca_file: "./configs/certs/ca.pem"
}
# Routes are actively solicited and connected to from this server.
# Other servers can connect to us if they supply the correct credentials
# in their routes definitions from above.
routes = [
nats-route://127.0.0.1:4246
]
}
```

8
nats_server/flags.md
View File

@ -35,11 +35,11 @@ The following options control very simple authentication:
| Flag | Description |
| :-------------------- | :-------- |
| `--user` | Required _username_ for connections. |
| `--pass` | Required _password_ for connections. |
| `--auth` | Required _authorization token_ for connections. |
| `--user` | Required _username_ for connections (exclusive of `--token`). |
| `--pass` | Required _password_ for connections (exclusive of `--token`). |
| `--auth` | Required _authorization token_ for connections (exclusive of `--user` and `--password`). |
You can read more about [autentication configuration here](authentication.md).
See [token authentication](tokens.md), and [username/password](username_password.md) for more information.
### Logging Options

77
nats_server/nkey_auth.md Normal file
View File

@ -0,0 +1,77 @@
## NKey Authentication
NATS 2.0 introduces a new highly secure public-key signature system based on [Ed25519](https://ed25519.cr.yp.to/).
With NKeys the server can verify identities without ever storing secrets on the server. The authentication system works by requiring a connecting client to provide its public key and digitally sign a challenge with its private key. The server generates a random challenge with every connection request, making it immune to playback attacks. The generated signature is validated against the provided public key, thus proving the identity of the client. If the public key is known to the server, authentication succeeds.
> NKey is an awesome replacement for token authentication, because a connecting client will have to prove it controls the private key for the authorized public key.
### Installing nk
To get started with NKeys, you’ll need the `nk` tool from https://github.com/nats-io/nkeys/nk repository. If you have _go_ installed, enter the following at a command prompt:
```bash
> go get github.com/nats-io/nk
```
### Generating NKeys and Configuring the Server
To generate a _User_ NKEY:
```
> nk -gen user -pubout
SUACSSL3UAHUDXKFSNVUZRF5UHPMWZ6BFDTJ7M6USDXIEDNPPQYYYCU3VY
UDXU4RCSJNZOIQHZNWXHXORDPRTGNJAHAHFRGZNEEJCPQTT2M7NLCNF4
```
The first output line starts with the letter `S` for _Seed_. The second letter `U` stands for _User_. Seeds are private keys; you should treat them as secrets and guard them with care.
The second line starts with the letter `U` for _User_, and is a public key which can be safely shared.
To use nkey authentication add a user and set the `nkey` property to the public key of the user you want to authenticate:
```text
authorization: {
users: [
{ nkey: UDXU4RCSJNZOIQHZNWXHXORDPRTGNJAHAHFRGZNEEJCPQTT2M7NLCNF4 }
]
}
```
Note that the user section sets the `nkey` property (user/password/token properties are not needed). Add `permission` sections as required.
### Client Configuration
Now that you have a user nkey let's configure a client to use it for authentication. As an example, here are the connect options for the node client:
```javascript
const NATS = require(‘nats‘);
const nkeys = require('ts-nkeys’);
const nkey_seed = ‘SUACSSL3UAHUDXKFSNVUZRF5UHPMWZ6BFDTJ7M6USDXIEDNPPQYYYCU3VY’;
const nc = NATS.connect({
port: PORT,
nkey: 'UDXU4RCSJNZOIQHZNWXHXORDPRTGNJAHAHFRGZNEEJCPQTT2M7NLCNF4',
sigCB: function (nonce) {
// client loads seed safely from a file
// or some constant like `nkey_seed` defined in
// the program
const sk = nkeys.fromSeed(Buffer.from(nkey_seed));
return sk.sign(nonce);
}
});
...
```
The client provides a function that it uses to parse the seed (the private key) and sign the connection challenge.
Other NATS tooling such as `nats-pub` and `nats-sub` can directly use nkeys:
```text
nats-sub -nkey /path/to/file/storing/seed ">"
```
For examples using other supported clients, please visit
our [documentation portal](https://nats.io/documentation/writing_applications/secure_connection)

30
nats_server/securing_nats.md
View File

@ -2,34 +2,6 @@
The nats-server provides several forms of security:
- Connections can be _encrypted_ with TLS
- [Connections can be _encrypted_ with TLS](tls.md)
- Client connections can require _authentication_
- Clients can require _authorization_ for subjects the publish or subscribe to
## Server TLS Configuration
TLS server configuration revolves around two options:
- `cert_file` - the server's certificate
- `key_file` - the server's key file
You can configure tls on the configuration file:
```
tls: {
cert_file: "./server-cert.pem"
key_file: "./server-key.pem"
}
```
Or by using [server options](./flags.md#tls-options):
```
> nats-server --tls --tlscert=./server-cert.pem --tlskey=./server-key.pem
```
More advanced configurations require additional options:
- `ca_file` - a certificate file providing the trust chain for the certificate authority (CA). Used to validate client certificates.
- `verify` - set to `true` if you want to verify client certs against the `ca_file` certificate.

222
nats_server/tls.md
View File

@ -1,197 +1,55 @@
## TLS Security
## TLS Configuration
As of Release 0.7.0, the server can use modern TLS semantics for client connections, route connections, and the HTTPS monitoring port. To enable TLS on the client port add the TLS configuration section as follows:
The NATS server uses modern TLS semantics to encrypt client, route and monitoring connections.
Server configuration revolves around a `tls` map, which has the following properties:
```ascii
# Simple TLS config file
- `cert_file` - the server's certificate
- `key_file` - the server's key file
- `ca_file` - a certificate file providing the trust chain for the certificate authority (CA). Used to validate client certificates.
- `timeout` - max seconds to allow for a TLS connection upgrade (default is 2 seconds)
- `verify` - set to `true` if you want to verify client certs against the `ca_file` certificate.
listen: 127.0.0.1:4443
tls {
cert_file: "./configs/certs/server-cert.pem"
key_file: "./configs/certs/server-key.pem"
timeout: 2
}
authorization {
user: derek
password: $2a$11$W2zko751KUvVy59mUTWmpOdWjpEm5qhcCZRd05GjI/sSOT.xtiHyG
timeout: 1
The simplest configuration:
```
tls: {
cert_file: "./server-cert.pem"
key_file: "./server-key.pem"
}
```
Note: This TLS configuration is also used for the monitor port if enabled with the `https_port` option.
The server **requires** a certificate and private key. Generating self signed certs and intermediary certificate authorities is beyond the scope here, but this document can be helpful in addition to Google Search:
<a href="https://docs.docker.com/engine/articles/https/" target="_blank">https://docs.docker.com/engine/articles/https/</a>
The server can be run using command line arguments to enable TLS functionality.
Or by using [server options](./flags.md#tls-options):
```
--tls Enable TLS, do not verify clients (default: false)
--tlscert FILE Server certificate file
--tlskey FILE Private key for server certificate
--tlsverify Enable TLS, verify client certificates
--tlscacert FILE Client certificate CA for verification
> nats-server --tls --tlscert=./server-cert.pem --tlskey=./server-key.pem
[21417] 2019/05/16 11:21:19.801539 [INF] Starting nats-server version 2.0.0
[21417] 2019/05/16 11:21:19.801621 [INF] Git commit [not set]
[21417] 2019/05/16 11:21:19.801777 [INF] Listening for client connections on 0.0.0.0:4222
[21417] 2019/05/16 11:21:19.801782 [INF] TLS required for client connections
[21417] 2019/05/16 11:21:19.801785 [INF] Server id is ND6ZZDQQDGKYQGDD6QN2Y26YEGLTH6BMMOJZ2XJB2VASPVII3XD6RFOQ
[21417] 2019/05/16 11:21:19.801787 [INF] Server is ready
```
Examples using the test certificates which are self signed for localhost and 127.0.0.1.
Notice that the log indicates that the client connections will be required to use TLS. If you run the server in Debug mode with `-D` or `-DV`, the logs will show the cipher suite selection for each connected client:
```sh
> ./nats-server --tls --tlscert=./test/configs/certs/server-cert.pem --tlskey=./test/configs/certs/server-key.pem
[2935] 2016/04/26 13:34:30.685413 [INF] Starting nats-server version 0.8.0.beta
[2935] 2016/04/26 13:34:30.685509 [INF] Listening for client connections on 0.0.0.0:4222
[2935] 2016/04/26 13:34:30.685656 [INF] TLS required for client connections
[2935] 2016/04/26 13:34:30.685660 [INF] Server is ready
```
[22242] 2019/05/16 11:22:20.216322 [DBG] 127.0.0.1:51383 - cid:1 - Client connection created
[22242] 2019/05/16 11:22:20.216539 [DBG] 127.0.0.1:51383 - cid:1 - Starting TLS client connection handshake
[22242] 2019/05/16 11:22:20.367275 [DBG] 127.0.0.1:51383 - cid:1 - TLS handshake complete
[22242] 2019/05/16 11:22:20.367291 [DBG] 127.0.0.1:51383 - cid:1 - TLS version 1.2, cipher suite TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
```
Notice that the log indicates that the client connections will be required to use TLS. If you run the server in Debug mode with -D or -DV, the logs will show the cipher suite selection for each connected client.
When a `tls` section is specified at the root of the configuration it also affects the monitoring port if `https_port` option is specified. Other sections such as `cluster` can specify a `tls` block.
### TLS Timeout
The `timeout` setting enables you to control the amount of time that a client is allowed to upgrade its connection to tls. If your clients are experiencing disconnects during TLS handshake, you'll want to increase the value. However if you do be aware that a long `timeout` exposes your server to attacks where a client doesn't upgrade to TLS and thus consumes resources. Conversely, if you reduce the TLS `timeout` too much, you are likely to experience handshake errors.
```sh
[15146] 2015/12/03 12:38:37.733139 [DBG] ::1:63330 - cid:1 - Starting TLS client connection handshake
[15146] 2015/12/03 12:38:37.751948 [DBG] ::1:63330 - cid:1 - TLS handshake complete
[15146] 2015/12/03 12:38:37.751959 [DBG] ::1:63330 - cid:1 - TLS version 1.2, cipher suite TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
```
### TLS Ciphers
The server requires TLS version 1.2, and sets preferences for modern cipher suites that avoid those known with vulnerabilities. The
server's default preferences when building with Go1.5 are as follows.
```go
func defaultCipherSuites() []uint16 {
return []uint16{
// The SHA384 versions are only in Go1.5+
tls.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
tls.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
tls.TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,
tls.TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,
tls.TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
tls.TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
}
tls: {
cert_file: "./server-cert.pem"
key_file: "./server-key.pem"
# clients will fail to connect (value is too low)
timeout: 0.0001
}
```
Optionally if your organization requires a specific cipher or list of ciphers, you can configure them with the `cipher_suites` option as follows:
```ascii
tls {
cert_file: "./configs/certs/server.pem"
key_file: "./configs/certs/key.pem"
timeout: 2
cipher_suites: [
"TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384",
"TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384",
]
}
```
A list of supported cipher suites is [located here in the cipherMap variable](https://github.com/nats-io/nats-server/blob/master/server/ciphersuites.go#L21).
### Client TLS Mutual Authentication
Optionally the server can require that clients need to present certificates, and the server can be configured with a CA authority to verify the client certificates. Simply add the option `verify` the TLS configuration section as follows:
```ascii
tls {
cert_file: "./configs/certs/server-cert.pem"
key_file: "./configs/certs/server-key.pem"
ca_file: "./configs/certs/ca.pem"
verify: true
}
```
If you want the server to enforce and require client certificates as well via the command line, utilize this example.
```sh
> ./nats-server --tlsverify --tlscert=./test/configs/certs/server-cert.pem --tlskey=./test/configs/certs/server-key.pem --tlscacert=./test/configs/certs/ca.pem
```
This option simply verifies the client's certificate has been signed by the CA specified in the `ca_file` option. However, it does not map any attribute of the client's certificate to the user's identity.
To have TLS Mutual Authentication map certificate attributes to the users identity, replace the option `verify` with `verify_and_map` as shown as follows:
```ascii
tls {
cert_file: "./configs/certs/server-cert.pem"
key_file: "./configs/certs/server-key.pem"
ca_file: "./configs/certs/ca.pem"
# Require a client certificate and map user id from certificate
verify_and_map: true
}
```
There are two options for certificate attributes that can be mapped to user names. The first is the email address in the Subject Alternative Name (SAN) field of the certificate. While generating a certificate with this attribute is outside the scope of this document, we will view this with OpenSSL:
```ascii
$ openssl x509 -noout -text -in test/configs/certs/client-id-auth-cert.pem
Certificate:
-------------<truncated>-------------
X509v3 extensions:
X509v3 Subject Alternative Name:
DNS:localhost, IP Address:127.0.0.1, email:derek@nats.io
X509v3 Extended Key Usage:
TLS Web Client Authentication
-------------<truncated>-------------
```
The configuration to authorize this user would be as follows:
```ascii
authorization {
users = [
{user: "derek@nats.io", permissions: { publish: "foo" }}
]
}
```
Note: This configuration only works for the first email address if there are multiple emails in the SAN field.
The second option is to use the RFC 2253 Distinguished Names syntax from the certificate subject as follows:
```ascii
$ openssl x509 -noout -text -in test/configs/certs/tlsauth/client2.pem
Certificate:
Data:
-------------<truncated>-------------
Subject: OU=CNCF, CN=example.com
-------------<truncated>-------------
```
The configuration to authorize this user would be as follows:
```ascii
authorization {
users = [
{user: "CN=example.com,OU=CNCF", permissions: { publish: "foo" }}
]
}
```
### Cluster TLS Mutual Authentication
When setting up clusters all servers in the cluster, if using TLS, will both verify the connecting endpoints and the server responses. So certificates are checked in both directions. Certificates can be configured only for the server's cluster identity, keeping client and server certificates separate from cluster formation.
```ascii
cluster {
listen: 127.0.0.1:4244
tls {
# Route cert
cert_file: "./configs/certs/srva-cert.pem"
# Private key
key_file: "./configs/certs/srva-key.pem"
# Optional certificate authority verifying connected routes
# Required when we have self-signed CA, etc.
ca_file: "./configs/certs/ca.pem"
}
# Routes are actively solicited and connected to from this server.
# Other servers can connect to us if they supply the correct credentials
# in their routes definitions from above.
routes = [
nats-route://127.0.0.1:4246
]
}
```
```

119
nats_server/tls_auth.md
View File

@ -1,119 +0,0 @@
## TLS Authentication
TLS authentication allows a client to authenticate by presenting a TLS certificate. TLS Certificate authentication checks the client certificate’s `Subject Alternative Name` for an email address. Alternatively, you can map fields found in the client certificate’s `Subject`. If the mapped value is matched to the client's certificate, authentication succeeds.
### Enabling TLS Certificate Authentication
To enable TLS Certificate authentication, set the `verify_and_map` configuration option on the server's `tls` configuration:
```yaml
tls {
cert_file: "./server_cert.pem"
key_file: "./server_key.pem"
ca_file: "./ca.pem"
# Require a client certificate and map user ids
verify_and_map: true
}
```
### Inspecting Certificate Contents
You can easily inspect a TLS certificate using `openssl`:
```text
> openssl x509 -in client-id-auth-cert.pem -text
Certificate:
Data:
Version: 3 (0x2)
Serial Number: 17268173637974047931 (0xefa4e06edb353cbb)
Signature Algorithm: sha1WithRSAEncryption
Issuer: C=US, ST=CA, L=San Francisco, O=Apcera Inc, OU=nats.io, CN=localhost/emailAddress=derek@nats.io
Validity
Not Before: Jan 25 04:40:50 2019 GMT
Not After : Jan 24 04:40:50 2023 GMT
Subject: C=US, ST=CA, L=Los Angeles, O=Synadia Communications Inc., OU=NATS.io, CN=localhost/emailAddress=derek@nats.io
Subject Public Key Info:
Public Key Algorithm: rsaEncryption
Public-Key: (2048 bit)
Modulus:
00:9c:ec:a1:c8:51:5e:0c:85:da:a4:2c
…
Exponent: 65537 (0x10001)
X509v3 extensions:
X509v3 Subject Alternative Name:
DNS:localhost, IP Address:127.0.0.1, email:derek@nats.io
X509v3 Extended Key Usage:
TLS Web Client Authentication
Signature Algorithm: sha1WithRSAEncryption
…
```
Here's one more example, this time showing a certificate that has multiple Subject Alternative Name (SAN):
```text
openssl x509 -in /tmp/client.pem -text
Certificate:
Data:
Version: 3 (0x2)
Serial Number:
2e:9c:da:46:3a:31:05:d9:fa:1a:7c:fd:28:15:06:8d:9b:9c:76:89
Signature Algorithm: sha256WithRSAEncryption
Issuer: OU=NATS.io, CN=www.nats.io
Validity
Not Before: Apr 19 04:38:00 2019 GMT
Not After : Apr 17 04:38:00 2024 GMT
Subject: CN=www.nats.io
Subject Public Key Info:
Public Key Algorithm: rsaEncryption
Public-Key: (2048 bit)
Modulus:
00:db:64:6b:38:85:ae:e1:9b:e9:69:1d:56:91:a2:
...
45:3d:56:6b:01:52:02:0f:32:89:cd:8f:50:97:83:
fc:e3
Exponent: 65537 (0x10001)
X509v3 extensions:
X509v3 Key Usage: critical
Digital Signature, Key Encipherment
X509v3 Extended Key Usage:
TLS Web Client Authentication
X509v3 Basic Constraints: critical
CA:FALSE
X509v3 Subject Key Identifier:
0C:75:6D:8B:34:34:D4:65:04:65:69:E3:7D:77:52:B8:FD:32:53:00
X509v3 Authority Key Identifier:
keyid:0C:1B:A8:58:3A:01:C9:7F:49:43:E1:D5:0F:FF:1C:DA:BC:80:E7:B7
X509v3 Subject Alternative Name:
DNS:app.nats.dev, DNS:*.app.nats.dev
Signature Algorithm: sha256WithRSAEncryption
23:31:20:fb:db:9f:c8:e1:da:4c:81:0e:52:cf:50:b3:05:e1:
...
47:d0:94:60:18:f3:d7:59:5a:ab:9d:62:8e:f9:bb:ff:6e:b3:
3f:32:c0:21
...
```
### NATS Server Configuration
The `authorization` section of the nats-server config can specify an email (when matching values in the `Subject Alternative Name` or specific fields in the `Subject` respectively:
```yaml
authorization {
users = [
{user: “derek@nats.io”},
{user: “OU=nats.io”},
{user: “*.example.nats.io”}
]
}
```
TLS certificate authentication is available for clients as well as for cluster configurations.
### Client TLS Configuration
Client TLS configuration using the various client libraries are documented in [Encrypting Connections with TLS](https://nats.io/documentation/writing_applications/secure_connection).
Keen eyes will notice that there is no new configuration. The burden of configuration is all in the server to expose one or more details about the client's TLS certificate. Client simply needs to provide a client-side certificate.

92
nats_server/tls_mutual_auth.md Normal file
View File

@ -0,0 +1,92 @@
## Client TLS Mutual Authentication
The server can require TLS certificates from a client. When required, you can use the certificates to:
- Validate the client certificate matches a known or trusted CA
- Extract information from a trusted certificate to provide authentication
### Validating a Client Certificate
The server can verify a client certificate using CA certificate. To require verification, simply add the option `verify` the TLS configuration section as follows:
```
tls {
cert_file: "./configs/certs/server-cert.pem"
key_file: "./configs/certs/server-key.pem"
ca_file: "./configs/certs/ca.pem"
verify: true
}
```
Or via the command line:
```sh
> ./nats-server --tlsverify --tlscert=./test/configs/certs/server-cert.pem --tlskey=./test/configs/certs/server-key.pem --tlscacert=./test/configs/certs/ca.pem
```
This option simply verifies the client's certificate has been signed by the CA specified in the `ca_file` option.
## Mapping Client Certificates To An User
In addition to verifying that a client certificate was issued by a specified CA, you can use information encoded in the certificate to authenticate a client. The client wouldn't have to provide or track usernames or passwords.
To have TLS Mutual Authentication map certificate attributes to the users identity use `verify_and_map` as shown as follows:
```
tls {
cert_file: "./configs/certs/server-cert.pem"
key_file: "./configs/certs/server-key.pem"
ca_file: "./configs/certs/ca.pem"
# Require a client certificate and map user id from certificate
verify_and_map: true
}
```
> Note that `verify` was changed to `verify_and_map`.
There are two options for certificate attributes that can be mapped to user names. The first is the email address in the Subject Alternative Name (SAN) field of the certificate. While generating a certificate with this attribute is outside the scope of this document, you can view one with `openssl`:
```
$ openssl x509 -noout -text -in test/configs/certs/client-id-auth-cert.pem
Certificate:
...
X509v3 extensions:
X509v3 Subject Alternative Name:
DNS:localhost, IP Address:127.0.0.1, email:derek@nats.io
X509v3 Extended Key Usage:
TLS Web Client Authentication
...
```
The configuration to authorize this user would be as follows:
```
authorization {
users = [
{user: "derek@nats.io"}
]
}
```
> Note: This configuration only works for the first email address if there are multiple emails in the SAN field.
The second option is to use the RFC 2253 Distinguished Names syntax from the certificate subject as follows:
```
$ openssl x509 -noout -text -in test/configs/certs/tlsauth/client2.pem
Certificate:
Data:
...
Subject: OU=CNCF, CN=example.com
...
```
The configuration to authorize this user would be as follows:
```
authorization {
users = [
{user: "CN=example.com,OU=CNCF"}
]
}
```

52
nats_server/tokens.md Normal file
View File

@ -0,0 +1,52 @@
# Token Authentication
Token authentication is a string that if provided by a client, allows it to connect. It is the simplest authentication provided by the NATS server.
To use token authentication, you can just specify an `authorization` section with the `token` property set:
```
authorization {
token: "s3cr3t"
}
```
Token authentication can be used in the authorization section for clients and clusters.
Or start the server with the `--auth` flag:
```
> nats-server --auth s3cr3t
```
A client can easily connect by specifying the server URL:
```
> nats-sub -s nats://s3cr3t@localhost:4222 ">"
Listening on [>]
```
## Bcrypted Tokens
Tokens can be bcrypted enabling an additional layer of security, as the clear-text version of the token would not be persisted on server configuration file.
You can generate bcrypted tokens and passwords using the [`mkpasswd`](/nats_tools/mkpasswd.md) tool:
```
> mkpasswd
pass: dag0HTXl4RGg7dXdaJwbC8
bcrypt hash: $2a$11$PWIFAL8RsWyGI3jVZtO9Nu8.6jOxzxfZo7c/W0eLk017hjgUKWrhy
```
Here's a simple configuration file:
```
authorization {
token: "$2a$11$PWIFAL8RsWyGI3jVZtO9Nu8.6jOxzxfZo7c/W0eLk017hjgUKWrhy"
}
```
The client will still require the clear-text password to connect:
```
nats-sub -s nats://dag0HTXl4RGg7dXdaJwbC8@localhost:4222 ">"
Listening on [>]
```

54
nats_server/username_password.md Normal file
View File

@ -0,0 +1,54 @@
# Username and Password
You can authenticate one or more clients using username and passwords. This enables you to have greater control on the management and issuing of credential secrets.
For a single user:
```
authorization: {
user: a,
password: b
}
```
You can also specify a single username/password by:
```
> nats-server --user a --pass b
```
For multiple users:
```
authorization: {
users: [
{user: a, password: b},
{user: b, password: a}
]
}
```
## Bcrypted Passwords
Username/password also supports bcrypted passwords using the [`mkpasswd`](/nats_tools/mkpasswd.md) tool. Simply replace the clear text password with the bcrypted entries:
```
> mkpasswd
ass: (Uffs#rG42PAu#Oxi^BNng
bcrypt hash: $2a$11$V1qrpBt8/SLfEBr4NJq4T.2mg8chx8.MTblUiTBOLV3MKDeAy.f7u
```
And on the configuration file:
authorization: {
users: [
{user: a, password: "$2a$11$V1qrpBt8/SLfEBr4NJq4T.2mg8chx8.MTblUiTBOLV3MKDeAy.f7u"},
...
]
}
## Reloading a Configuration
As you add/remove passwords from the server configuration file, you'll want your changes to take effect. To reload without restarting the server and disconnecting clients, simply do:
```
> nats-server --signal reload
```

20
nats_tools/mkpasswd.md
View File

@ -12,30 +12,38 @@ If you have [go installed](https://golang.org/doc/install), you can easily insta
> go get github.com/nats-server/util/mkpasswd
```
Alternatively, you can
Alternatively, you can:
```
> git clone git@github.com:nats-io/nats-server
> cd nats-server/util/mkpasswd
> go build mkpasswd.go
> ./mkpasswd
> go install mkpasswd.go
```
## Generating bcrypted passwords
With `mkpasswd` installed:
```
> mkpasswd
pass: #IclkRPHUpsTmACWzmIGXr
bcrypt hash: $2a$11$3kIDaCxw.Glsl1.u5nKa6eUnNDLV5HV9tIuUp7EHhMt6Nm9myW1aS
```
If you already have a password selected, you can supply the `-p` flag on the command line, enter your desired password, and a `bcrypt` hash will be generated for it:
```
> ./mkpasswd -p
> mkpasswd -p
Enter Password: *******
Reenter Password: ******
bcrypt hash: $2a$11$3kIDaCxw.Glsl1.u5nKa6eUnNDLV5HV9tIuUp7EHhMt6Nm9myW1aS
```
Add the hash into the server configuration file's authorization section.
To use the password on the server, add the hash into the server configuration file's authorization section.
```
authorization {
user: derek
password: $2a$11$3kIDaCxw.Glsl1.u5nKa6eUnNDLV5HV9tIuUp7EHhMt6Nm9myW1aS
}
```
```
Note the client will still have to provide the plain text version of the password, the server however will only store the hash to verify that the password is correct when supplied.

29
nats_tools/nk.md Normal file
View File

@ -0,0 +1,29 @@
# NK
`nk` is a command line tool that generates `nkeys`. NKeys are a highly secure public-key signature system based on [Ed25519](https://ed25519.cr.yp.to/).
With NKeys the server can verify identity without ever storing secrets on the server. The authentication system works by requiring a connecting client to provide its public key and digitally sign a challenge with its private key. The server generates a random challenge with every connection request, making it immune to playback attacks. The generated signature is validated a public key, thus proving the identity of the client. If the public key validation succeeds, authentication succeeds.
> NKey is an awesome replacement for token authentication, because a connecting client will have to prove it controls the private key for the authorized public key.
### Installing nk
To get started with NKeys, you’ll need the `nk` tool from https://github.com/nats-io/nkeys/nk repository. If you have _go_ installed, enter the following at a command prompt:
```bash
> go get github.com/nats-io/nk
```
### Generating NKeys and Configuring the Server
To generate a _User_ NKEY:
```
> nk -gen user -pubout
SUACSSL3UAHUDXKFSNVUZRF5UHPMWZ6BFDTJ7M6USDXIEDNPPQYYYCU3VY
UDXU4RCSJNZOIQHZNWXHXORDPRTGNJAHAHFRGZNEEJCPQTT2M7NLCNF4
```
The first output line starts with the letter `S` for _Seed_. The second letter `U` stands for _User_. Seeds are private keys; you should treat them as secrets and guard them with care.
The second line starts with the letter `U` for _User_, and is a public key which can be safely shared.