[go: nahoru, domu]
Skip to content

Latest commit

 

History

History
106 lines (88 loc) · 6.13 KB

cors.md

File metadata and controls

106 lines (88 loc) · 6.13 KB
Raw
title
cors

Description

cors plugin can help you enable CORS easily.

Attributes

Name Type Requirement Default Valid Description
allow_origins string optional "*" Which Origins is allowed to enable CORS, format as: scheme://host:port, for example: https://somehost.com:8081. Multiple origin use , to split. When allow_credential is false, you can use * to indicate allow any origin. you also can allow all any origins forcefully using ** even already enable allow_credential, but it will bring some security risks.
allow_methods string optional "*" Which Method is allowed to enable CORS, such as: GET, POST etc. Multiple method use , to split. When allow_credential is false, you can use * to indicate allow all any method. You also can allow any method forcefully using ** even already enable allow_credential, but it will bring some security risks.
allow_headers string optional "*" Which headers are allowed to set in request when access cross-origin resource. Multiple value use , to split. When allow_credential is false, you can use * to indicate allow all request headers. You also can allow any header forcefully using ** even already enable allow_credential, but it will bring some security risks.
expose_headers string optional "*" Which headers are allowed to set in response when access cross-origin resource. Multiple value use , to split. When allow_credential is false, you can use * to indicate allow any header. You also can allow any header forcefully using ** even already enable allow_credential, but it will bring some security risks.
max_age integer optional 5 Maximum number of seconds the results can be cached. Within this time range, the browser will reuse the last check result. -1 means no cache. Please note that the maximum value is depended on browser, please refer to MDN for details.
allow_credential boolean optional false Enable request include credential (such as Cookie etc.). According to CORS specification, if you set this option to true, you can not use '*' for other options.
allow_origins_by_regex array optional nil Use regex expressions to match which origin is allowed to enable CORS, for example, [".*.test.com"] can use to match all subdomain of test.com
allow_origins_by_metadata array optional nil Match which origin is allowed to enable CORS by referencing allow_origins set in plugin metadata. For example, if "allow_origins": {"EXAMPLE": "https://example.com"} is set in metadata, then ["EXAMPLE"] can be used to match the origin https://example.com

Tips

Please note that allow_credential is a very sensitive option, so choose to enable it carefully. After set it be true, the default * of other parameters will be invalid, you must specify their values explicitly. When using **, you must fully understand that it introduces some security risks, such as CSRF, so make sure that this security level meets your expectations before using it。

Metadata

Name Type Requirement Default Valid Description
allow_origins object optional A map from origin reference to allowed origins; its key is the reference used by allow_origins_by_metadata and its value is a string equivalent to allow_origins in plugin attributes

How To Enable

Create a Route or Service object and configure cors plugin.

curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "uri": "/hello",
    "plugins": {
        "cors": {}
    },
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "127.0.0.1:8080": 1
        }
    }
}'

Test Plugin

curl to server, you will find the headers about CORS is be returned, which means plugin is working fine.

curl http://127.0.0.1:9080/hello -v
...
< Server: APISIX web server
< Access-Control-Allow-Origin: *
< Access-Control-Allow-Methods: *
< Access-Control-Allow-Headers: *
< Access-Control-Expose-Headers: *
< Access-Control-Max-Age: 5
...

Disable Plugin

When you want to disable the cors plugin, it is very simple, you can delete the corresponding json configuration in the plugin configuration, no need to restart the service, it will take effect immediately:

$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "uri": "/hello",
    "plugins": {},
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "127.0.0.1:8080": 1
        }
    }
}'

The cors plugin has been disabled now. It works for other plugins.