How to Shopify OAuth

How to - Shopify OAuth

In this guide you will learn how to use the Shopify.OAuth package in your .NET application to perform authentication / authorization for your Shopify Application against a Shopify store.

IShopifyOAuth / ShopifyOAuth is the main class that performs the workflow.

---

Above class can be instantiated in two ways:

Option 1: Initialize IShopifyOAuth by providing Shopify Application API Key and Shared secret Key in constructor. In this option you exclusively provide the API key and shared secret when instantiating ShopifyOAuth class.

This two parameters can be provided by wrapping it up in OAuthConfiguration object, its a simple POCO class with two properties ApiKey and SecretKey. The ShopifyOAuth class takes one parameter in constructor of type OAuthConfiguration.

Example:

OAuthConfiguration configuration = new OAuthConfiguration
{
    ApiKey = "your-app-api-key",
    SecretKey = "your-app-secret-key"
};

IShopifyOAuth myShopifyOAuth = new ShopifyOAuth(configuration);

Option 2: Initialize IShopifyOAuth with empty / default constructor. In this case, library will try to fetch ApiKey and SecretKey from the web.config / app.config file's appSettings.

To use this option you need to add two appSettings key / value to your application's configuration file

• Key Name: shopify-dotnet-api-key - Your Shopify application's API key
• Key Name: shopify-dotnet-secret-key - Your Shopify application's shared secret key

Example - web.config:

<appSettings>
  <add key="shopify-dotnet-api-key" value="23fsdf2323lk2l91a950508985" />
  <add key="shopify-dotnet-secret-key" value="da9d8sdfsd342423f8db91985" />
</appSettings>

While initializing IShopifyOAuth if following key and its value not found will result in ArgumentNullException / ArgumentException.

---

Shopify OAuth 2.0 authorization is performed in two steps:

Step 1: Asking for permission (Redirection / Accept permission)

In this step your application needs to redirect user to Shopify's Authorization server. This redirection needs some information in the request you make - shop's name and what permission your application needs to access the shop.

Generate a redirection URL using IShopifyOAuth.GetOAuthUrl() method. This method take in two parameters.

• Shop's name - The name of the shop (without '.myshopify.com`) for which you are going to ask permission for.
• Permission scope list - This is implemented using a enum - OAuthScope. You can specify multiple permissions using the pipe | separator.

E.g. - If my application needs write_orders and write_shipping permission to the shop then, it can be provided as follows:

OAuthScope.write_orders | OAuthScope.write_shipping

Example:

var redirectionUrl = myShopifyOAuth.GetOAuthUrl("fancyshopname",
                     OAuthScope.write_orders | OAuthScope.write_shipping | OAuthScope.write_products);
Redirect(redirectionUrl); //// Example for ASP.NET MVC redirection

Step 2: Confirming installation (Fetching shop access code)

On redirection during step 1 the shop user will be asked for permission allowing the application to access parts of their shop. When user accepts application permission by clicking on 'Install ', Shopify Authorization Server will redirect this request to the "Callback URL" you specified in the settings page of your application.

In this incoming request at your "Callback URL" you will receive following parameters in query string with value to use:

• shop - Shop's name.
• code - Intermediate authorization code.
• hmac - HMAC - SHA256 hash value.
• timestamp - Timestamp value.

You need to pass above four parameter's value into IShopifyOAuth.AuthorizeClient() method. This method has two variants:

• Accepts instance of NameValueCollection. This can be a collection of query string provided in the request.
• Accepts all four parameters as individual values.

Example:

var myOAuthState = myShopifyOAuth.AuthorizeClient(Request.QueryString);

or

var myOAuthState = myShopifyOAuth.AuthorizeClient(
                      "fancyshopname.myshopify.com",
                      "3c171400a41f8db91a9505",
                      "da9d83c171400a41f8db91a950508985",
                      "1409617544");

In the process of AuthorizeClient, the library will internally verify the integrity of the incoming request to ensure that it came from Shopify.

AuthorizeClient method returns instance of OAuthState which contains four accessible properties:

• ShopName - The shop name for which this authorization was performed.
• AccessToken - Access token, this is required (and should be safely stored) to access Shop resources using Shopify API.
• IsSuccess - Indicates whether application installation in the shop was successful or not.
• Error - If IsSuccess is false then this property will contain appropriate reason for the same.

---

Three types of Error details you may want to know that can be returned if application installation failed:

• Required parameters in query string missing - If library was not able to find the values for API and Shared Secret key from configuration file or in constructor.
• HMAC signature validation failed - If HMAC signature validation failed, this can be because the request to callback URL was not from Shopify server or some data was tampered or the specification changed.
• {Exception Type}: {Exception message} - This would be any internal or HTTP request / response exception. ExceptionType will be known .NET exception and ExceptionMessage will be value for exception's message property.