Skip to content

Sign in or create an account for AI agents with OAuth 2.0

time to complete
20 minutes

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.

  • 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)
  • 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-enablement Composer package.
  • A storefront that signs shoppers in with the user authentication drop-in through the commerce-login and commerce-create-account blocks.

When an agent starts an authorization request:

  1. 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.
  2. If the shopper is not signed in, the commerce-login block shows the usual sign-in form. If the shopper is already signed in, this step is skipped.
  3. The block calls the issueOauthAuthorizationCode GraphQL mutation with the customer token and the URL parameters.
  4. Commerce validates the client, the redirect URI, the scopes, and PKCE, and then returns a redirect_url that carries code, state, and iss.
  5. 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:

ParameterRequiredDescription
response_typeYesMust be code.
client_idYesID of the OAuth 2.0 client registered in the Commerce Admin.
redirect_uriYesMust exactly match a redirect URI registered for the client.
code_challengeYesPKCE challenge.
code_challenge_methodYesMust be S256.
scopeNoSpace-separated scopes.
stateNoReturned unchanged to the client.

Register the agent’s OAuth 2.0 client and configure the storefront URLs before connecting the handlers to your storefront blocks.

  1. 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.

  2. Go to Stores > Configuration > Adobe Services > Storefront MCP.

  3. 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.

  4. Save the configuration to keep the URLs.

Call each OAuth handler before the block’s existing code so it can handle the authorization request first.

  1. Copy scripts/oauth-authorize.js into your project.

  2. In scripts/commerce.js, add the create-account path export after the existing CUSTOMER_PATH definition if the export is missing:

    scripts/commerce.js
    export const CUSTOMER_CREATE_PATH = `${CUSTOMER_PATH}/create`;
  3. In blocks/commerce-login/commerce-login.js, import handleOauth and call it at the start of decorate:

    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 handleOauth returns true, it has handled the OAuth request, so return skips the regular sign-in behavior.

  4. In blocks/commerce-create-account/commerce-create-account.js, import handleOauthSignUp and call it at the start of decorate so 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.

  5. Optionally, add these keys to placeholders/auth.json to change the messages:

    KeyDefault
    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.

Test both the regular sign-in flow and the OAuth handoff for existing and new accounts.

  1. 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.

  2. 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=xyz

    Replace <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, and iss.

  3. Open the same URL while signed in.

    Confirm that the browser redirects without showing the sign-in form.

  4. 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, and iss. 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.

  5. Change redirect_uri to an unregistered value.

    Confirm that the block shows an error and does not redirect.