# Part-2: Tying in with the Java EE Platform
This part, covers integration with
* Servlet, and
* Java EE Security
## Servlets and WebSockets
A WebSocket connection begins with a HTTP handshake. There is an association between `javax.servlet.http.HTTPSession` and `javax.websocket.Session`. The `HTTPSession` object can be obtained by overriding the `modifyHandshake` method in `ServerEndpointConfig.Configurator`. Once we have the it, the `ServletContext` can be easily retrieved
```
public class CustomServerEndpointConfigurator extends ServerEndpointConfig.Configurator{
...
@Override
public void modifyHandshake(ServerEndpointConfig sec, HandshakeRequest request, HandshakeResponse response) {
HttpSession httpSession = (HttpSession) request.getHttpSession();
ServletContext servletContext = httpSession.getServletContext();
...
}
}
```
> #### Lifetime of `Session`-`HTTPSession` association
>
> The WebSocket `Session` is closed if the `HTTPSession` dies (due to invalidation, timeout, user logging out etc.) - but this happens only in case the WebSocket endpoint happens to be a protected resource (more on this in the next section). The container is not obliged to kill the underlying WebSocket connection in response of closing an `HTTPSession` if it was not protected to begin with
## Integrating with Java EE Security
The WebSocket specification does not define it's own security primitives. It relies heavily on the web container (Servlet) security model can be broadly divided into declarative and programmatic styles (in terms of their usage patterns). We will explore these strategies in this sub-section
> **Recommended**: for a deep dive into Servlet security, please refer chapters 13, 14 of the latest (3.1) [Servlet specification](https://jcp.org/aboutJava/communityprocess/final/jsr340/index.html)
### Declarative security
The declarative Java EE security model is driven by the web.xml descriptor. WebSocket endpoints can benefit from the following security features - Authentication, Authorization and Secure transport. Let's look at each one of these
#### Authentication
It is driven by the `login-config` element in `web.xml` descriptor and the possible values are - BASIC, FORM, DIGEST and CLIENT-CERT
```
BASIC
file
```
To protect a WebSocket endpoint, the encapsulating resource (which acts as the WebSocket client) must be protected. A good example is a HTML page which uses the WebSocket Javascript client API to initiate a connection to the server endpoint. Once the authentication challenge is satisfied (depending upon the chosen method), the authenticated context is associated with the subsequent calls from the client to the WebSocket endpoint. Failure to authenticate results in a HTTP 401 error
#### Authorization
For declarative authorization to work, the `` settings (in tandem with other container configuration) is important. Post authentication, the authorization will kick in and only if the authenticated principal is found to be a member of the configured roles (this calculation will happen as per the application server specific setting), will the protected resource (and the WebSocket endpoint) be accessible. If not, the process will result in a HTTP 403 error
```
premium_users
```
#### Secure transport
This setting determines whether or not the communication channel is secure. From a WebSocket perspective, this is achieved by multiple configuration
* the original (protected) resource should be accessed over `https`
* the WebSocket URL must begin with `wss` (not `ws`) e.g. wss\://we-all-chat/
* `` configuration in `web.xml` should be configured
```
CONFIDENTIAL
```
### Programmatic
The programmatic aspects of security handling are taken care of by `Session` and `HandshakeRequest` objects. These are passive in nature i.e. these come into picture after the primary level of authentication (HTTP based) is over which provide methods to access the Principal object, determine whether the user is part of a specific role and whether the communication is taking place over an encrypted connection
#### `HandshakeRequest`
You can check the `Principal` as well as check for role membership of a user using the `getUserPrincipal` and the `isUserInRole` methods respectively
```
public class SecurityConfigurator extends ServerEndpointConfig.Configurator {
@Override
public void modifyHandshake(ServerEndpointConfig sec, HandshakeRequest request, HandshakeResponse response) {
System.out.println("Endpoint accessed by user - "+ req.getUserPrincipal().getName());
String roleName = "premium-users";
System.out.println("Is user in role "+ roleName + " ? " + req.isUserInRole(roleName));
}
}
```
#### `Session`
As with `HandshakeRequest`, the `Session` object also provides access to the authenticated `Principal` via the `getUserPrincipal` method along with the `isSecure` API to check whether the communication is taking place over secure (encrypted channel) i.e. `wss`
## Next chapter ..
.. looks at some of the Concurrency semantics of common WebSocket APIs
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://abhishek-gupta.gitbook.io/java-websocket-api-handbook/part-2-tying_in_with_the_java_ee_platform.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.