diff --git a/SUMMARY.md b/SUMMARY.md index c627812..2dce020 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -75,6 +75,8 @@ * [Securing Connections](developer/security/intro.md) * [Authenticating with a User and Password](developer/security/userpass.md) * [Authenticating with a Token](developer/security/token.md) + * [Authenticating with an NKey](developer/security/nkey.md) + * [Authenticating with a Credentials File](developer/security/creds.md) * [Encrypting Connections with TLS](developer/security/tls.md) * [Receiving Messages](developer/receiving/intro.md) diff --git a/_examples/connect_creds.html b/_examples/connect_creds.html new file mode 100644 index 0000000..8f8725d --- /dev/null +++ b/_examples/connect_creds.html @@ -0,0 +1,24 @@ + +
+ + + + + + + + +
+ 
Options options = new Options.Builder().
+            server("nats://localhost:4222").
+            authHandler(Nats.credentials("path_to_creds_file")).
+            build();
+Connection nc = Nats.connect(options);
+
+// Do something with the connection
+
+nc.close();
+
+
+ +
diff --git a/_examples/connect_nkey.html b/_examples/connect_nkey.html new file mode 100644 index 0000000..23ed26d --- /dev/null +++ b/_examples/connect_nkey.html @@ -0,0 +1,45 @@ + +
+ + + + + + + + +
+ 
NKey theNKey = NKey.createUser(null); // really should load from somewhere
+Options options = new Options.Builder().
+            server("nats://localhost:4222").
+            authHandler(new AuthHandler(){
+                public char[] getID() {
+                    try {
+                        return theNKey.getPublicKey();
+                    } catch (GeneralSecurityException|IOException|NullPointerException ex) {
+                        return null;
+                    }
+                }
+
+                public byte[] sign(byte[] nonce) {
+                    try {
+                        return theNKey.sign(nonce);
+                    } catch (GeneralSecurityException|IOException|NullPointerException ex) {
+                        return null;
+                    }
+                }
+
+                public char[] getJWT() {
+                    return null;
+                }
+            }).
+            build();
+Connection nc = Nats.connect(options);
+
+// Do something with the connection
+
+nc.close();
+
+
+ +
diff --git a/developer/security/creds.md b/developer/security/creds.md new file mode 100644 index 0000000..b1ad637 --- /dev/null +++ b/developer/security/creds.md @@ -0,0 +1,5 @@ +# Authenticating with an NKey + +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. Given a creds file, a client can authenticate as a specific user belonging to a specific account: + +!INCLUDE "../../_examples/connect_creds.html" \ No newline at end of file diff --git a/developer/security/nkey.md b/developer/security/nkey.md new file mode 100644 index 0000000..5391f1a --- /dev/null +++ b/developer/security/nkey.md @@ -0,0 +1,7 @@ +# 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 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 insures security by insuring 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" \ No newline at end of file