com.google.gwt.user.server.rpc

## Class XsrfTokenServiceServlet

- java.lang.Object
- - javax.servlet.GenericServlet
  - - javax.servlet.http.HttpServlet
    - - com.google.gwt.user.server.rpc.AbstractRemoteServiceServlet
      - - com.google.gwt.user.server.rpc.RemoteServiceServlet
        - - com.google.gwt.user.server.rpc.XsrfTokenServiceServlet

- All Implemented Interfaces:
    RemoteService, XsrfTokenService, SerializationPolicyProvider, java.io.Serializable, javax.servlet.Servlet, javax.servlet.ServletConfig

      public class XsrfTokenServiceServlet
      extends RemoteServiceServlet
      implements XsrfTokenService

  EXPERIMENTAL and subject to change. Do not use this in production code.

  RPC service to generate XSRF tokens.

  Sample use of `XsrfTokenService`:

  1. Add `XsrfTokenServiceServlet` to `web.xml`:

          <servlet>
            <servlet-name>xsrf</servlet-name>
            <servlet-class>
              com.google.gwt.user.server.rpc.XsrfTokenServiceServlet
            </servlet-class>
          </servlet>
          <servlet-mapping>
            <servlet-name>xsrf</servlet-name>
            <url-pattern>/gwt/xsrf</url-pattern>
          </servlet-mapping>

  2. Specify session cookie name that is used for authentication. MD5 hash of the session cookie's value will be used as an XSRF token:

          <context-param>
            <param-name>gwt.xsrf.session_cookie_name</param-name>
            <param-value>JSESSIONID</param-value>
          </context-param>

  3. To enforce XSRF token validation on each method call either mark RPC interface as XSRF protected using `XsrfProtect` annotation or extend `XsrfProtectedService` instead of RemoteService. Use `NoXsrfProtect` to mark methods as not requiring XSRF protection:

          public interface MyRpcService extends XsrfProtectedService {
            public void doStuff();
          }

  4. Ensure that RPC's servlet implementation extends `XsrfProtectedServiceServlet` instead of `RemoteServiceServlet`:

          public class MyRpcServiceServlet extends XsrfProtectedServiceServlet
              implements MyRpcService {

            public void doStuff() {
              // ...
            }
          }

  5. Obtain `XsrfToken` and set it on the RPC end point:

          XsrfTokenServiceAsync xsrf = (XsrfTokenServiceAsync)GWT.create(XsrfTokenService.class);

          ((ServiceDefTarget)xsrf).setServiceEntryPoint(GWT.getModuleBaseURL() + "xsrf");

          xsrf.getNewXsrfToken(new AsyncCallback<XsrfToken>() {
            public void onSuccess(XsrfToken result) {
              MyRpcServiceAsync rpc = (MyRpcServiceAsync)GWT.create(MyRpcService.class);
              ((HasRpcToken) rpc).setRpcToken(result);
              // make XSRF protected RPC call
              rpc.doStuff(new AsyncCallback<Void>() {
                // ...
              });

            }

            public void onFailure(Throwable caught) {
              try {
                throw caught;
              } catch (RpcTokenException e) {
                // Can be thrown for several reasons:
                //   - duplicate session cookie, which may be a sign of a cookie
                //     overwrite attack
                //   - XSRF token cannot be generated because session cookie isn't
                //     present
              } catch (Throwable e) {
                // unexpected
              }
          });

  See Also:
    `XsrfProtectedServiceServlet`, `XsrfProtect`, `NoXsrfProtect`, Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `(package private) static java.lang.String` | `COOKIE_NAME_NOT_SET_ERROR_MSG`
    `static java.lang.String` | `COOKIE_NAME_PARAM` Session cookie name initialization parameter.

    - ### Fields inherited from class com.google.gwt.user.server.rpc.AbstractRemoteServiceServlet

      `perThreadRequest, perThreadResponse`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `XsrfTokenServiceServlet()` Default constructor.
    `XsrfTokenServiceServlet(java.lang.String sessionCookieName)` Alternative constructor that accepts session cookie name instead of getting it from `ServletConfig` or `ServletContext`.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `XsrfToken` | `getNewXsrfToken()` Generates and returns new XSRF token.
    `void` | `init()` Servlet initialization.

    - ### Methods inherited from class com.google.gwt.user.server.rpc.RemoteServiceServlet

      `checkPermutationStrongName, doGetSerializationPolicy, getSerializationPolicy, loadSerializationPolicy, onAfterResponseSerialized, onBeforeRequestDeserialized, processCall, processPost, shouldCompressResponse`

    - ### Methods inherited from class com.google.gwt.user.server.rpc.AbstractRemoteServiceServlet

      `doPost, doUnexpectedFailure, getPermutationStrongName, getThreadLocalRequest, getThreadLocalResponse, onAfterRequestDeserialized, readContent`

    - ### Methods inherited from class javax.servlet.http.HttpServlet

      `doDelete, doGet, doHead, doOptions, doPut, doTrace, getLastModified, service, service`

    - ### Methods inherited from class javax.servlet.GenericServlet

      `destroy, getInitParameter, getInitParameterNames, getServletConfig, getServletContext, getServletInfo, getServletName, init, log, log`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### COOKIE_NAME_PARAM

          public static final java.lang.String COOKIE_NAME_PARAM

      Session cookie name initialization parameter.
      See Also:
        Constant Field Values

    - #### COOKIE_NAME_NOT_SET_ERROR_MSG

          static final java.lang.String COOKIE_NAME_NOT_SET_ERROR_MSG

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### XsrfTokenServiceServlet

          public XsrfTokenServiceServlet()

      Default constructor.

    - #### XsrfTokenServiceServlet

          public XsrfTokenServiceServlet(java.lang.String sessionCookieName)

      Alternative constructor that accepts session cookie name instead of getting it from `ServletConfig` or `ServletContext`.

  - ### Method Detail

    - #### getNewXsrfToken

          public XsrfToken getNewXsrfToken()

      Generates and returns new XSRF token.
      Specified by:
        `getNewXsrfToken` in interface `XsrfTokenService`

    - #### init

          public void init()

      Servlet initialization.
      Overrides:
        `init` in class `javax.servlet.GenericServlet`