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`}.