GitBook: [master] 326 pages and 16 assets modified

developing-with-nats/intro-2/README.md

@@ -0,0 +1,6 @@
+# Securing Connections
+
+NATS provides several forms of security, authentication, authorization and isolation. You can turn on authentication which limits access to the NATS system. Accounts allow for isolation of a subject space and groups of applications. Authorization can be used to limit individual users access to specific subjects for publish and subscribe operations. TLS can be used to encrypt all traffic between clients and the NATS system. Finally, TLS can be used to verify client identities using client certificates. By combining all of these methods you can protect access to the system and to all message flows.
+
+The client doesn't have control over access controls, but clients do provide the configurations required to authenticate with the system, bind to an account, and to require TLS.
+

developing-with-nats/intro-2/creds.md

@@ -0,0 +1,24 @@
+# Authenticating with a Credentials File
+
+The 2.0 version of NATS server introduced the idea of JWT-based authentication. Clients interact with this new scheme using a user JWT and the private key from an NKey pair. To help make connecting with a JWT easier, the client libraries support the concept of a credentials file. This file contains both the private key and the JWT and can be generated with the `nsc` tool. The contents will look like the following and should be protected because it contains a private key. This creds file is unused and only for example purposes.
+
+```text
+-----BEGIN NATS USER JWT-----
+eyJ0eXAiOiJqd3QiLCJhbGciOiJlZDI1NTE5In0.eyJqdGkiOiJUVlNNTEtTWkJBN01VWDNYQUxNUVQzTjRISUw1UkZGQU9YNUtaUFhEU0oyWlAzNkVMNVJBIiwiaWF0IjoxNTU4MDQ1NTYyLCJpc3MiOiJBQlZTQk0zVTQ1REdZRVVFQ0tYUVM3QkVOSFdHN0tGUVVEUlRFSEFKQVNPUlBWV0JaNEhPSUtDSCIsIm5hbWUiOiJvbWVnYSIsInN1YiI6IlVEWEIyVk1MWFBBU0FKN1pEVEtZTlE3UU9DRldTR0I0Rk9NWVFRMjVIUVdTQUY3WlFKRUJTUVNXIiwidHlwZSI6InVzZXIiLCJuYXRzIjp7InB1YiI6e30sInN1YiI6e319fQ.6TQ2ilCDb6m2ZDiJuj_D_OePGXFyN3Ap2DEm3ipcU5AhrWrNvneJryWrpgi_yuVWKo1UoD5s8bxlmwypWVGFAA
+------END NATS USER JWT------
+
+************************* IMPORTANT *************************
+NKEY Seed printed below can be used to sign and prove identity.
+NKEYs are sensitive and should be treated as secrets.
+
+-----BEGIN USER NKEY SEED-----
+SUAOY5JZ2WJKVR4UO2KJ2P3SW6FZFNWEOIMAXF4WZEUNVQXXUOKGM55CYE
+------END USER NKEY SEED------
+
+*************************************************************
+```
+
+Given a creds file, a client can authenticate as a specific user belonging to a specific account:
+
+!INCLUDE "../../\_examples/connect\_creds.html"
+

developing-with-nats/intro-2/nkey.md

@@ -0,0 +1,8 @@
+# Authenticating with an NKey
+
+The 2.0 version of NATS server introduces a new challenge response authentication option. This challenge response is based on a wrapper we call NKeys which uses [Ed25519](https://ed25519.cr.yp.to/) signing. The server can use these keys in several ways for authentication. The simplest is for the server to be configured with a list of known public keys and for the clients to respond to the challenge by signing it with its private key. This challenge-response ensures security by ensuring that the client has the private key, but also protects the private key from the server which never has to actually see it.
+
+Handling challenge response may require more than just a setting in the connection options, depending on the client library.
+
+!INCLUDE "../../\_examples/connect\_nkey.html"
+

developing-with-nats/intro-2/tls.md

@@ -0,0 +1,24 @@
+# Encrypting Connections with TLS
+
+While authentication limits which clients can connect, TLS can be used to check the server’s identity and optionally the client’s identity and will encrypt all traffic between the two. The most secure version of TLS with NATS is to use verified client certificates. In this mode, the client can check that it trusts the certificate sent by NATS system but the individual server will also check that it trusts the certificate sent by the client. From an application's perspective connecting to a server that does not verify client certificates may appear identical. Under the covers, disabling TLS verification removes the server side check on the client’s certificate. When started in TLS mode, a `nats-server` will require all clients to connect with TLS. Moreover, if configured to connect with TLS, client libraries will fail to connect to a server without TLS.
+
+The [Java examples repository](https://github.com/nats-io/java-nats-examples/tree/master/src/main/resources) contains certificates for starting the server in TLS mode.
+
+```bash
+> nats-server -c /src/main/resources/tls.conf
+ or
+> nats-server -c /src/main/resources/tls_verify.conf
+```
+
+## Connecting with TLS
+
+Connecting to a server with TLS is straightforward. Most clients will automatically use TLS when connected to a NATS system using TLS. Setting up a NATS system to use TLS is primarily an exercise in setting up the certificate and trust managers. Clients may also need additional information, for example:
+
+!INCLUDE "../../\_examples/connect\_tls.html"
+
+## Connecting with the TLS Protocol
+
+Some clients may support the `tls` protocol as well as a manual setting to turn on TLS. However, in that case there is likely some form of default or environmental settings to allow the TLS libraries to find certificate and trust stores.
+
+!INCLUDE "../../\_examples/connect\_tls\_url.html"
+

developing-with-nats/intro-2/token.md

@@ -0,0 +1,26 @@
+# Authenticating with a Token
+
+Tokens are basically random strings, much like a password, and can provide a simple authentication mechanism in some situations. However, tokens are only as safe as they are secret so other authentication schemes can provide more security in large installations.
+
+For this example, start the server using:
+
+```bash
+> nats-server --auth mytoken
+```
+
+The code uses localhost:4222 so that you can start the server on your machine to try them out.
+
+## Connecting with a Token
+
+!INCLUDE "../../\_examples/connect\_token.html"
+
+## Connecting with a Token in the URL
+
+Some client libraries will allow you to pass the token as part of the server URL using the form:
+
+> nats://_token_@server:port
+
+Again, once you construct this URL you can connect as if this was a normal URL.
+
+!INCLUDE "../../\_examples/connect\_token\_url.html"
+

developing-with-nats/intro-2/userpass.md

@@ -0,0 +1,36 @@
+# Authenticating with a User and Password
+
+For this example, start the server using:
+
+```bash
+> nats-server --user myname --pass password
+```
+
+You can encrypt passwords to pass to `nats-server` using a simple tool provided by the server:
+
+```bash
+> go run mkpasswd.go -p
+> password: password
+> bcrypt hash: $2a$11$1oJy/wZYNTxr9jNwMNwS3eUGhBpHT3On8CL9o7ey89mpgo88VG6ba
+```
+
+and use the hashed password in the server config. The client still uses the plain text version.
+
+The code uses localhost:4222 so that you can start the server on your machine to try them out.
+
+## Connecting with a User/Password
+
+When logging in with a password `nats-server` will take either a plain text password or an encrypted password.
+
+!INCLUDE "../../\_examples/connect\_userpass.html"
+
+## Connecting with a User/Password in the URL
+
+Most clients make it easy to pass the user name and password by accepting them in the URL for the server. This standard format is:
+
+> nats://_user_:_password_@server:port
+
+Using this format, you can connect to a server using authentication as easily as you connected with a URL:
+
+!INCLUDE "../../\_examples/connect\_userpass\_url.html"
+