55 lines
No EOL
3.3 KiB
XML
Executable file
55 lines
No EOL
3.3 KiB
XML
Executable file
<chapter id="cors">
|
|
<title>CORS</title>
|
|
<para>
|
|
CORS stands for Cross-Origin Resource Sharing. If executing browser Javascript tries to make an AJAX HTTP request
|
|
to a server's whose domain is different than the one the Javascript code came from, then the request uses the
|
|
<ulink url="http://www.w3.org/TR/cors/">CORS protocol</ulink>. The server must handle CORS requests in a special
|
|
way, otherwise the browser will not display or allow the request to be processed. This protocol exists to protect
|
|
against XSS and other Javascript-based attacks. Keycloak has support for validated CORS requests.
|
|
</para>
|
|
<para>
|
|
Keycloak's CORS support is configured per client. You specify the allowed origins
|
|
in the client's configuration page in the admin console. You can add as many you want. The value
|
|
must be what the browser would send as a value in the <literal>Origin</literal> header. For example <literal>http://example.com</literal>
|
|
is what you must specify to allow CORS requests from <literal>example.com</literal>. When an access token is
|
|
created for the client, these allowed origins are embedded within the token. On authenticated
|
|
CORS requests, your application's Keycloak adapter will handle the CORS protocol and validate the <literal>Origin</literal>
|
|
header against the allowed origins embedded in the token. If there is no match, then the request is denied.
|
|
</para>
|
|
<para>
|
|
To enable CORS processing in your application's server, you must set the <literal>enable-cors</literal> setting
|
|
to <literal>true</literal> in your <link linkend='adapter-config'>adapter's configuration file</link>. When this
|
|
setting is enabled, the Keycloak adapter will handle all CORS preflight requests. It will validate authenticated
|
|
requests (protected resource requests), but will let unauthenticated requests (unprotected resource requests) pass through.
|
|
</para>
|
|
<section>
|
|
<title>Handling CORS Yourself</title>
|
|
<para>
|
|
This section is for Java developers securing servlet-based applications using our servlet adapter.
|
|
</para>
|
|
<para>
|
|
If you don't like our CORS support you can handle it yourself in a filter or something. One problem you will encounter is that our adapter will
|
|
may trigger for any CORS preflight OPTIONS requests to blindly secured URLs. This will result in 302 redirection or 401 responses
|
|
for the preflight OPTIONS request. To workaround this problem, you must modify your web.xml security constraints to let OPTIONS requests
|
|
through
|
|
<programlisting><![CDATA[
|
|
<security-constraint>
|
|
<web-resource-collection>
|
|
<web-resource-name>wholesale</web-resource-name>
|
|
<url-pattern>/*</url-pattern>
|
|
<http-method>GET</http-method>
|
|
<http-method>POST</http-method>
|
|
<http-method>PUT</http-method>
|
|
<http-method>DELETE</http-method>
|
|
</web-resource-collection>
|
|
...
|
|
</security-constraint>]]>
|
|
|
|
</programlisting>
|
|
</para>
|
|
<para>
|
|
The above security constraint will secure all URLs, but only on GET, POST, PUT, and DELETE calls. OPTIONS requests
|
|
will be let through.
|
|
</para>
|
|
</section>
|
|
</chapter> |