keycloak-scim/docbook/auth-server-docs/reference/en/en-US/modules/jetty9-adapter.xml

<!--
  ~ Copyright 2016 Red Hat, Inc. and/or its affiliates
  ~ and other contributors as indicated by the @author tags.
  ~
  ~ Licensed under the Apache License, Version 2.0 (the "License");
  ~ you may not use this file except in compliance with the License.
  ~ You may obtain a copy of the License at
  ~
  ~ http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~ Unless required by applicable law or agreed to in writing, software
  ~ distributed under the License is distributed on an "AS IS" BASIS,
  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  ~ See the License for the specific language governing permissions and
  ~ limitations under the License.
  -->

<section id="jetty9-adapter">
    <title>Jetty 9.x Adapters</title>
    <para>
        Keycloak has a separate adapter for Jetty 9.1.x and Jetty 9.2.x that you will have to install into your Jetty
        installation.  You then have to provide some extra configuration in each WAR you deploy to
        Jetty.  Let's go over these steps.
    </para>
    <section id="jetty9-adapter-installation">
        <title>Adapter Installation</title>
        <para>
            Adapters are no longer included with the appliance or war distribution.Each adapter is a separate download on
            the Keycloak download site.  They are also available as a maven artifact.
        </para>
        <para>
            You must unzip the Jetty 9.x  distro into Jetty 9.x's root directory.  Including
            adapter's jars within your WEB-INF/lib directory will not work!
        </para>
    <para>
<programlisting>
$ cd $JETTY_HOME
$ unzip keycloak-jetty92-adapter-dist.zip
</programlisting>
    </para>
    <para>
        Next, you will have to enable the keycloak module for your jetty.base.
    </para>
        <para>
<programlisting>
$ cd your-base
$ java -jar $JETTY_HOME/start.jar --add-to-startd=keycloak
</programlisting>

        </para>
    </section>

    <section id="jetty9_per_war">
        <title>Required Per WAR Configuration</title>
        <para>
            This section describes how to secure a WAR directly by adding config and editing files within your WAR package.
        </para>
        <para>
            The first thing you must do is create a <literal>WEB-INF/jetty-web.xml</literal> file in your WAR package.  This is
            a Jetty specific config file and you must define a Keycloak specific authenticator within it.
        </para>
        <programlisting>
<![CDATA[
<?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Mort Bay Consulting//DTD Configure//EN" "http://www.eclipse.org/jetty/configure_9_0.dtd">
<Configure class="org.eclipse.jetty.webapp.WebAppContext">
    <Get name="securityHandler">
        <Set name="authenticator">
            <New class="org.keycloak.adapters.jetty.KeycloakJettyAuthenticator">
            </New>
        </Set>
    </Get>
</Configure>]]>
        </programlisting>
        <para>
            Next you must create
            a <literal>keycloak.json</literal> adapter config file within the <literal>WEB-INF</literal> directory
            of your WAR.  The format of this config file is describe in the <link linkend='adapter-config'>general adapter configuration</link>
            section.
        </para>
        <warning>
            <para>
                The Jetty 9.1.x adapter will not be able to find the <literal>keycloak.json</literal> file.  You will have to define
                all adapter settings within the <literal>jetty-web.xml</literal> file as described below.
            </para>
        </warning>
        <para>
            Instead of using keycloak.json, you can define everything within the <literal>jetty-web.xml</literal>.  You'll
            just have to figure out how the json settings match to the <literal>org.keycloak.representations.adapters.config.AdapterConfig</literal>
            class.
        </para>
        <para>
<programlisting>
<![CDATA[
<?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Mort Bay Consulting//DTD Configure//EN" "http://www.eclipse.org/jetty/configure_9_0.dtd">
<Configure class="org.eclipse.jetty.webapp.WebAppContext">
  <Get name="securityHandler">
    <Set name="authenticator">
        <New class="org.keycloak.adapters.jetty.KeycloakJettyAuthenticator">
            <Set name="adapterConfig">
                <New class="org.keycloak.representations.adapters.config.AdapterConfig">
                    <Set name="realm">tomcat</Set>
                    <Set name="resource">customer-portal</Set>
                    <Set name="authServerUrl">http://localhost:8081/auth</Set>
                    <Set name="sslRequired">external</Set>
                    <Set name="credentials">
                        <Map>
                            <Entry>
                                <Item>secret</Item>
                                <Item>password</Item>
                            </Entry>
                        </Map>
                    </Set>
                    <Set name="realmKey">MIGfMA0GCSqGSIb3DQEBAQUAA4</Set>
                </New>
            </Set>
        </New>
    </Set>
  </Get>
</Configure>
]]>
</programlisting>
        </para>
        <para>
            You do not have to crack open your WAR to secure it with keycloak.  Instead create the jetty-web.xml file
            in your webapps directory with the name of yourwar.xml.  Jetty should pick it up.  In this mode, you'll have
            to declare keycloak.json configuration directly within the xml file.
        </para>
        <para>
            Finally you must specify both a <literal>login-config</literal> and use standard servlet security to specify
            role-base constraints on your URLs.  Here's an example:
        </para>
        <para>
<programlisting>
<![CDATA[
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
      version="3.0">

	<module-name>customer-portal</module-name>

    <security-constraint>
        <web-resource-collection>
            <web-resource-name>Customers</web-resource-name>
            <url-pattern>/*</url-pattern>
        </web-resource-collection>
        <auth-constraint>
            <role-name>user</role-name>
        </auth-constraint>
        <user-data-constraint>
            <transport-guarantee>CONFIDENTIAL</transport-guarantee>
        </user-data-constraint>
    </security-constraint>

    <login-config>
        <auth-method>BASIC</auth-method>
        <realm-name>this is ignored currently</realm-name>
    </login-config>

    <security-role>
        <role-name>admin</role-name>
    </security-role>
    <security-role>
        <role-name>user</role-name>
    </security-role>
</web-app>
]]>
</programlisting>
        </para>
    </section>
</section>