Building an embedded Shopify app in Symfony: session tokens, token exchange, and the parts nobody writes in PHP

Shopify's app development guidelines are predominantly centered around the use of Node.js, including its CLI and Remix template for authentication. However, for developers working with Symfony, there are specific steps to follow to successfully embed and secure an app. This article provides a comprehensive guide on how to authenticate and secure an embedded Shopify app in Symfony 7.4, running on PHP 8.5, utilizing Shopify's App Bridge and session tokens.

The authentication process is fundamentally different from traditional PHP development due to the absence of third-party cookies in the Shopify admin iframe environment. Shopify employs a JWT, known as a session token, which is minted per request and remains valid for one minute. This token is pivotal as it permits the API calls necessary for data transactions between the Shopify admin and the embedded app.

Unlike conventional PHP applications which typically secure controllers and render data server-side, this embedded app architecture necessitates a strategy where authentication is enforced at the API level rather than at the web page level. This approach results in a clear separation between the public, unauthenticated shell and the authenticated API endpoints, fundamentally altering the typical Symfony security configuration.

The Symfony security configuration demonstrates this distinction by defining separate firewall configurations for webhooks and the embedded admin API. The webhooks firewall is designed to authenticate using HMAC signatures in the controller, while the embedded admin API requires a stateless authentication mechanism. This is explicitly configured to bypass Symfony's session storage capabilities, ensuring that the JWT session token remains secure and is not exposed to the browser through third-party cookies.

The verification of these session tokens involves five critical checks, including signature verification using the app's client secret, expiration checks with a small leeway for clock skew, audience validation to prevent token misuse across different apps, and domain verification to ensure the token is issued for the correct Shopify shop.

A key operational step in this process is the token exchange mechanism, which converts the short-lived session token into an access token required for making authenticated calls to the Shopify Admin API. This exchange is facilitated through OAuth 2.0 token exchange as defined in RFC 8693, eliminating the need for redirections and redirects for authentication.

Upon successful installation, the initial authenticated request from a new Shopify shop automatically performs this token exchange, paving the way for subsequent API requests.

Implementing these authentication and security measures in a Symfony embedded Shopify app requires meticulous attention to detail, particularly around the handling of JWT session tokens and the implementation of the token exchange process. By adhering to these guidelines, developers can create secure, efficient, and reliable embedded Shopify applications that seamlessly integrate with Shopify's ecosystem.