@lwrjs/auth-middleware

The @lwrjs/auth-middleware package contains middleware that authenticates to a Salesforce Connected App. Once LWR app developers authenticate, they can make requests to their Salesforce org. The middleware works with Express and Koa LWR server types.

Before you can use LWR authentication middleware, you have to set up a Connected App.

Follow the instructions in Enable OAuth Settings for API Integration to complete this setup.

During this setup, make sure you:

Select options for a Web Server Flow, not Device or JWT flows.
Take note of the Consumer Key and Consumer Secret. You can also find these values later in the App Manager.

To keep the following information secure and out of the codebase, it's passed to the LWR server by environment variables.

The public OAuth identifier for the Connected app. It's also referred to as the consumer key or the client ID.

The password corresponding to the CLIENT_KEY. It's also referred to as the consumer secret. The client key is known only to the Connected App and the LWR server.

The domain of the Salesforce org. This value is not always the same as the org's URL in your browser, so we recommend that you use the My Domain login URL in Setup > My Domain.

If you don't set a value for MY_DOMAIN, it uses the default value https://login.salesforce.com for the login server.

If a login request already has a login_server query parameter, that parameter overrides MY_DOMAIN for that login request.

You can attach the LWR authentication middleware when you create your LWR server, as seen in the example below. The platformWebServerAuthMiddleware uses the OAuth 2.0 Web Server Flow for Web App Integration.

The middleware takes the following arguments.

Argument	Type	Required/Optional	Description
`lwrApp`	LWR app instance	Required	An LWR app instance from `createServer()`. It's compatible with Express and Koa LWR server types. Do not use `lwrApp.getInternalServer()`, which returns either the underlying Express server or the underlying Koa server.
`proxyEndpoint`	String	Optional	The endpoint that proxies all its requests to the Salesforce org with the OAuth token in an Authorization header. If you don't set `proxyEndpoint`, the default value is `/services/data`.

LWR authentication middleware provides these endpoints.

This endpoint triggers the OAuth flow to let the current user log in. It's accessed from the LWR app's client code.

/login takes this query parameter.

Query Parameter	Required/Optional	Description
`app_path`	Optional	You can set `app_path` to the path and parameters that the LWR server should redirect to after authentication. This value has to be URL encoded. For example, `app_path` accepts values like `%2Fhome` and `%2Flist%3Fsort%3Ddesc`. If you don't set `app_path`, `/login` uses the default value `/`.

/revoke triggers a revoke of the access token. It's accessed from the LWR app's client code. Call this endpoint whenever a user logs out of the LWR app client.

Requests sent to this endpoint are proxied to the Salesforce org with the OAuth token.

You can optionally pass this endpoint into the platformWebServerAuthMiddleware. For more information, see the table of arguments in LWR Middleware Configuration

Let's walk through a basic example of how to use LWR middleware in an LWR app.

First, add the middleware to the LWR server.

Start the LWR server, then use the environment variables CLIENT_KEY and CLIENT_SECRET to pass in information from a Salesforce Connected App.

Now, authenticate by accessing the /login endpoint from the LWR app.

Finally, you can make authenticated requests from your LWR app through the proxy endpoint.