50th tip on this blog, yaay!

Tech Tip #49 explained how to secure WebSockets using username/password and Servlet Security mechanisms. This Tech Tip will explain how to secure WebSockets using HTTPS/TLS on WildFly.

Lets get started!

1. Create a new keystore:
   
   <strong>keytool -genkey -alias websocket -keyalg RSA -keystore websocket.keystore -validity 10950</strong> Enter keystore password: Re-enter new password: What is your first and last name? [Unknown]: Arun Gupta What is the name of your organizational unit? [Unknown]: JBoss Middleware What is the name of your organization? [Unknown]: Red Hat What is the name of your City or Locality? [Unknown]: San Jose What is the name of your State or Province? [Unknown]: CA What is the two-letter country code for this unit? [Unknown]: US Is CN=Arun Gupta, OU=JBoss Middleware, O=Red Hat, L=San Jose, ST=CA, C=US correct? [no]: yes Enter key password for &lt;websocket&gt; (RETURN if same as keystore password): Re-enter new password:

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23

   <strong>keytool -genkey -alias websocket -keyalg RSA -keystore websocket.keystore -validity 10950</strong> Enter keystore password: Re-enter new password: What is your first and last name?   [Unknown]:  Arun Gupta What is the name of your organizational unit?   [Unknown]:  JBoss Middleware What is the name of your organization?   [Unknown]:  Red Hat What is the name of your City or Locality?   [Unknown]:  San Jose What is the name of your State or Province?   [Unknown]:  CA What is the two-letter country code for this unit?   [Unknown]:  US Is CN=Arun Gupta, OU=JBoss Middleware, O=Red Hat, L=San Jose, ST=CA, C=US correct?   [no]:  yes   Enter key password for &lt;websocket&gt;     (RETURN if same as keystore password): Re-enter new password:

   
   Used “websocket” as the convenience password.
2. Download WildFly 8.1, unzip, and copy “websocket.keystore” file in standalone/configuration directory.
3. Start WildFly as
   
   ./bin/standalone.sh

   1 2 3

   ./bin/standalone.sh

4. Connect to it using jboss-cli as:
   
   ./bin/jboss-cli.sh -c

   1 2 3

   ./bin/jboss-cli.sh -c

5. Add a new security realm as:
   
   [standalone@localhost:9990 /] /core-service=management/security-realm=WebSocketRealm:add() {"outcome" =&gt; "success"}

   1 2 3 4

   [standalone@localhost:9990 /] /core-service=management/security-realm=WebSocketRealm:add() {"outcome" => "success"}

   
   And configure it:
   
   [standalone@localhost:9990 /] /core-service=management/security-realm=WebSocketRealm/server-identity=ssl:add(keystore-path=websocket.keystore, keystore-relative-to=jboss.server.config.dir, keystore-password=websocket) { "outcome" =&gt; "success", "response-headers" =&gt; { "operation-requires-reload" =&gt; true, "process-state" =&gt; "reload-required" } }

   1 2 3 4 5 6 7 8 9 10

   [standalone@localhost:9990 /] /core-service=management/security-realm=WebSocketRealm/server-identity=ssl:add(keystore-path=websocket.keystore, keystore-relative-to=jboss.server.config.dir, keystore-password=websocket) {     "outcome" => "success",     "response-headers" => {         "operation-requires-reload" => true,         "process-state" => "reload-required"     } }

6. Add a new HTTPS listener as:
   
   [standalone@localhost:9990 /] /subsystem=undertow/server=default-server/https-listener=https:add(socket-binding=https, security-realm=WebSocketRealm) { "outcome" =&gt; "success", <span style="font-size: 13px;"> "response-headers" =&gt; {"process-state" =&gt; "reload-required"} }</span>

   1 2 3 4 5 6 7

   [standalone@localhost:9990 /] /subsystem=undertow/server=default-server/https-listener=https:add(socket-binding=https, security-realm=WebSocketRealm) {     "outcome" =&gt; "success", <span style="font-size: 13px;">    "response-headers" =&gt; {"process-state" =&gt; "reload-required"} }</span>

