Agent Order on Behalf

Use SLAS Trusted Agent on Behalf (TAOB) functionality in your PWA Kit application to allow agents to place orders on behalf of customers. PWA Kit comes with TAOB authentication hooks. Learn how to use these and check out sample code for implementing order-on-behalf UI components.

• Familiarize yourself with the SLAS Trusted Agent on Behalf documentation to understand the auth flows, client requirements, and requirements for Business Manager users to login and place orders on behalf of customers.
• Ensure the private SLAS client used by PWA Kit is configured with the sfcc.ta_ext_on_behalf_of scope.

The @salesforce/commerce-sdk-react package in PWA Kit contains a useTrustedAgent React hook. This hook allows inspection of the agent state as well as actions to log in and log out agents via Account Manager (AM).

The login(loginId?: string, usid?: string, refresh = false) action handles the complete agent login flow within the agent's browser:

1. The hook invokes the getTrustedAgentAuthorizationToken SLAS API. This API returns a login URL at Salesforce B2C Commerce Account Manager (AM) for the agent to authenticate. If provided, the loginId and usid parameters are included in the request. A loginId value of guest can be used to login as a guest user.
2. The hook opens this URL in a browser "popup" window and the agent authenticates with AM.
3. Upon successful authentication, AM redirects to a URL (the /callback redirectURI used by PWA Kit and configured on your SLAS client) that includes an authorization code.
4. The popup handling code reads this authorization code and uses it to invoke the getTrustedAgentAccessToken SLAS API to exchange the code for an access token. This access token replaces the normal access token used by the PWA Kit application to make authenticated requests to SLAS APIs.
5. The hook updates its internal state to reflect that an agent is now logged in (isAgent is true and agentId and loginId are populated).

From this point onward, all SCAPI API requests made by the PWA Kit application will be made on behalf of the customer represented by the trusted agent access token. The agent can now place orders on behalf of customers.

To log out the agent and revert to normal customer authentication, simply call the logout() action provided by the hook. This will clear the trusted agent access token and revert to the normal customer access token.

TAOB access tokens have a limited lifetime (default is 15 minutes). If the agent is still active after the token expires, the PWA Kit application can call the login action again with the refresh parameter set to true to obtain a new access token. Agent access tokens don't support refresh tokens. This refresh parameter is instead used to re-initiate the full login flow described above but keeps the popup from being focused. Since the agent would have recently been authenticated with AM, they don't need to re-enter their credentials and the authentication can complete seamlessly.

The normal refresh handling flow in PWA Kit automatically invokes the login action in this manner when an agent access token is present.

This sample code implements a new component, a TrustedAgentBanner. We place this component in our PWA Kit applications app/components directory.

This component displays a banner at the top of the page when an agent is logged in or when the showAgentBanner query parameter is present in the URL. It shows the agent ID and login ID when available, and provides a form for logging in as an agent or a button to logout.

Let's add this component to our PWA Kit application's main layout so that it appears on all pages. Open the app/_app/index.jsx file and import the TrustedAgentBanner component at the top:

This places the TrustedAgentBanner above the main Header component. Remember this will only display when an agent is logged in or when the showAgentBanner query parameter is present.

Finally we need to make a small change to our apps ssr.js file in the Express handler for the /callback route. This route is used by PWA Kit to handle OAuth redirects. We need to ensure it returns a proper content type to be loaded in our popup window. Open the ssr.js file and locate the /callback route handler. Update it as follows, adding the Content-Type header:

Now when we test our application, the trusted agent banner should appear by adding a showAgentBanner query parameter to the URL. For example: http://localhost:3000/?showAgentBanner.

We can enter a customer login ID or simply click Login to login as a guest user. This action opens the Account Manager login page in a popup window. After authenticating, the banner updates to show the agent is logged in:

The previous solution uses a banner to allow agents to log in from within the PWA Kit application. In some cases, you may want to allow agents to log in from an external application or portal. This portal could have already initiated the Account Manager login process and therefore an active AM session already exists. In this case, we can adjust the TrustedAgentBanner component to accept a query parameter with the target customer ID and automatically trigger the login flow. Update the TrustedAgentBanner component as follows:

In this example, we read a new trustedAgentCustomerID query parameter. If this parameter is present and no agent is currently logged in, we automatically call the login action with this customer ID (this can be set to guest as well) and set the refresh parameter to true (because an Account Manager Session already exists). The login action triggers the login flow in the background without focusing the popup window.