PlugShopifyEmbeddedJWTAuth (plug_shopify_jwt v0.1.1)

This plug validates Shopify JWT - also known as session token authentication. Session tokens/JWT are a replacement for cookie based authentication in embedded apps.

PlugShopifyJwt is architected to support Session tokens whilst allowing you to verify with URL parameters (validation of URL parameters is not included in this plug) should you decide.

### Usage Grab you app secret, and crack open your router.ex file, insert plug PlugShopifyEmbeddedJWTAuth, [secret: "your-secret"]. A basic setup looks something similar to this:

    pipeline :embedded do
      plug PlugShopifyEmbeddedJWTAuth, [secret: "224e5146-4f1e-4a1d-a64a-2732df659542"]
    end

    scope "/api", HelloPhoenixWeb do
      pipe_through :embedded

      get "/show", PageController, :show
    end

### Installation The package can be installed by adding plug_shopify_jwt to your list of dependencies in mix.exs:

  def deps do
    [
      {:plug_shopify_jwt, "~> 0.1.0"}
    ]
  end

Link to this section Summary

Types

Plug configuration

  • algorithm (Default: "HS256") - "HS256", "HS384", "HS512", "RS256", "RS384", "RS512", "ES256", "ES384", "ES512", "PS256", "PS384", "PS512", "Ed25519", "Ed25519ph", "Ed448".
  • secret (Required the plug will throw an error if you do not set this) - from your Shopify Partner Dashboard.
  • halt_on_error (Default: true) - either true or false
  • signer (App only) - this is set by the Plug, you do not need to set this item.

Functions

Pass in a Plug.Conn and Config and it will take the auth header, authenticate the request, and the result will be one of the following

Protects a route with JWT. Plug will automatically call call/2 for each connection.

Link to this section Types

Specs

config() :: [
  algorithm: String.t(),
  secret: String.t() | nil,
  signer: Joken.Signer.t() | nil,
  halt_on_error: true | false
]

Plug configuration

  • algorithm (Default: "HS256") - "HS256", "HS384", "HS512", "RS256", "RS384", "RS512", "ES256", "ES384", "ES512", "PS256", "PS384", "PS512", "Ed25519", "Ed25519ph", "Ed448".
  • secret (Required the plug will throw an error if you do not set this) - from your Shopify Partner Dashboard.
  • halt_on_error (Default: true) - either true or false
  • signer (App only) - this is set by the Plug, you do not need to set this item.

Link to this section Functions

Link to this function

call(conn, opts)

Specs

call(Plug.Conn.t(), config()) :: Plug.Conn.t()

Pass in a Plug.Conn and Config and it will take the auth header, authenticate the request, and the result will be one of the following:

  1. Return a 401: halt_on_error must be set to true, and the authentication fails.
  2. Allow the connection to continue: When authentication passes we will set conn.private[:shopify_jwt_claims] to the full decoded JWT, and conn.private[:current_shop_name] - will be the myshopify.com domain for the current store, e.g. example.shopify.com
  3. Fail, but allow the connection to continue: When halt_on_error is set to false instead of halting the connection the plug will set conn.private[:ps_jwt_success] to false assuming you will be doing error handling in another place.

Specs

init(config()) :: config()

Protects a route with JWT. Plug will automatically call call/2 for each connection.

Config

See the documentation for the config type for details on the available options.

Usage:

    pipeline :embedded do
      plug PlugShopifyEmbeddedJWTAuth, [secret: "224e5146-4f1e-4a1d-a64a-2732df659542"]
    end

    scope "/api", HelloPhoenixWeb do
      pipe_through :embedded

      get "/show", PageController, :show
    end

Specs

respond(
  {:ok, nil | maybe_improper_list() | map(), Plug.Conn.t()}
  | {:error, any(), any(), nil | keyword() | map()}
) :: Plug.Conn.t()