description: WebSocket Configuration Example

Configuration

To enable WebSocket support in the server, add a websocket configuration block in the server’s configuration file like the following:

  1. websocket {
  2.     # Specify a host and port to listen for websocket connections
  3.     #
  4.     # listen: "host:port"
  6.     # It can also be configured with individual parameters,
  7.     # namely host and port.
  8.     #
  9.     # host: "hostname"
  10.     port: 443
  12.     # This will optionally specify what host:port for websocket
  13.     # connections to be advertised in the cluster.
  14.     #
  15.     # advertise: "host:port"
  17.     # TLS configuration is required by default
  18.     #
  19.     tls {
  20.       cert_file: "/path/to/cert.pem"
  21.       key_file: "/path/to/key.pem"
  22.     }
  24.     # For test environments, you can disable the need for TLS
  25.     # by explicitly setting this option to `true`
  26.     #
  27.     # no_tls: true
  29.     # [Cross-origin resource sharing option](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS).
  30.     #
  31.     # IMPORTANT! This option is used only when the http request presents an Origin
  32.     # header, which is the case for web browsers. If no Origin header is present,
  33.     # this check will not be performed.
  34.     #
  35.     # When set to `true`, the HTTP origin header must match the request’s hostname.
  36.     # The default is `false`.
  37.     #
  38.     # same_origin: true
  40.     # [Cross-origin resource sharing option](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS).
  41.     #
  42.     # IMPORTANT! This option is used only when the http request presents an Origin
  43.     # header, which is the case for web browsers. If no Origin header is present,
  44.     # this check will not be performed.
  45.     #
  46.     # List of accepted origins. When empty, and `same_origin` is `false`, clients from any origin are allowed to connect.
  47.     # This list specifies the only accepted values for the client's request Origin header. The scheme,
  48.     # host and port must match. By convention, the absence of TCP port in the URL will be port 80
  49.     # for an "http://" scheme, and 443 for "https://".
  50.     #
  51.     # allowed_origins [
  52.     #    "http://www.example.com"
  53.     #    "https://www.other-example.com"
  54.     # ]
  56.     # This enables support for compressed websocket frames
  57.     # in the server. For compression to be used, both server
  58.     # and client have to support it.
  59.     #
  60.     # compression: true
  62.     # This is the total time allowed for the server to
  63.     # read the client request and write the response back
  64.     # to the client. This includes the time needed for the
  65.     # TLS handshake.
  66.     #
  67.     # handshake_timeout: "2s"
  69.     # Name for an HTTP cookie, that if present will be used as a client JWT.
  70.     # If the client specifies a JWT in the CONNECT protocol, this option is ignored.
  71.     # The cookie should be set by the HTTP server as described [here](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#restrict_access_to_cookies).
  72.     # This setting is useful when generating NATS `Bearer` client JWTs as the
  73.     # result of some authentication mechanism. The HTTP server after correct
  74.     # authentication can issue a JWT for the user, that is set securely preventing
  75.     # access by unintended scripts. Note these JWTs must be [NATS JWTs](https://docs.nats.io/nats-server/configuration/securing_nats/jwt).
  76.     #
  77.     # jwt_cookie: "my_jwt_cookie_name"
  79.     # If no user name is provided when a websocket client connects, will default
  80.     # this user name in the authentication phase. If specified, this will
  81.     # override, for websocket clients, any `no_auth_user` value defined in the
  82.     # main configuration file.
  83.     # Note that this is not compatible with running the server in operator mode.
  84.     #
  85.     # no_auth_user: "my_username_for_apps_not_providing_credentials"
  87.     # See below to know what is the normal way of limiting websocket clients
  88.     # to specific users.
  89.     # If there are no users specified in the configuration, this simple authorization
  90.     # block allows you to override the values that would be configured in the
  91.     # equivalent block in the main section.
  92.     #
  93.     # authorization {
  94.     #     # If this is specified, the client has to provide the same username
  95.     #     # and password to be able to connect.
  96.     #     # username: "my_user_name"
  97.     #     # password: "my_password"
  98.     #
  99.     #     # If this is specified, the password field in the CONNECT has to
  100.     #     # match this token.
  101.     #     # token: "my_token"
  102.     #
  103.     #     # This overrides the main's authorization timeout. For consistency
  104.     #     # with the main's authorization configuration block, this is expressed
  105.     #     # as a number of seconds.
  106.     #     # timeout: 2.0
  107.     #}
  108. }

Authorization of WebSocket Users

Authentication

NATS supports different forms of authentication for clients connecting over WebSocket:

  • username/password
  • token
  • NKEYS
  • client certificates
  • JWTs

You can get some more information about how applications connecting over WebSocket can use those different forms of authentication here

Restricting connection types

A new field when configuring users allows you to restrict which type of connections are allowed for a specific user.

Consider this configuration:

  1. authorization {
  2.   users [
  3.     {user: foo password: foopwd, permission: {...}}
  4.     {user: bar password: barpwd, permission: {...}}
  5.   ]
  6. }

If a WebSocket client were to connect and use the username foo and password foopwd, it would be accepted. Now suppose that you would want the WebSocket client to only be accepted if it connected using the username bar and password barpwd, then you would use the option allowed_connection_types to restrict which type of connections can bind to this user.

  1. authorization {
  2.   users [
  3.     {user: foo password: foopwd, permission: {...}}
  4.     {user: bar password: barpwd, permission: {...}, allowed_connection_types: ["WEBSOCKET"]}
  5.   ]
  6. }

The option allowed_connection_types (also can be named connection_types or clients) as you can see is a list, and you can allow several types of clients. Suppose you want the user bar to accept both standard NATS clients and WebSocket clients, you would configure the user like this:

  1. authorization {
  2.   users [
  3.     {user: foo password: foopwd, permission: {...}}
  4.     {user: bar password: barpwd, permission: {...}, allowed_connection_types: ["STANDARD", "WEBSOCKET"]}
  5.   ]
  6. }

The absence of allowed_connection_types means that all types of connections are allowed (the default behavior).

The possible values are currently:

  • STANDARD
  • WEBSOCKET
  • LEAFNODE
  • MQTT

Leaf nodes connections

You can configure remote Leaf node connections so that they connect to the Websocket port instead of the Leaf node port. See Leafnode section.

Docker

When running on Docker, WebSocket is not enabled by default, so you’ll have to create a configuration file with the minimal entries, such as:

  1. websocket 
  2. {
  3.      port: 8080
  4.      no_tls: true
  5. }

Assuming the configuration was stored in /tmp/nats.conf, you can start docker as follows:

  1. docker run -it --rm  -v /tmp:/container -p 8080:8080 nats -c /container/nats.conf