• How To Guides
• OAuth Connector

Miva OAuth Connector

1. Overview
2. Installation & Setup
3. Available Items
4. Available Functions
5. Facebook Example

Overview

The Miva OAuth Connector module enables your customers to log into your store using their credentials from third party websites and services such as Facebook, Twitter, Google or Amazon. This module implements OAuth 1.0, 1.0a, and 2.0 protocols.

Installation & Setup

Installation

1. The Miva OAuth Connector module can be downloaded from the Miva App Store here.
2. Go to Home > Modules and click the Add Module button [ + ] to upload the module.
3. Click the UPLOAD button and select oauth.mvc.
4. Click the [ + Add ] button.
5. To make it live, the module needs to be installed on the store. Under Utility Settings > Add/Remove Modules, click [+] Install on the OAuth Connector module.

Setup

After installing the module, there is a new OAuth Providers tab under Utility Settings. Before you can add a provider (i.e. Facebook, Twitter, Amazon, Dropbox, Google, etc.), you must set it up using the client's account. Refer to the documentation from the appropriate provider. The example below shows how to use OAuth Connector with Facebook.

Available Items

After installing the module, three new items are available in the User Interface.

These items must be assigned to any page on which you want to access the data.

• oauth – Must be assigned to any page accessing OAuth tokens.
• oauth_providers – Used to show additional information about which providers are configured and whether the currently logged in customer is associated with a provider (optional).
• oauth_tokens – Used to show any active tokens and which providers they are associated with (optional).

Available Functions

OAuthCustomer_Create

This function creates a new customer and links it to the associated OAuth provider.

Input Parameters

Customer Input Parameters

Error Codes

Response

OAuthCustomer_Create_Association

This function links a logged-in customer to the associated OAuth provider.

Input Parameters

Error Codes

Response

OAuth_Request

This function creates a request to a specified URL using the associated OAuth provider.

Input Parameters

Error Codes

Response

OAuth_Login

This function logs into a Miva Merchant account via an OAuth provider.

Input Parameters

Error Codes

Response

Facebook Example

Needed prior to beginning:

• Client's Facebook Login – This is used to create the Facebook App.
• The oauth.mvc module must be live in Miva admin. Follow the steps in INSTALLATION if you haven't already installed the module.

Step 1 – Create a Facebook app using the client's Facebook account. You will need the App ID and Secret Code.

The Display Name should be "[Store Name] Login Application" – This is displayed to the customer.

Make sure that the Site URL is set to the secure version of the client's URL.

Upload a logo for the App. This will display on the authorization screen for the customer. To do this, click on App Details. You need to create an image exactly 75px by 75px from the logo. Upload it as the 75×75 primary icon.

Step 2 – Create a blank page in Miva.

1. Go to Home > User Interface > Pages and click on the Add Page button [ + ].
2. In the Code field, enter "facebook-redirect".
3. In the Name field, enter "Facebook Redirect".
4. Leave Template blank and click [ + Add ].

Step 3 – Create two new items and assign them to facebook-redirect.

1. Go to Home > User Interface > Items and click on the Add Item button [ + ].
2. In the Code field, enter "facebook_CSS".
3. In the Module field, enter "cmp-mv-content" or use the LOOK UP button to navigate to the "Content" module and select it.
4. Click [ + Add ].

5. Repeat steps 1-4 to enter an item with the Code "facebook_JS".
6. Go to Home > User Interface > Pages > Edit Page: Facebook Redirect > Items
7. Search for the two new "facebook" items and use the slider buttons to assign them to the Facebook Redirect page.

Step 4 – Assign "oauth" item to facebook-redirect.

When the module is installed, it creates an item "oauth".

1. Go to Home > User Interface > Items > Edit Item: oauth > Pages.
2. Search for the Facebook Redirect page and assign "oauth" to it via the slider button.

3. Go to Home > User Interface > Items > Edit Item: store > Pages.
4. Search for the Facebook Redirect page and assign "store" to it via the slider button.

Step 5 – Add the provider.

To add a new provider, perform the following steps.

1. Go to Home > Utility Settings > OAuth Providers.
2. Click the New Provider button [ + ]. The Add Provider dialog appears.

3. Fill in the fields as shown below.
4. When you have finished filling in the fields, click Add.

Code: facebook

Name: Facebook

Client ID: Enter the Facebook AP ID here

Client Secret: Enter the Facebook AP Secret here

Authorize URL: https://www.facebook.com/dialog/oauth/

Authorize Scope: email

Access Token URL: https://graph.facebook.com/oauth/access_token [POST]

Version: 2.0

Redirect Page: facebook-redirect

Enabled check

Additional Parameters:

• Attribute: display
• Value: popup
• Type: Authorize

Step 6 – jQuery and global popup function

Add jQuery (if needed) and global popup function into the HEAD tag. If they already have the jQuery library only add the popup function below.

Step 7 – Upload Facebook button

Facebook Button and graphic files should be uploaded to the /images folder inside the mm5 folder.

Step 8 – Add code to facebook pages

Copy and paste the following code into the facebook-redirect main page template.

Copy and paste the following code into the facebook_CSS content tab.

Copy and paste the following code into the facebook_JS content tab.

Step 9 – Add Facebook buttons to LOGN and ORDL below the create account button.

Step 10 – On the facebook-redirect page in the facebook_JS tab, update the return_url to reflect the correct screen parameter.

Note: Only the second return_url value should ever need to be changed. This is the page the customer will be taken to when they login from LOGN. Some stores will be ACLN, others will be ACED others will be a custom page or the storefront. This should match what normally happens on their site when you login from LOGN.

Step 11 – Pre PR8 Update 7 changes

If the site is not on PR8 Update 7 or above, you need to adjust the JavaScript inside the miva_login function. Starts on line 142.

You should also change the HTML on the main facebook-redirect template to say "Username" instead of "Email" on line 41.

Step 12 – Setup Facebook Login App

In the Facebook Portal, Click the + next to Product to Add Product. Select Facebook Login from list. Select Web. Enter the store URL. Click Save and Continue. Keep clicking Next and ignore all the code in Step 5.

After that, under Products>>Facebook Login, Click Settings. Where it asks for a Valid OAuth redirect URIs, you need to add your store’s OAuth redirect URL. It should look something like this:

https://www .{STORENAME}.com/mm5/merchant.mvc?Store_Code={STORECODE}&Screen=OAUTH&Action=OAUTH_CALLBACK&OAuth_Provider_Code=facebook

Note: If you get this error:
“Can’t Load URL: The domain of this URL isn’t included in the app’s domains. To be able to load this URL, add all domains and subdomains of your app to the App Domains field in your app settings.”
Right click and inspect the message. There's an input field underneath the error message for the desired URL.
If your URL contains Session, remove it and the value before adding it in the Facebook Portal.

Step 13 – Check Miva Domain Settings

In the Miva admin, go to Domain Settings and make sure Include Session Parameters is set to "Never". Make sure your store is forcing HTTPS.

Step 14 – Test all three use cases

1. New Customer, login via Facebook and create a new account.
2. New Customer, login via Facebook, create account but specify password.
3. Returning customer with existing account. Link account to Facebook.