
[[_jetty9_adapter]]
==== Jetty 9.x adapters

Keycloak has a separate adapter for Jetty 9.2.x, Jetty 9.3.x and Jetty 9.4.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.

[[_jetty9_adapter_installation]]
===== Installing the adapter

Adapters are no longer included with the appliance or war distribution. Each adapter is a separate download on the Keycloak downloads site. They are also available as a maven artifact.

.Procedure
.  Download the {project_name} Jetty 9.x adapter ZIP archive from the link:https://www.keycloak.org/downloads[Keycloak Downloads] site.

. Unzip the Jetty 9.x distro into Jetty 9.x's link:https://www.eclipse.org/jetty/documentation/jetty-9/index.html[base directory]. In the example below, the Jetty base is named `your-base`:
+
[source]
----
$ cd your-base
$ unzip keycloak-jetty93-adapter-dist-2.5.0.Final.zip
----

. Enable the `keycloak` module for your Jetty base:
+
[source]
----
$ java -jar $JETTY_HOME/start.jar --add-to-startd=keycloak
----
+
====
[NOTE]
Including the adapter's jars within your WEB-INF/lib directory will not work.
====

[[_jetty9_per_war]]
===== Jetty 9 Securing a WAR

Use this procedure to secure a WAR directly by adding config and editing files within your WAR package.

.Procedure

. Create a `WEB-INF/jetty-web.xml` file in your WAR package. This is a Jetty specific config fil. You define a Keycloak specific authenticator within it.
+
[source]
----
<?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>
----

. Create a `keycloak.json` adapter config file within the `WEB-INF` directory of your WAR.
+
The format of this config file is described in the <<_java_adapter_config,Java adapter configuration>>            section.
+
WARNING: The Jetty 9.x adapter will not be able to find the `keycloak.json` file.
You will have to define all adapter settings within the `jetty-web.xml` file as described below.
Instead of using keycloak.json, you can define everything within the `jetty-web.xml`.
You'll just have to figure out how the json settings match to the `org.keycloak.representations.adapters.config.AdapterConfig` class.
+
[source]
----
<?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>
                </New>
            </Set>
        </New>
    </Set>
  </Get>
</Configure>
----


. Create the jetty-web.xml file in your webapps directory with the name of yourwar.xml.
Jetty should pick it up. You do not need to open your WAR to secure it with {project_name}.
In this mode, you declare keycloak.json configuration directly within the xml file.

. Specify both a `login-config` and use standard servlet security to specify role-base constraints on your URLs. Here's an example:
+
[source,xml]
----
<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>
----
