From ff3db96ac6b01a1db7fedb8790d1c405f501634e Mon Sep 17 00:00:00 2001
From: Zoey Lan <zoey.lan@shopify.com>
Date: Tue, 12 Sep 2023 09:06:15 -0600
Subject: [PATCH] Add numbering to steps and remove cookies

---
 docs/usage/oauth.md | 38 ++++++++++++++++++++++++--------------
 1 file changed, 24 insertions(+), 14 deletions(-)

diff --git a/docs/usage/oauth.md b/docs/usage/oauth.md
index f0905627..a39a8a92 100644
--- a/docs/usage/oauth.md
+++ b/docs/usage/oauth.md
@@ -6,7 +6,8 @@ To do this, you can follow the steps below.
 For more information on authenticating a Shopify app please see the [Types of Authentication](https://shopify.dev/docs/apps/auth#types-of-authentication) page.
 
 ## Session Persistence
-Session persistence is depreciated from the `ShopifyAPI` library gem. The responsibility of session storage typically is fulfilled by the web framework middleware. This API library's focus is on making requests and facilitate session creation.
+Session persistence is depreciated from the `ShopifyAPI` library gem. The responsibility of session storage typically is fulfilled by the web framework middleware.
+This API library's focus is on making requests and facilitate session creation.
 
 If you're not using the [ShopifyApp](https://github.com/Shopify/shopify_app) gem, you may use ShopifyAPI to perform OAuth to create sessions, but you must implement your own session storage method to persist the authorized access token.
 
@@ -17,10 +18,21 @@ If you aren't using Rails, you can look at how that [gem creates / stores sessio
 
 ## Performing OAuth
 ### 1. Add a route to start OAuth
-Add a route to your app to start the OAuth process. In this exmple the `ShopifyAuthController`'s `/login` route.
-The route for starting the OAuth process should use the library's [`ShopifyAPI::Auth::Oauth.begin_auth`](https://github.com/Shopify/shopify-api-ruby/blob/main/lib/shopify_api/auth/oauth.rb#L22) method. 
+Add a route to your app to start the OAuth process.
+
+An example is shown below in a Rails app but these steps could be applied in any framework:
+
+```ruby
+class ShopifyAuthController < ApplicationController
+  def login
+    # This method will trigger the start of the OAuth process
+  end
+end
+```
+
+### 2. Use `Auth::Oauth.begin_auth` method in the route to begin OAuth
+Use the ShopifyAPI library's [`ShopifyAPI::Auth::Oauth.begin_auth`](https://github.com/Shopify/shopify-api-ruby/blob/main/lib/shopify_api/auth/oauth.rb#L22) method to start OAuth process for your app.
 
-### `Auth::Oauth.begin_auth` method
 #### Input
 | Parameter      | Type                   | Required? | Default Value | Notes                                                                                                       |
 | -------------- | ---------------------- | :-------: | :-----------: | ----------------------------------------------------------------------------------------------------------- |
@@ -40,10 +52,11 @@ The route for starting the OAuth process should use the library's [`ShopifyAPI::
 | Key | Type | Notes |
 |-----|------|-------|
 |`auth_route`|`String`|URI that will be used for redirecting the user to the Shopify Authentication screen|
-|`cookie`|`ShopifyAPI::Auth::Oauth::SessionCookie`|A session cookie to store on the user's browser.|
+|`cookie`|`ShopifyAPI::Auth::Oauth::SessionCookie`|A session cookie to store on the user's browser. |
 
 #### Using the result
-Your app should take the returned values from the `begin_auth` method and redirect the user to url defined by `auth_route` and set the cookie in the user's browser. We strongly recommend that you use secure, httpOnly cookies for this to help prevent session hijacking.
+Your app should take the returned values from the `begin_auth` method and redirect the user to url defined by `auth_route`.
+Setting the cookie in the user's browser is no longer necessary, see [ZOEY CHANGE THIS]() to see how to handle OAuth callback. 
 
 An example is shown below in a Rails app but these steps could be applied in any framework:
 
@@ -52,22 +65,19 @@ class ShopifyAuthController < ApplicationController
   def login
     shop = request.headers["Shop"]
 
+    # Builds the auth URL route to redirect the user to
     auth_response = ShopifyAPI::Auth::Oauth.begin_auth(shop: domain, redirect_path: "/auth/callback")
 
-    cookies[auth_response[:cookie].name] = {
-      expires: auth_response[:cookie].expires,
-      secure: true,
-      http_only: true,
-      value: auth_response[:cookie].value
-    }
-
+    # Redirect the user to "auth_response[:auth_route]" to start OAuth
+    # This will lead the user to the Shopify Authorization page
     head 307
     response.set_header("Location", auth_response[:auth_route])
   end
 end
 ```
 
-### 2. Add your OAuth callback route
+
+### 3. Add your OAuth callback route
 
 After the app is authenticated with Shopify, the Shopify platform will send a request back to your app using this route (which you provided as a parameter to `begin_auth`, above). Your app will now use the provided `validate_auth_callback` method to finalize the OAuth process. This method returns a hash containing the new session and a cookie to be set in the browser in form of {`session`: `ShopifyAPI::Auth::Session`, `cookie`: `ShopifyAPI::Auth::Oauth::SessionCookie`}.