CORS

If your server supposes to handle cross-origin requests, you need to install and configure the CORS Ktor plugin. This plugin allows you to configure allowed hosts, HTTP methods, headers set by the client, and so on.

Install CORS

To install the CORS plugin, pass it to the install function in the application initialization code. Depending on the way used to create a server, this can be the embeddedServer function call ...

            import io.ktor.features.*
            // ...
            fun main() {
                embeddedServer(Netty, port = 8080) {
                    install(CORS)
                    // ...
                }.start(wait = true)
            }
        

... or a specified module.

            import io.ktor.features.*
            // ...
            fun Application.module() {
                install(CORS)
                // ...
            }
        

Configure CORS

CORS-specific configuration settings are exposed by the CORS.Configuration class. Let's see how to configure these settings.

Overview

Suppose you have a server listening on the 8080 port, with the /customer route responding with JSON data. A code snippet below shows a sample request made using the Fetch API from the client working on another port to make this request cross-origin.

To allow such a request on the backend side, you need to configure the CORS plugin as follows.

    install(CORS) {
        host("0.0.0.0:5000")
        header(HttpHeaders.ContentType)
    }

You can find the full example here: cors-backend.

Hosts

To specify the allowed host that can make cross-origin requests, use the host function. Apart from the hostname, you can specify a port number, a list of subdomains, or the supported HTTP schemes.

install(CORS) {
     host("client-host")
     host("client-host:5000")
     host("client-host", subDomains = listOf("en", "de", "es"))
     host("client-host", schemes = listOf("http", "https"))
}

To allows cross-origin requests from any host, use the anyHost function.

install(CORS) {
    anyHost()
}

HTTP methods

By default, the CORS plugin allows the GET, POST and HEAD HTTP methods. To add additional methods, use the method function.

install(CORS) {
    method(HttpMethod.Options)
    method(HttpMethod.Put)
    method(HttpMethod.Patch)
    method(HttpMethod.Delete)
}

HTTP headers

The CORS plugin allows the following client headers by default:

Accept
Accept-Language
Content-Language

To allow additional headers, use the header function.

install(CORS) {
    header(HttpHeaders.ContentType)
    header(HttpHeaders.Authorization)
}

To allow custom headers, use the allowHeaders or allowHeadersPrefixed functions. For instance, the code snippet below shows how to allow headers prefixed with custom-.

install(CORS) {
    allowHeadersPrefixed("custom-")
}

Credentials

By default, browsers don't send credential information (such as cookies or authentication information) with cross-origin requests. To allow passing this information, set the Access-Control-Allow-Credentials response header to true using the allowCredentials property.

    install(CORS) {
        allowCredentials = true
    }

Miscellaneous

The CORS plugin also allows you to specify other CORS-related settings. For example, you can use maxAgeInSeconds to specify how long the response to the preflight request can be cached without sending another preflight request.

    install(CORS) {
        maxAgeInSeconds = 3600
    }

You can learn about other configuration options from CORS.Configuration.

Last modified: 11 May 2022