CORSPlug

When using Phoenix, placing CORSPlug in a standard pipeline may not work because pipelines are only invoked for matched routes.

There are two recommended integration patterns:

1. Endpoint Level (Recommended): Add the plug directly to your Endpoint module so it intercepts all requests before they reach the router.
2. Router/Pipeline Level: Add CORSPlug to a specific pipeline and ensure you define options routes for your resources to handle preflight requests.

Note: Options passed directly to the plug override application configuration, which in turn overrides default options.

# Pattern 1: Endpoint Level
defmodule YourApp.Endpoint do
  use Phoenix.Endpoint, otp_app: :your_app

  # ...
  plug CORSPlug

  plug YourApp.Router
end

# Pattern 2: Router Pipeline Level
pipeline :api do
  plug CORSPlug
  # ...
end

scope "/api", PhoenixApp do
  pipe_through :api

  resources "/articles", ArticleController
  options   "/articles", ArticleController, :options
  options   "/articles/:id", ArticleController, :options
end

The origin option determines which request origins are allowed. It supports several types of values:

• String: An exact match for the origin (e.g., "https://example.com").
• List of Strings: A whitelist of allowed origins.
• List containing "*": Allows all origins.
• Regex: A regular expression to match the request origin.
• :self: A special atom that whitelists the internal request origin (defaults to "*" if no origin is present).
• Function: A function used to dynamically determine the allowed origin. Supported arities are:
  • 0: The function takes no arguments and returns the origin string.
  • 1: The function takes the %Plug.Conn{} as an argument and returns the origin string.
• Single non-list value: If you provide a single string or regex instead of a list, it will be automatically wrapped into a list.

# Using a Regex
origin: ~r/https://.*\.example\.com$/

# Using a List
origin: ["https://example.com", "https://app.example.com"]

# Using a Function (Arity 1)
origin: fn conn -> if conn.method == "GET", do: "https://allowed.com", else: nil end

# Using :self to whitelist internal requests
origin: [:self]

You can define which origins are allowed to access your resources using several methods. The origin configuration accepts strings, regular expressions, or a mix of both.

Methods for defining origins:

• List of strings or regexes: Pass a list directly to the plug.
• Single Regex: Pass a single regex to the plug.
• Application Configuration: Set the origin key in your config.exs.
• Dynamic Functions: Pass a function (function/0 or function/1) that returns a list of allowed origins as strings.
  • Caveat: You cannot use anonymous functions because they cannot be quoted. Use a named function from a module instead.
  • function/0 takes no arguments.
  • function/1 receives the conn as an argument, allowing you to perform logic based on the connection before returning the allowed origins.

# Using a list
plug CORSPlug, origin: ["http://example1.com", "http://example2.com", ~r/https?.*example\d?\.com$/]

# Using a regex
plug CORSPlug, origin: ~r/https?.*example\d?\.com$/

# Using config.exs
config :cors_plug,
  origin: ["http://example.com"],
  max_age: 86400,
  methods: ["GET", "POST"]

# Using a function/0
plug CORSPlug, origin: &MyModule.my_fun/0

defmodule MyModule do
  def my_fun do
    ["http://example.com"]
  end
end

# Using a function/1 (accessing conn)
plug CORSPlug, origin: &MyModule.my_fun/1

defmodule MyModule do
  def my_fun(conn) do
    # Do something with conn
    ["http://example.com"]
  end
end

Headers returned by CorsPlug

On preflight (OPTIONS) requests:

• Access-Control-Allow-Origin
• Access-Control-Allow-Credentials
• Access-Control-Max-Age
• Access-Control-Allow-Headers
• Access-Control-Allow-Methods

On GET, POST, etc. requests:

• Access-Control-Allow-Origin
• Access-Control-Expose-Headers
• Access-Control-Allow-Credentials

Configuration Keys

Note: If no configured origin matches the request, the string null is returned for Access-Control-Allow-Origin as per W3C recommendations.