7. A simple sample to show TLS-based security for WebSocket is available at github.com/javaee-samples/javaee7-samples/tree/master/websocket/endpoint-wss. Clone the workspace and change directory to “websocket/endpoint-wss”. The sample’s deployment descriptor has:
   
   &lt;security-constraint&gt; &lt;web-resource-collection&gt; &lt;web-resource-name&gt;Secure WebSocket&lt;/web-resource-name&gt; &lt;url-pattern&gt;/*&lt;/url-pattern&gt; &lt;/web-resource-collection&gt; &lt;user-data-constraint&gt; &lt;transport-guarantee&gt;CONFIDENTIAL&lt;/transport-guarantee&gt; &lt;/user-data-constraint&gt; &lt;/security-constraint&gt;

   1 2 3 4 5 6 7 8 9 10 11

   <security-constraint>   <web-resource-collection>     <web-resource-name>Secure WebSocket</web-resource-name>     <url-pattern>/*</url-pattern>   </web-resource-collection>   <user-data-constraint>     <transport-guarantee>CONFIDENTIAL</transport-guarantee>   </user-data-constraint> </security-constraint>

   
   This ensures that any request coming to this application will be auto-directed to an HTTPS URL.
8. Deploy the sample by giving the command:
   
   mvn wildfly:deploy

   1 2 3

   mvn wildfly:deploy

Now accessing http://localhost:8080/endpoint-wss redirects to https://localhost:8080/endpoint-wss. The browsers may complain about self-signed certificate. For example, Chrome shows the following warning:

And Safari shows the following warning:

In either case, click on “Proceed to localhost” or “Continue” to proceed further. And then a secure WebSocket connection is established.

Another relevant point to understand is that a non-secure WebSocket connection cannot be made from an https-protected page. For example the following code in our sample:

will throw the following exception in Chrome Developer Tools:

Enjoy!

RFC 6455 provide a complete list of security considerations for WebSockets. Some of them are baked in the protocol itself, and others need more explanation on how they can be achieved on a particular server. Lets talk about some of the security built into the protocol itself:

• The Origin header in HTTP request includes only the information required to identify the principal (web page, JavaScript or any other client) that initiated the request (typically the scheme, host, and port of initiating origin). For WebSockets, this header field is included in the client’s opening handshake. This is used to inform server of the script origin generating the WebSocket connection request. The server may then decide to accept or reject the handshake request accordingly. This allows the server to protect against unauthorized cross-origin use of a WebSocket server by scripts using the WebSocket API in a browser.
  For example, if Java EE 7 WebSocket Chat sample is deployed to WildFly and accessed at localhost:8080/chat/ then the Origin header is “http://localhost:8080″. Non-browser clients may use the Origin header to specify the origin of the request. WebSocket servers should be careful about receiving such requests.
• WebSocket opening handshake from client must include Sec-WebSocket-Key and Sec-WebSocket-Version HTTP header field. XMLHttpRequest can be used to make HTTP requests, and allows to set headers as part of that request as:
  
  xhr.onreadystatechange = function () { if (xhr.readyState == 4 &amp;&amp; xhr.status == 200) { document.getElementById("myDiv").innerHTML = xhr.responseText; } } xhr.open("GET", "http://localhost:8080", true); xhr.setRequestHeader("foo", "bar"); xhr.setRequestHeader("Sec-WebSocket-Key", "myKey"); xhr.send();

  1 2 3 4 5 6 7 8 9 10 11 12 13

  xhr.onreadystatechange = function () {   if (xhr.readyState == 4 && xhr.status == 200)   {     document.getElementById("myDiv").innerHTML = xhr.responseText;   } } xhr.open("GET", "http://localhost:8080", true); xhr.setRequestHeader("foo", "bar"); xhr.setRequestHeader("Sec-WebSocket-Key", "myKey"); xhr.send();

  
  If XMLHttpRequest tries to set any header fields starting with Sec- then they are ignored. So a malicious user cannot simulate a WebSocket connection to a server by using HTML and JavaScript APIs.

In addition to these two primary ways, WebSockets can be secured using client authentication mechanism available to any HTTP servers. This Tech Tip will show how to authenticate Java EE 7 WebSockets deployed on WildFly.

Lets get started!

• Clone Java EE 7 Samples workspace:
  
  git clone https://github.com/javaee-samples/javaee7-samples.git

  1 2 3

  git clone https://github.com/javaee-samples/javaee7-samples.git

• The “websocket/endpoint-security” sample shows how client authentication can be done before the WebSocket handshake is initiated from the client. This is triggered by including the following deployment descriptor:
  
  &lt;security-constraint&gt; &lt;web-resource-collection&gt; &lt;web-resource-name&gt;WebSocket Endpoint&lt;/web-resource-name&gt; &lt;url-pattern&gt;/*&lt;/url-pattern&gt; &lt;http-method&gt;GET&lt;/http-method&gt; &lt;/web-resource-collection&gt; &lt;auth-constraint&gt; &lt;role-name&gt;g1&lt;/role-name&gt; &lt;/auth-constraint&gt; &lt;/security-constraint&gt; &lt;login-config&gt; &lt;auth-method&gt;BASIC&lt;/auth-method&gt; &lt;realm-name&gt;file&lt;/realm-name&gt; &lt;/login-config&gt; &lt;security-role&gt; &lt;role-name&gt;g1&lt;/role-name&gt; &lt;/security-role&gt;

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21

  <security-constraint>   <web-resource-collection>     <web-resource-name>WebSocket Endpoint</web-resource-name>     <url-pattern>/*</url-pattern>     <http-method>GET</http-method>   </web-resource-collection>   <auth-constraint>     <role-name>g1</role-name>   </auth-constraint> </security-constraint> <login-config>   <auth-method>BASIC</auth-method>   <realm-name>file</realm-name> </login-config> <security-role>   <role-name>g1</role-name> </security-role>

  
  Some key points to understand about this descriptor:
  • <url-pattern> indicates that any request made to this application will be prompted for authentication
  • <auth-constraint> defines the security role that can access this resource
  • <login-config> shows that file-based realm is used with basic authentication
  • <security-role> defines the security roles referenced by this application

  In our particular case, the page that creates the WebSocket connection is protected by basic authentication.

• Download WildFly 8.1, unzip, and add a new user by invoking the following script:
  ./bin/add-user.sh -a -u u1 -p p1 -g g1

  1 2 3

  ./bin/add-user.sh -a -u u1 -p p1 -g g1

  This will add user “u1″ with password “p1″ in group “g1″. The group specified here needs to match as defined in <role-name> in the deployment descriptor.

• Deploy the sample by giving the command:
  mvn wildfly:deploy

  1 2 3

  mvn wildfly:deploy

Now when the application is accessed at localhost:8080/endpoint-security then a security dialog box pops up as shown:

Enter “u1″ as the username and “p1″ as the password to authenticate. These credentials are defined in the group “g1″ which is referenced in the deployment descriptor. Any other credentials will keep bringing the dialog back.

As soon as the request is successfully authenticated, the WebSocket connection is established and a message is shown on the browser.

If you are interested in securing only the WebSocket URL then change the URL pattern from

to

In websocket.js, change the URL to create WebSocket endpoint from:

to

Note, how credentials are passed in the URL itself. As of Google Chrome 38.0.2125.104, a browser popup does not appear if only WebSocket URL requires authentication.

Next Tech Tip will explain how to secure WebSocket using wss:// protocol.