Sign in or create an account for AI agents with OAuth 2.0
Add an OAuth 2.0 authorization handoff to your storefront’s sign-in and create-account blocks so AI agents can act on behalf of a signed-in shopper. This handoff works with storefronts built on the Adobe Commerce boilerplate .
AI agents that use the Commerce Storefront MCP server need the shopper’s permission for account actions, such as checkout or viewing orders. Anonymous actions, such as product search, do not need that permission.
The agent uses the OAuth 2.0 authorization code flow with Proof Key for Code Exchange (PKCE). It sends the shopper to your storefront sign-in page. After the shopper signs in, the storefront returns an authorization code to the agent without sharing the shopper’s password.
What you’ll edit or create
Section titled “What you’ll edit or create”- Copy
scripts/oauth-authorize.js - Edit
scripts/commerce.js - Edit
blocks/commerce-login/commerce-login.js - Edit
blocks/commerce-create-account/commerce-create-account.js - Edit
placeholders/auth.json(optional)
Prerequisites
Section titled “Prerequisites”- Adobe Commerce with the Storefront MCP extension, which includes the OAuth 2.0 server. On Adobe Commerce as a Cloud Service, it is available by default. On Adobe Commerce on cloud infrastructure or on-premises, install the
adobe-commerce/module-storefront-mcp-enablementComposer package. - A storefront that signs shoppers in with the user authentication drop-in through the
commerce-loginandcommerce-create-accountblocks.
How it works
Section titled “How it works”When an agent starts an authorization request:
- The agent sends the shopper to the Commerce authorization endpoint with the OAuth 2.0 parameters. On Adobe Commerce as a Cloud Service, this endpoint is your sign-in page. On other deployments, it is
/oauth2ac/authorize, which forwards the parameters to your sign-in page. - If the shopper is not signed in, the
commerce-loginblock shows the usual sign-in form. If the shopper is already signed in, this step is skipped. - The block calls the
issueOauthAuthorizationCodeGraphQL mutation with the customer token and the URL parameters. - Commerce validates the client, the redirect URI, the scopes, and PKCE, and then returns a
redirect_urlthat carriescode,state, andiss. - The block redirects the browser to
redirect_url. The agent exchanges the code for tokens at the Commerce token endpoint.
If the shopper has no account, the sign-in form links to the create-account page. The pending request stays in the same browser tab. After sign-up, the commerce-create-account block signs the shopper in and continues from step 3.
If email confirmation is required, the block shows the email confirmation form. If automatic sign-in fails, it shows an account-created message with a sign-in link. In both cases, the pending request stays in the tab, so authorization continues when the shopper signs in from that tab before the request expires.
When there is no OAuth 2.0 request in the URL or stored for the tab, both blocks keep their existing behavior.
The sign-in page receives these parameters:
| Parameter | Required | Description |
|---|---|---|
response_type | Yes | Must be code. |
client_id | Yes | ID of the OAuth 2.0 client registered in the Commerce Admin. |
redirect_uri | Yes | Must exactly match a redirect URI registered for the client. |
code_challenge | Yes | PKCE challenge. |
code_challenge_method | Yes | Must be S256. |
scope | No | Space-separated scopes. |
state | No | Returned unchanged to the client. |
Configure the authorization handoff
Section titled “Configure the authorization handoff”Register the agent’s OAuth 2.0 client and configure the storefront URLs before connecting the handlers to your storefront blocks.
Configure Commerce
Section titled “Configure Commerce”-
In the Commerce Admin, go to System > Agentic Commerce > OAuth 2.0 Clients and register the agent’s client with the exact redirect URIs that it uses.
-
Go to Stores > Configuration > Adobe Services > Storefront MCP.
-
In the Storefront section, check Storefront URL and Sign-in URL.
Set Storefront URL to your storefront home page and Sign-in URL to your sign-in page, such as
https://<your-storefront>/customer/login. Replace<your-storefront>with your storefront hostname. Both fields require absolute HTTPS URLs. The Admin suggests a value for an empty field. -
Save the configuration to keep the URLs.
Add the handoff to your storefront
Section titled “Add the handoff to your storefront”Call each OAuth handler before the block’s existing code so it can handle the authorization request first.
-
Copy scripts/oauth-authorize.js into your project.
-
In
scripts/commerce.js, add the create-account path export after the existingCUSTOMER_PATHdefinition if the export is missing:scripts/commerce.js export const CUSTOMER_CREATE_PATH = `${CUSTOMER_PATH}/create`; -
In
blocks/commerce-login/commerce-login.js, importhandleOauthand call it at the start ofdecorate:blocks/commerce-login/commerce-login.js import { handleOauth } from '/scripts/oauth-authorize.js';export default async function decorate(block) {if (await handleOauth(block)) {return;}// existing block code}Keep the block’s existing code after this check. When
handleOauthreturnstrue, it has handled the OAuth request, soreturnskips the regular sign-in behavior. -
In
blocks/commerce-create-account/commerce-create-account.js, importhandleOauthSignUpand call it at the start ofdecorateso shoppers can create an account during authorization:blocks/commerce-create-account/commerce-create-account.js import { handleOauthSignUp } from '/scripts/oauth-authorize.js';export default async function decorate(block) {if (await handleOauthSignUp(block)) {return;}// existing block code}Keep the block’s existing code after this check, as in the sign-in block.
-
Optionally, add these keys to
placeholders/auth.jsonto change the messages:Key Default Auth.OAuth.redirectingRedirecting you back…Auth.OAuth.errorHeadingWe could not complete the sign-in for this app.Auth.OAuth.accountCreatedYour account was created. Sign in to continue.Auth.OAuth.signInSign in
The sign-in block stores the pending request in sessionStorage under oauth_authorization_request with a 10-minute expiry. This lets a shopper move from sign-in to account creation in the same tab without losing the request.
The entry holds no secret. The PKCE code_verifier stays with the agent, and Commerce validates the request again when it issues the code. If the new account needs email confirmation, Commerce issues no code until the shopper signs in from the same tab.
Verify the handoff
Section titled “Verify the handoff”Test both the regular sign-in flow and the OAuth handoff for existing and new accounts.
-
Open your sign-in page without parameters in a tab with no pending OAuth request.
Sign in to confirm that the block behaves as before.
-
Open the sign-in page with a valid OAuth request, using this URL as a template:
https://<your-storefront>/customer/login?response_type=code&client_id=<client-id>&redirect_uri=<registered-uri>&code_challenge=<challenge>&code_challenge_method=S256&state=xyzReplace
<your-storefront>with your storefront hostname and<client-id>with the registered client’s ID. Use the client’s registered redirect URI for<registered-uri>and its PKCE challenge for<challenge>. URL-encode the query parameter values.Sign in to confirm that the browser redirects to the registered URI with
code,state=xyz, andiss. -
Open the same URL while signed in.
Confirm that the browser redirects without showing the sign-in form.
-
Open the same URL while signed out.
Follow the create-account link and register a new shopper. After sign-up, the browser redirects to the registered URI with
code,state=xyz, andiss. If email confirmation is required, confirm the account, then open your sign-in page in the original tab and sign in. If automatic sign-in fails, use the sign-in link that the block shows. -
Change
redirect_urito an unregistered value.Confirm that the block shows an error and does not redirect.