diff --git a/docs/getting_started.md b/docs/getting_started.md index b8b007cc4..bf4883ebe 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -37,10 +37,27 @@ ShopifyAPI::Context.setup( Next, unless you are making a private app, you need to go through OAuth as described [here](https://shopify.dev/docs/apps/auth/oauth) to create sessions for shops using your app. The Shopify API gem tries to make this easy by providing functions to begin and complete the OAuth process. See the [Oauth doc](usage/oauth.md) for instructions on how to use these. -### Register Webhooks and a Webhook Handler +### Sessions -If you intend to use webhooks in your application follow the steps in the [Webhooks doc](usage/webhooks.md) for instructions on registering and handling webhooks. +Sessions are required to make requests with the REST or GraphQL clients. This Library provides helpers for creating sessions via OAuth. Helpers are provided to retrieve session ID from a HTTP request from an embedded Shopify app or cookies from non-embedded apps. + +Session persistence is handled by the [ShopifyApp](https://github.com/Shopify/shopify_app) gem and is recommended for use in the Rails context. See that gem for documentation on how to use it. + +#### Cookie +Cookie based authentication is not supported for embedded apps due to browsers dropping support for third party cookies due to security concerns. Non-embedded apps are able to use cookies for session storage/retrieval. + +For *non-embedded* apps, you can pass the cookies into `ShopifyAPI::Utils::SessionUtils.current_session_id(nil, cookies, true)` for online (user) sessions or `ShopifyAPI::Utils::SessionUtils.current_session_id(nil, cookies, false)` for offline (store) sessions. + +#### Getting Session ID From Embedded Requests +For *embedded* apps, you can pass the auth header into `ShopifyAPI::Utils::SessionUtils.current_session_id(auth_header, nil, true)` for online (user) sessions or `ShopifyAPI::Utils::SessionUtils.current_session_id(auth_header, nil, false)` for offline (store) sessions. This function needs an `auth_header` which is the `HTTP_AUTHORIZATION` header. -### Start Making Authenticated Shopify Requests +If your app uses client side rendering instead of server side rendering, you will need to use App Bridge's [authenticatedFetch](https://shopify.dev/docs/apps/auth/oauth/session-tokens/getting-started) to make authenticated API requests from the client. + +#### Start Making Authenticated Shopify Requests You can now start making authenticated Shopify API calls using the Admin [REST](usage/rest.md) or [GraphQL](usage/graphql.md) Clients or the [Storefront GraphQL Client](usage/graphql_storefront.md). + +### Register Webhooks and a Webhook Handler + +If you intend to use webhooks in your application follow the steps in the [Webhooks doc](usage/webhooks.md) for instructions on registering and handling webhooks. + diff --git a/docs/usage/graphql.md b/docs/usage/graphql.md index 4493f5f5c..6e00bfce6 100644 --- a/docs/usage/graphql.md +++ b/docs/usage/graphql.md @@ -104,6 +104,7 @@ If you would like to give your front end the ability to make authenticated graph def proxy begin response = ShopifyAPI::Utils::GraphqlProxy.proxy_query( + session: session, headers: request.headers.to_h, body: request.raw_post, cookies: request.cookies.to_h diff --git a/docs/usage/oauth.md b/docs/usage/oauth.md index 8ea8ec6ce..1147dae05 100644 --- a/docs/usage/oauth.md +++ b/docs/usage/oauth.md @@ -70,35 +70,3 @@ def callback end end ``` -## Fetching sessions - -You can use the OAuth methods to create both offline and online sessions. Once the process is completed, the session will be stored as per your `Context.session_storage`, and can be retrieved with `SessionUtils` class methods. - -- To load current session, you can use the following method: - -```ruby -ShopifyAPI::Utils::SessionUtils.load_current_session(auth_header: , cookies: , is_online: ) -``` - -Accepted arguments: -| Parameter | Type | Notes | -| ----------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `auth_header` | `String` | JWT token will be extracted from `auth_header` to load session for embedded apps. If JWT token is not provided this methods will try with `cookies`. Only required if trying to load, an embedded session. | -| `cookies` | `Hash(String, String)` | The cookies from the HTTP request. A session cookie named `shopify_app_session` is used to load session for non-embedded apps. Can be omitted if loading and embedded session without falling back on cookies | -| `is_online` | `Boolean` | Whether to load online or offline sessions. Defaults to `false` | - -This method will return a `ShopifyAPI::Auth::Session` if a session exists. Either a proper token or a proper cookie must be present. - -- To load offline session, you can use the following method: - -```ruby -ShopifyAPI::Utils::SessionUtils.load_offline_session(shop) -``` - -Accepted arguments: -| Parameter | Type | Notes | -| ------------------- | --------- | --------------------------------------------- | -| `shop` | `String` | The shop url to find the offline session for. | -| `include_expired` | `Boolean` | Include expired sessions or not. | - -This method will return a `ShopifyAPI::Auth::Session` if a session exists and `nil` otherwise. This method **does not** perform any validation on the shop domain, so it **must not** rely on user input for the domain. This method is typically meant to be used in background tasks like webhooks, where the data is expected to have been validated when the task was enqueued. diff --git a/docs/usage/session_storage.md b/docs/usage/session_storage.md deleted file mode 100644 index a01a6e66e..000000000 --- a/docs/usage/session_storage.md +++ /dev/null @@ -1,46 +0,0 @@ - -# Create a Session Storage Implementation - -The implementation of session storage that you pass in `ShopifyAPI::Context.setup` is what the Shopify gem will use to store and load sessions. [Shopify::Auth::FileSessionStorage](../../lib/shopify_api/auth/file_session_storage.rb) can be used for testing purposes and as an example of how to make an implementation in your app. This is not recommended for production, we recommend you implement a solution that will store and load serialized sessions from a more ideal store such as a database like MySQL or MongoDB. - -## Create a New Session Storage Class - -You can create a session storage class that includes `ShopifyAPI::Auth::SessionStorage` and override the methods as shown in the table and example below: - -| Method Name | Input Type | Return Type | -| ---------------------- | --------------------------------- | ------------------------------ | -| `store_session` | `ShopifyAPI::Auth::Session` | `Boolean` (true if successful) | -| `load_session` | `String` (session id) | `ShopifyAPI::Auth::Session` | -| `delete_session` | `String` (session id) | `Boolean` (true if successful) | - - -```ruby -class CustomSessionStorage - include ShopifyAPI::Auth::SessionStorage - - def initialize - # Initialize as needed - end - - def store_session(session) - # Implement a store function - some_store_function(id: session.id, session_data: session.serialize) - end - - def load_session(id) - # Implement a fetch function - session_data = some_fetch_function(id) - ShopifyAPI::Auth::Session.deserialize(session_data) - end - - def delete_session(id) - # Implement a delete function - some_delete_function(id) - true - end -end -``` - -**Note:** We recommend utilizing the Session `serialize` and `deserialize` functions to make storing and loading sessions easier. - -Once this is complete you can pass an instance of this session storage class as `session_storage` in `ShopifyAPI::Context.setup`