keycloak-scim/docbook/saml-adapter-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.
  -->

<chapter id="jetty9-adapter">
    <title>Jetty 9.x SAML Adapters</title>
    <para>
        Keycloak has a separate SAML adapter for Jetty 9.x.  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-saml-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.saml.jetty.KeycloakSamlAuthenticator">
            </New>
        </Set>
    </Get>
</Configure>]]>
        </programlisting>
        <para>
            Next you must create
            a <literal>keycloak-saml.xml</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>
        <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>
</chapter>