Merge pull request #242 from patriot1burke/master

cors docs

docbook/reference/en/en-US/master.xml

@@ -18,6 +18,7 @@
                 <!ENTITY Migration SYSTEM "modules/MigrationFromOlderVersions.xml">
                 <!ENTITY Email SYSTEM "modules/email.xml">
                 <!ENTITY Roles SYSTEM "modules/roles.xml">
+                <!ENTITY CORS SYSTEM "modules/cors.xml">
                 <!ENTITY Timeouts SYSTEM "modules/timeouts.xml">
                 ]>
 
@@ -94,6 +95,7 @@
         &Email;
     </chapter>
     &Roles;
+    &CORS;
     &Timeouts;
     &Migration;
 

docbook/reference/en/en-US/modules/adapter-config.xml

@@ -18,7 +18,7 @@
   "bearer-only" : false,
   "expose-token" : true,
    "credentials" : {
-      "password" : "password"
+      "secret" : "234234-234234-234234"
    }
 
    "connection-pool-size" : 20,

docbook/reference/en/en-US/modules/cors.xml

@@ -0,0 +1,25 @@
+<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 application and oauth client.  You specify the allowed origins
+        in the application's or oauth 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 application or OAuth 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>
+</chapter>

docbook/reference/en/en-US/modules/javascript-adapter.xml

@@ -10,7 +10,7 @@
         disadvantage of using this approach is that you end up having a non-confidential, public client.  This can be mitigated
         by registering valid redirect URLs.  You are still vulnerable if somebody hijacks the IP/DNS name of your pure
         HTML/Javascript application though.
-    </para>
+    </para>                                                                  startAsync
     <para>
         To use this adapter, you first must load and initialize the keycloak javascript library into your application.
 <programlisting><![CDATA[

integration/as7-eap6/adapter/src/main/java/org/keycloak/adapters/as7/AuthenticatedActionsValve.java

@@ -118,7 +118,7 @@ public class AuthenticatedActionsValve extends ValveBase {
             response.setHeader("Access-Control-Allow-Origin", origin);
             response.setHeader("Access-Control-Allow-Credentials", "true");
         } else {
-            log.debugv("session or origin was null: {0}", request.getRequestURI());
+            log.debugv("letting through.  This is an unathenticated session or origin header was null: {0}", request.getRequestURI());
         }
         return false;
     }

integration/undertow/src/main/java/org/keycloak/adapters/undertow/AuthenticatedActionsHandler.java

@@ -124,7 +124,7 @@ public class AuthenticatedActionsHandler implements HttpHandler {
             exchange.getResponseHeaders().put(PreflightCorsHandler.ACCESS_CONTROL_ALLOW_ORIGIN, origin);
             exchange.getResponseHeaders().put(PreflightCorsHandler.ACCESS_CONTROL_ALLOW_CREDENTIALS, "true");
         } else {
-            log.debugv("not secured or origin was null: {0}", exchange.getRequestURI());
+            log.debugv("cors validation not needed as we're not a secure session or origin header was null: {0}", exchange.getRequestURI());
         }
         return false;
     }