109 lines
No EOL
4.1 KiB
XML
Executable file
109 lines
No EOL
4.1 KiB
XML
Executable file
<!--
|
|
~ 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="tomcat-adapter">
|
|
<title>Tomcat 6, 7 and 8 SAML adapters</title>
|
|
<para>
|
|
To be able to secure WAR apps deployed on Tomcat 6, 7 and 8 you must install the Keycloak Tomcat 6, 7 or 8 SAML adapter
|
|
into your Tomcat installation. You then have to provide some extra configuration in each WAR you deploy to
|
|
Tomcat. Let's go over these steps.
|
|
</para>
|
|
<section id="tomcat-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 adapter distro into Tomcat's <literal>lib/</literal> directory. Including
|
|
adapter's jars within your WEB-INF/lib directory will not work! The Keycloak SAML adapter is implemented as a Valve
|
|
and valve code must reside in Tomcat's main lib/ directory.
|
|
</para>
|
|
<para>
|
|
<programlisting>
|
|
$ cd $TOMCAT_HOME/lib
|
|
$ unzip keycloak-saml-tomcat6-adapter-dist.zip
|
|
or
|
|
$ unzip keycloak-saml-tomcat7-adapter-dist.zip
|
|
or
|
|
$ unzip keycloak-saml-tomcat8-adapter-dist.zip
|
|
</programlisting>
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<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>META-INF/context.xml</literal> file in your WAR package. This is
|
|
a Tomcat specific config file and you must define a Keycloak specific Valve.
|
|
</para>
|
|
<programlisting>
|
|
<![CDATA[
|
|
<Context path="/your-context-path">
|
|
<Valve className="org.keycloak.adapters.saml.tomcat.SamlAuthenticatorValve"/>
|
|
</Context>]]>
|
|
</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>
|
|
</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> |