Default value for Access-Control-Allow-Methods

Learn default value for access-control-allow-methods with practical examples, diagrams, and best practices. Covers http, header, cross-domain development techniques with visual explanations.

Understanding the Default Value of Access-Control-Allow-Methods

Illustration of HTTP methods (GET, POST, PUT, DELETE) flowing between a client and server, with a lock icon representing CORS security.

Explore the behavior of the Access-Control-Allow-Methods header in CORS, its default values, and how to configure it for secure cross-origin requests.

When dealing with Cross-Origin Resource Sharing (CORS), the Access-Control-Allow-Methods HTTP response header plays a crucial role in specifying which HTTP methods are permitted when accessing a resource from a different origin. Understanding its default behavior is key to correctly configuring your server and troubleshooting CORS issues. This article delves into what happens when this header is omitted or explicitly set, and how browsers interpret these scenarios.

The Role of Access-Control-Allow-Methods in CORS

The Access-Control-Allow-Methods header is part of the server's response to a CORS preflight request (an OPTIONS request). The browser sends a preflight request for 'complex' HTTP requests, which include requests using methods other than GET, HEAD, or POST, or requests with custom headers. The server's response to this preflight request dictates whether the actual request is allowed to proceed.

If the server's response to the preflight request does not include the Access-Control-Allow-Methods header, or if the requested method is not listed in it, the browser will block the actual request, resulting in a CORS error. This mechanism is a fundamental security feature, preventing malicious cross-origin requests.

sequenceDiagram
    participant Client
    participant Server

    Client->>Server: OPTIONS /resource (Preflight Request)
    Note over Client,Server: Requesting access for POST method
    Server-->>Client: HTTP/1.1 204 No Content
    Server-->>Client: Access-Control-Allow-Origin: *
    Server-->>Client: Access-Control-Allow-Methods: GET, POST, OPTIONS
    alt Method Allowed
        Client->>Server: POST /resource (Actual Request)
        Server-->>Client: HTTP/1.1 200 OK
    else Method Not Allowed or Header Missing
        Client->>Client: CORS Error: Method not allowed
        Note over Client: Actual request is blocked by browser
    end

CORS Preflight Request Flow with Access-Control-Allow-Methods

Default Behavior When the Header is Omitted

Contrary to what some might expect, there is no universal 'default' value for Access-Control-Allow-Methods if the header is entirely omitted from the server's preflight response. If the server does not send this header, the browser will interpret this as a rejection of the preflight request for any method that requires preflighting.

Specifically, if a client attempts to make a PUT or DELETE request (which always trigger a preflight), and the server's OPTIONS response does not include Access-Control-Allow-Methods listing PUT or DELETE respectively, the browser will block the subsequent actual request. For 'simple' requests (GET, HEAD, POST without custom headers), a preflight is not sent, and thus Access-Control-Allow-Methods is not checked. However, even for simple POST requests, if the server doesn't explicitly allow it via Access-Control-Allow-Methods in a preflight (if one were triggered for other reasons), it would be blocked.

⚠️

Omitting the Access-Control-Allow-Methods header in a preflight response effectively means no complex methods are allowed from a cross-origin context. It does not default to allowing common methods like GET or POST for preflighted requests.

Configuring Access-Control-Allow-Methods

To allow specific HTTP methods for cross-origin requests, you must explicitly include them in the Access-Control-Allow-Methods header in your server's preflight response. It's best practice to only allow the methods truly needed by your application to minimize potential attack vectors.

Here are examples of how this header might be configured in different server environments.

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://example.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization

Example of a server response allowing multiple HTTP methods.

💡

Always include OPTIONS in your Access-Control-Allow-Methods list if you expect preflight requests. While browsers typically handle OPTIONS implicitly for preflights, explicitly allowing it can prevent issues with some proxies or older browser versions.

Impact on Simple vs. Complex Requests

It's crucial to distinguish between simple and complex requests. Simple requests (e.g., GET, HEAD, POST with specific Content-Type headers like application/x-www-form-urlencoded, multipart/form-data, or text/plain, and no custom headers) do not trigger a preflight OPTIONS request. For these, the Access-Control-Allow-Methods header is not checked by the browser. The server simply responds to the actual request, and the Access-Control-Allow-Origin header is the primary determinant of whether the response is accessible to the client.

Complex requests, on the other hand, always trigger a preflight. This is where Access-Control-Allow-Methods becomes critical. If the method used in the actual request (e.g., PUT, DELETE, or POST with application/json or custom headers) is not explicitly listed in the preflight response's Access-Control-Allow-Methods header, the browser will block the request.

fetch('https://api.example.com/data', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'X-Custom-Header': 'value'
  },
  body: JSON.stringify({ key: 'value' })
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('CORS error:', error));

A JavaScript fetch request that will trigger a CORS preflight due to PUT method and custom header.