Single Sign-On (SSO) / Shared Authentication

FoxyCart's SSO allows you to send an authenticated user from your own site to your FoxyCart checkout without needing to re-enter their username (email address) and password. In order to increase security and greatly reduce security risks, shared-authentication checkouts still require the customer to enter certain aspects of their payment information. As of v051, a shared-authentication customer can re-use a previously saved credit card, but the CSC must be entered.

This allows for a few interesting options in addition to just shared-authentication:

• Checkout can be made entirely “private”, requiring authentication (through your own system) prior to allowing purchase. This could allow for members-only stores or other secure ordering or customer pre-screening opportunities.
• Prior to passing a customer on to the checkout the customer's cart could be retrieved (using the JSONP functionality) and validated to ensure they:
  • aren't ordering more or less items than may be required;
  • aren't getting a discount or price range they aren't authorized to get;
  • have entered any additional information (referrer values, coupon codes, etc.);
  • have registered through your system's own registration process;
  • have been presented with cross-sell or up-sell opportunities.

• FoxyCart v051+.
• A functional site + FoxyCart setup, using the API to synchronize customer records with your own user database.

The basic idea of SSO is as follows:

1. User creates an account or logs into SITE.
2. On any user creation or modification, the SITE synchs the user's information with FoxyCart's customer records, using the API.
3. When the user attempts to load the SITE's FoxyCart checkout (ie. from clicking “checkout” on the cart, from a direct to checkout request, etc.), the checkout redirects the user back to the SSO endpoint as configured in your FoxyCart store settings.
4. The SITE's endpoint checks the current user's authentication status (on the SITE). This is possible because the endpoint is (probably) on the same domain as the SITE (where the initial authentication and any cookie-based sessions reside), and thus can access whatever session information might be available (such as the COOKIE headers).
5. Based on the SITE's shared-authentication endpoint, the script can:
   • Redirect the user to the checkout, authenticated;
   • Redirect the user to the checkout, not authenticated; or
   • Take other action, such as redirect the user to a login or registration page, or deny checkout altogether.

Read the above overview first. Then take note of some of the details below.

• WHEN: On every checkout request submitted to FoxyCart, the checkout will redirect back to your shared-authentication endpoint unless a valid authentication token (fc_auth_token) is passed in.
• WHAT: When the checkout redirects the user back to your shared-authentication endpoint two additional values are passed in as well, as GET parameters:
  • fcsid: The user's FoxyCart session id. This is necessary to maintain the session across domains, particularly important when a store is not using a custom subdomain and the user has third-party cookies disabled.
  • timestamp: The epoch time on the FoxyCart server. It is important to note that this value is basically provided just in case you want to confirm that times are synched properly. This value should not be used for anything but confirming that the timestamp you hash and return (below) is indeed in the future as far as FoxyCart is concerned.

If shared-authentication is enabled, the checkout will not load unless a valid fc_auth_token (and other supporting information) is passed in (by your endpoint when it redirects the user). Here's what the checkout expects and requires.

• fc_auth_token: The authentication token is a SHA-1 hash of the FoxyCart customer ID (available through the API), the expiration timestamp, and the store's FoxyCart API key. These values are separated by | (the pipe symbol). Here's what it might look like in PHP:

  $auth_token = sha1($customer_id . '|' . $timestamp . '|' . $foxycart_api_key);

  or in Ruby:

  Digest::SHA1.hexdigest("#{customer_id}|#{timestamp}|#{foxycart_api_key}")

  • It is critically important to note that the timestamp value you hash must match the timestamp value you send in the clear (below). Again, the timestamp provided to your endpoint must not be used when passed back to FoxyCart, as that timestamp will already be in the past.
• fcsid: The FoxyCart session ID. This is necessary to prevent issues with users with 3rd party cookies disabled and stores that are not using a custom subdomain.
• fc_customer_id: INTEGER. The customer ID, as determined and stored when the user is first created or synched using the API. NOTE: If a customer is not authenticated and you would like to allow them through to checkout, enter a customer ID of 0 (the number).
• timestamp: INTEGER, epoch time. The future time that this authentication token will expire. If a customer makes a checkout request with an expired authentication token, then FoxyCart will redirect them to the endpoint in order to generate a new token.

The completed redirect might look something like this (in PHP):

$redirect_complete = 'https://yourdomain.foxycart.com/checkout?fc_auth_token=' . $auth_token . '&fcsid=' . $fcsid . '&fc_customer_id=' . $customer_id . '&timestamp=' . $timestamp;
header('Location: ' . $redirect_complete);

Note that if you append any additional fields after the required fields above you still must separate the values with an ampersand (&). For example, if you're pre-populating the checkout fields:

$redirect_complete = 'https://yourdomain.foxycart.com/checkout?fc_auth_token=' . $auth_token . '&fcsid=' . $fcsid . '&fc_customer_id=' . $customer_id . '&timestamp=' . $timestamp . '&customer_name=' . $customer_name;
header('Location: ' . $redirect_complete);

• If the SHA-1 hash passed to FoxyCart is invalid or doesn't match the supplied cleartext values, the user is redirected back to the store's URL (as configured in the store settings). The only way this should happen is if your SSO endpoint is configured incorrectly, or if a malicious user is attempting to manipulate the redirect URL.
• If the SSO timestamp has expired, the user will be redirected back to the shared-authentication endpoint. This may result in the user then being bounced immediately back to the checkout, which can be problematic as it will appear that there was an error on checkout.
  • Set the timestamp/expiration far enough in the future (an hour or more, perhaps) to prevent issues.
  • Add a javascript alert on a setTimeout() to match your expiration setting alerting your user that their checkout session is about to expire to let your customers know that their session is about to (or has already) expired.

If you're convinced that FoxyCart is broken because you can't get SSO working, it's possible, but unlikely. Check a few common causes:

• What's your timestamp value? It must be in the future, but don't set a date in the year 24800 or something crazy. If it's in the past, that's your problem.
• The customer ID must match the FoxyCart customer ID, as retrieved in the XML datafeed or API. This isn't (usually) the ID of the customer in your database.
• The URL is pointing to checkout and not cart.
• The URL is wellformed, and doesn't have any syntax errors like missing & or =.
• The hash you're sending (in the URL) is indeed what you get by manually hashing the pieces you're sending.

If you still can't get it working, please post in our forum and we'll be happy to help.

• PHP