@ordergroove/auth

Ordergroove Authentication

Given a merchant auth endpoint this function tries to resolve the current auth. If og_auth is in cookie it returns it, otherwise it call the merchant auth endpoint detecting if response is JSON or cookie set by response header and return it.

Install

npm install @ordergroove/auth --save

Usage

Node or webpack environment

import auth from '@ordergroove/auth';

const auth_url = 'http://some-merchant.com/ordergroove-auth.json';
auth.reoslveAuth(auth_url).then(auth => {
  const { sig_field, ts, sig } = auth;
  console.log(auth);
});

UMD

It's exposed as OG.auth namespace

<script src="dist/auth.js"></script>
<script>
  OG.auth.resolveAuth()
  const auth_url = 'http://some-merchant.com/ordergroove-auth.json'
  OG.auth.reoslveAuth(auth_url).then(auth =>
  	const { sig_field, ts, sig } = auth;
  	console.log(auth);
  });
</script>

API

reoslveAuth(auth_url)

Returns a promise with auth information

auth_url

Authentication endpoint in merchant site. See below how to integrate this endpoint.

Authentication endpoint

This section details how to create an authentication page for OrderGroove. Users are authenticated for the secure display of the My Subscriptions Interface and Impulse Upsell offers.

Ordergroove support 3 ways of authenticate.

• Json endpoint
• Response cookie authentication
• Static auth

JSON endpoint authentication

Json endpoint also known as ajax auth consists in merchant implementing a page that returns a JSON representation of signature.

Merchant will need to set up an GET endpoint that's only accessible over HTTPS. This endpoint should output the following as JSON:

{
"public_id": "<merchant_public_id>",
"ts": <unix_timestamp_ms>,
"sig_field": "<merchant_user_id>",
"sig": "<signature>"
}

Note: the timestamp is not in quotation marks as it should be sent as a number.

Make sure that this endpoint sends the response with the header: Content-Type: application/json

The fields are defined as follows:

public_id	Merchant Public ID. OrderGroove's identifier of PetSupermarket in our system	8e09fff4b05711e7b962bc764e106cf4
timestamp	Current Unix epoch timestamp. This will be a 10-digit number.	1516309285
sig_field	Merchant User ID. The ID of the customer with which you are authenticating	123456789
sig	HMAC signature. Using the HMAC sha256 hash function, generate a signature. The function inputs are a string and your private OrderGroove hash key. This string should be the concatenation of the user ID and the timestamp, separated by a pipe character, e.g. 123456789|1516309285.	J623tGQuq3fJKB0C4t1+JcBAWzQo7CI/tXc8aRIVB3w=

Example:

signature = hash_hmac("sha256", "<SIG_FIELD>|<TIMESTAMP>", "<HASH_KEY>");

Response cookie authentication

Requirements

1. Must NOT require logging in to view
2. Must be HTTPS

Path to Authentication Page

Please provide the relative path of this page to OrderGroove. The path should be the same in all environments.

og_auth Cookie & Signature Creation

When the og-auth page loads, you should create a signature and set it as a "secure" cookie and not HTTP only. Please refer to the HMAC authentication instructions in the Security section below.

NOTE: Only set the og_auth cookie if the user is logged in and set it with a 2 hours expiry. If the user is not logged in, the auth page should still load but no cookie should be set. Please delete this cookie whenever the user logs out to ensure that access to OG's information has been terminated when the user's session ends.

NOTE: Do not URL encode this cookie.

The cookie contents will have the following format:

<MERCHANT_USER_ID>|<SECONDS_SINCE_EPOCH>|<SIGNATURE>

Note: The merchant_user_id should be the value you use to identify the customer in your system (e.g. TestCustomer123)

Note: Seconds since epoch should not include milliseconds. This will be a 10-digit number.

Here is an example of setting the cookie in PHP

setcookie("og_auth", "<user_id>|<seconds_since_epoch>|<signature>", time() + (60 * 60 * 2) /* 2 hour expire */, "/" /* available on all paths */ , "<merchant_domain>", true /* secure */);

Merchant must delete the og_auth cookie when the user logs out!

Static authentication

Authentication provided on OG initialization. TBD