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

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

To be able to secure WAR apps deployed on Tomcat 7, 8, and 9, you install the Keycloak Tomcat 7 adapter or 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 7:
+
[source]
----
$ cd $TOMCAT_HOME/lib
$ unzip keycloak-tomcat7-adapter-dist.zip
----

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