User authentication

Pusher provides mechanisms for both authenticating and authorizing users. Our definition of this is that the former identifies who a user is, while the latter controls access by a given user to certain resources.

Since your servers are the authority on who your users are, and what they can access, our client libraries will make requests to endpoints of your choice to supply signed authentication and authorization tokens for the bearing user.

This page discusses how to use the user authentication functionality from the Pusher Channels client libraries.

We authenticate a user once per connection session. Authenticating a user gives your application access to user based features such as sending events to a user based on user id or terminating a user’s connections immediately.

Authentication happens when your application calls the signin method. It’s behaviour depends on the configuration provided to the Pusher object constructor through the userAuthentication parameter object. Below are the available configuration options with their default values. Check the Connection page for an overview of the parameters.

const pusher = new Pusher(APP_KEY, {
  userAuthentication: {
    endpoint: "/pusher/user-auth",
    transport: "ajax",
    params: {},
    headers: {},
    paramsProvider: null,
    headersProvider: null,
    customHandler: null,
  },
});

PusherOptions options =
  new PusherOptions()
    .setUserAuthenticator(new HttpUserAuthenticator("https://example.com/pusher/user-auth"));

Pusher pusher = new Pusher(APP_KEY, options);

pusher = new Pusher(APP_KEY, new PusherOptions()
  {
    Cluster = APP_CLUSTER,
    UserAuthenticator = new HttpUserAuthenticator("http://example.com/pusher/user-auth")
  });

∞ Sign in

When the signin method is called, the user authentication process will be triggered.

pusher.signin();

pusher.signin();

pusher.User.Signin();

This will cause the client library to call the user authentication endpoint on your application server or to use your custom handler if that was provided to retrieve a signed authentication token and user information. These are then sent to Pusher servers for sign in. A successful sign in will result in the client receiving a pusher:signin_success event. In case of error, the client receives a pusher:error event.

∞ Additional headers and parameters in the user authentication request

Depending on your application’s needs, you might need to add more information to the user authentication request made to your server’s endpoint. This can be done by adding extra parameters or headers to the request. These are set up when initializing the Pusher object.

const pusher = new Pusher(APP_KEY, {
  userAuthentication: {

    // Parameters to be added to every request
    params: { param1: 'example-1' },

    // Headers to be added to every request
    headers: { header1: 'example-2' },

    // This function is called on every request and the parameters returned are
    // added to the request
    paramsProvider: () => { return { param2: 'example-3' }; },

    // This function is called on every request and the headers returned are
    // added to the request
    headersProvider: () => { return { header2: 'example-4' }; },
  },
});

∞ Events

See binding to events for general information about how to bind to events on the connection or on the user object.