keycloak-scim/docs/documentation/securing_apps/topics/oidc/java/tomcat-adapter.adoc

[[_tomcat_adapter]]
==== Tomcat 8 and 9 adapters

include::adapter-deprecation-notice.adoc[]

To be able to secure WAR apps deployed on Tomcat 8, and 9, you install the Keycloak Tomcat adapter into your Tomcat installation. You then perform extra configuration to secure each WAR you deploy to Tomcat.

[[_tomcat_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 adapter for the Tomcat version on your system from the link:https://www.keycloak.org/downloads[Keycloak Downloads] site.

* Install on Tomcat 8 or 9:
+
[source]
----

$ cd $TOMCAT_HOME/lib
$ unzip keycloak-tomcat-adapter-dist.zip
----

====
[NOTE]
Including the adapter's jars within your WEB-INF/lib directory will not work. The Keycloak adapter is implemented as a Valve and valve code must reside in Tomcat's main lib/ directory.
====

===== Securing a WAR

This section describes how to secure a WAR directly by adding config and editing files within your WAR package.

.Procedure

. Create a `META-INF/context.xml` file in your WAR package.
+
This is a Tomcat specific config file and you must define a Keycloak specific Valve.
+
[source]
----
<Context path="/your-context-path">
    <Valve className="org.keycloak.adapters.tomcat.KeycloakAuthenticatorValve"/>
</Context>
----

. 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>>

. 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>
    </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>
----