docbook updates for adapter
This commit is contained in:
Bill Burke
parent
87ec1e53bf
commit
a793ad3505
5 changed files with 252 additions and 240 deletions
|
|
@ -6,8 +6,7 @@
|
|||
<!ENTITY Installation SYSTEM "modules/server-installation.xml">
|
||||
<!ENTITY OpenShift SYSTEM "modules/openshift.xml">
|
||||
<!ENTITY AdapterConfig SYSTEM "modules/adapter-config.xml">
|
||||
<!ENTITY WildflyAdapter SYSTEM "modules/wildfly-adapter.xml">
|
||||
<!ENTITY EAP6Adapter SYSTEM "modules/eap6-adapter.xml">
|
||||
<!ENTITY JBossAdapter SYSTEM "modules/jboss-adapter.xml">
|
||||
<!ENTITY SocialConfig SYSTEM "modules/social-config.xml">
|
||||
<!ENTITY SocialFacebook SYSTEM "modules/social-facebook.xml">
|
||||
<!ENTITY SocialGitHub SYSTEM "modules/social-github.xml">
|
||||
|
|
@ -15,6 +14,7 @@
|
|||
<!ENTITY SocialTwitter SYSTEM "modules/social-twitter.xml">
|
||||
<!ENTITY SocialProviderSPI SYSTEM "modules/social-spi.xml">
|
||||
<!ENTITY Themes SYSTEM "modules/themes.xml">
|
||||
<!ENTITY Migration SYSTEM "modules/MigrationFromOlderVersions.xml">
|
||||
<!ENTITY Email SYSTEM "modules/email.xml">
|
||||
]>
|
||||
|
||||
|
|
@ -61,8 +61,7 @@
|
|||
your applications.
|
||||
</para>
|
||||
&AdapterConfig;
|
||||
&WildflyAdapter;
|
||||
&EAP6Adapter;
|
||||
&JBossAdapter;
|
||||
</chapter>
|
||||
|
||||
<chapter>
|
||||
|
|
@ -91,6 +90,8 @@
|
|||
&Email;
|
||||
</chapter>
|
||||
|
||||
&Migration;
|
||||
|
||||
</book>
|
||||
|
||||
|
||||
|
|
|
|||
26
docbook/reference/en/en-US/modules/MigrationFromOlderVersions.xml
Executable file
26
docbook/reference/en/en-US/modules/MigrationFromOlderVersions.xml
Executable file
|
|
@ -0,0 +1,26 @@
|
|||
<chapter id="Migration_from_older_versions">
|
||||
<title>Migration from older versions</title>
|
||||
<sect1>
|
||||
<title>Migrating from 1.0 Alpha 1 to 1.0 Alpha 2</title>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
JBoss and Wildfly adapters are now installed via a JBoss/Wildfly subsystem. Please review the adapter
|
||||
installation documentation. Edits to standalone.xml are now required.
|
||||
</listitem>
|
||||
<listitem>
|
||||
There is a new credential type "secret". Unlike other credential types, it is stored in plain text in
|
||||
the database and can be viewed in the admin console.
|
||||
|
||||
</listitem>
|
||||
<listitem>
|
||||
There is no longer required Application or OAuth Client credentials. These client types are now
|
||||
hard coded to use the "secret" credential type.
|
||||
</listitem>
|
||||
<listitem>
|
||||
Because of the "secret" credential change to Application and OAuth Client, you'll have to update
|
||||
your keycloak.json configuration files and regenarate a secret within the Application or OAuth Client
|
||||
credentials tab in the administration console.
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</sect1>
|
||||
</chapter>
|
||||
|
|
@ -1,129 +0,0 @@
|
|||
<section>
|
||||
<title>JBoss EAP6/AS7 Adapter</title>
|
||||
<section>
|
||||
<title>JBoss EAP6/AS7 Adapter Adapter Installation</title>
|
||||
<para>
|
||||
The JBoss EAP6 Adapter is contained in the Keycloak distribution within the <literal>adapters/keycloak-eap6-adapter-dist.zip</literal>
|
||||
file. Conversely, the JBoss AS 7.1.1 adapter is contained in the file <literal>adapters/keycloak-as7-adapter-dist.zip</literal>
|
||||
To install it:
|
||||
</para>
|
||||
<para>
|
||||
<programlisting>
|
||||
$ cd $JBOSS_HOME
|
||||
# For an EAP distro
|
||||
$ unzip keycloak-eap6-adapter-dist.zip
|
||||
|
||||
or
|
||||
# For an JBoss AS 7.1.1 distro
|
||||
$ unzip keycloak-as7-adapter-dist.zip
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
This zip file creates new JBoss Modules specific to the JBoss EAP6 Keycloak Adapter within your JBoss distro.
|
||||
</para>
|
||||
</section>
|
||||
<section>
|
||||
<title>JBoss EAP6/AS7 Adapter Configuration</title>
|
||||
<para>
|
||||
The JBoss EAP6 Adapter is enabled per WAR application. The adapter code is contained in a JBoss Module
|
||||
so you must first create a <literal>jboss-deployment-structure.xml</literal> within your WAR's
|
||||
<literal>WEB-INF</literal> directory that imports the JBoss EAP6 Keycloak Adapter.
|
||||
</para>
|
||||
<para>
|
||||
<programlisting><![CDATA[
|
||||
<jboss-deployment-structure>
|
||||
<deployment>
|
||||
<dependencies>
|
||||
<module name="org.keycloak.keycloak-as7-adapter"/>
|
||||
</dependencies>
|
||||
</deployment>
|
||||
</jboss-deployment-structure>]]>
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
It is possible to add the adapter jars directory to your WAR, but its best to do module imports because
|
||||
the adapter's dependencies may conflict with your application's.
|
||||
</para>
|
||||
<para>
|
||||
Next thing you have to do is turn on the Keycloak adapter for this deployment. To do this you must
|
||||
create a <literal>WEB-INF/jboss-web.xml</literal> file and specify a a Keycloak valve. This will override
|
||||
any <literal>login-config</literal> setting you have defined with <literal>web.xml</literal>
|
||||
</para>
|
||||
<para>
|
||||
<programlisting><![CDATA[<jboss-web>
|
||||
<valve>
|
||||
<class-name>org.keycloak.adapters.as7.KeycloakAuthenticatorValve</class-name>
|
||||
</valve>
|
||||
</jboss-web>]]>
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
After creating the <literal>jboss-web.xml</literal> configuration file, you must create
|
||||
a <literal>keycloak.json</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>
|
||||
While you do have to specify a login-config in your WAR's <literal>web.xml</literal>, it doesn't matter what values you put there.
|
||||
You also
|
||||
have to use standard servlet security to specify role-base constraints on your URLs. Here's an example
|
||||
pulled from one of the examples that comes distributed with Keycloak.
|
||||
</para>
|
||||
<para>
|
||||
<programlisting>
|
||||
<![CDATA[
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<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>Admins</web-resource-name>
|
||||
<url-pattern>/admin/*</url-pattern>
|
||||
</web-resource-collection>
|
||||
<auth-constraint>
|
||||
<role-name>admin</role-name>
|
||||
</auth-constraint>
|
||||
</security-constraint>
|
||||
<security-constraint>
|
||||
<web-resource-collection>
|
||||
<web-resource-name>Customers</web-resource-name>
|
||||
<url-pattern>/customers/*</url-pattern>
|
||||
</web-resource-collection>
|
||||
<auth-constraint>
|
||||
<role-name>user</role-name>
|
||||
</auth-constraint>
|
||||
</security-constraint>
|
||||
|
||||
<!--
|
||||
<security-constraint>
|
||||
<web-resource-collection>
|
||||
<url-pattern>/*</url-pattern>
|
||||
</web-resource-collection>
|
||||
<user-data-constraint>
|
||||
<transport-guarantee>CONFIDENTIAL</transport-guarantee>
|
||||
</user-data-constraint>
|
||||
</security-constraint> -->
|
||||
|
||||
<login-config>
|
||||
<auth-method>BASIC</auth-method>
|
||||
<realm-name>commerce</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> ]
|
||||
|
||||
</section>
|
||||
221
docbook/reference/en/en-US/modules/jboss-adapter.xml
Executable file
221
docbook/reference/en/en-US/modules/jboss-adapter.xml
Executable file
|
|
@ -0,0 +1,221 @@
|
|||
<section>
|
||||
<title>JBoss/Wildfly Adapter</title>
|
||||
<para>
|
||||
To be able to secure WAR apps deployed on JBoss AS 7.1.1, JBoss EAP 6.x, or Wildfly, you must install and
|
||||
configure the Keycloak Subsystem. You then have two options to secure your WARs. You can provide a keycloak
|
||||
config file in your WAR and change the auth-method to KEYCLOAK within web.xml. Alternatively, you don't have
|
||||
to crack open your WARs at all and can apply Keycloak via the Keycloak Subsystem configuration in standalone.xml.
|
||||
Both methods are described in this section.
|
||||
</para>
|
||||
<section>
|
||||
<title>Adapter Installation</title>
|
||||
<para>
|
||||
This is a adapter zip file for AS7, EAP, and Wildfly in the <literal>adapters/</literal> directory in the Keycloak
|
||||
distribution.
|
||||
</para>
|
||||
<para>
|
||||
Install on Wildfly:
|
||||
<programlisting>
|
||||
$ cd $WILDFLY_HOME
|
||||
$ unzip keycloak-wildfly-adapter-dist.zip
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
Install on JBoss EAP 6.x:
|
||||
<programlisting>
|
||||
$ cd $JBOSS_HOME
|
||||
$ unzip keycloak-eap6-adapter-dist.zip
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
Install on JBoss AS 7.1.1:
|
||||
<programlisting>
|
||||
$ cd $JBOSS_HOME
|
||||
$ unzip keycloak-as7-adapter-dist.zip
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
This zip file creates new JBoss Modules specific to the Wildfly Keycloak Adapter within your Wildfly distro.
|
||||
</para>
|
||||
<para>
|
||||
After adding the Keycloak modules, you must then enable the Keycloak Subsystem within your app server's server configuration:
|
||||
<literal>domain.xml</literal> or <literal>standalone.xml</literal>.
|
||||
</para>
|
||||
<para>For Wildfly:
|
||||
<programlisting><![CDATA[
|
||||
<server xmlns="urn:jboss:domain:1.4">
|
||||
|
||||
<extensions>
|
||||
<extension module="org.keycloak.keycloak-wildfly-subsystem"/>
|
||||
...
|
||||
</extensions>
|
||||
|
||||
<profile>
|
||||
<subsystem xmlns="urn:jboss:domain:keycloak:1.0"/>
|
||||
...
|
||||
</profile>
|
||||
]]>
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>For JBoss AS 7.1.1 and EAP 6.x:
|
||||
<programlisting><![CDATA[
|
||||
<server xmlns="urn:jboss:domain:1.4">
|
||||
|
||||
<extensions>
|
||||
<extension module="org.keycloak.keycloak-as7-subsystem"/>
|
||||
...
|
||||
</extensions>
|
||||
|
||||
<profile>
|
||||
<subsystem xmlns="urn:jboss:domain:keycloak:1.0"/>
|
||||
...
|
||||
</profile>
|
||||
]]>
|
||||
</programlisting>
|
||||
</para>
|
||||
</section>
|
||||
<section>
|
||||
<title>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>keycloak.json</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>
|
||||
Next you must set the <literal>auth-method</literal> to <literal>KEYCLOAK</literal> in <literal>web.xml</literal>. You also
|
||||
have to use standard servlet security to specify role-base constraints on your URLs. Here's an example
|
||||
pulled from one of the examples that comes distributed with Keycloak.
|
||||
</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>Admins</web-resource-name>
|
||||
<url-pattern>/admin/*</url-pattern>
|
||||
</web-resource-collection>
|
||||
<auth-constraint>
|
||||
<role-name>admin</role-name>
|
||||
</auth-constraint>
|
||||
</security-constraint>
|
||||
<security-constraint>
|
||||
<web-resource-collection>
|
||||
<web-resource-name>Customers</web-resource-name>
|
||||
<url-pattern>/customers/*</url-pattern>
|
||||
</web-resource-collection>
|
||||
<auth-constraint>
|
||||
<role-name>user</role-name>
|
||||
</auth-constraint>
|
||||
</security-constraint>
|
||||
|
||||
<security-constraint>
|
||||
<web-resource-collection>
|
||||
<url-pattern>/*</url-pattern>
|
||||
</web-resource-collection>
|
||||
<user-data-constraint>
|
||||
<transport-guarantee>CONFIDENTIAL</transport-guarantee>
|
||||
</user-data-constraint>
|
||||
</security-constraint>
|
||||
|
||||
<login-config>
|
||||
<auth-method>KEYCLOAK</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>
|
||||
<section>
|
||||
<title>Securing WARs via Keycloak Subsystem</title>
|
||||
<para>
|
||||
You do not have to crack open a WAR to secure it with Keycloak. Alternatively, you can externally secure
|
||||
it via the Keycloak Subsystem. While you don't have to specify KEYCLOAK as an <literal>auth-method</literal>,
|
||||
you still have to define the <literal>security-constraints</literal> in <literal>web.xml</literal>. You do
|
||||
not, however, have to create a <literal>WEB-INF/keycloak.json</literal> file. This metadata is instead defined
|
||||
within XML in your server's <literal>domain.xml</literal> or <literal>standalone.xml</literal> subsystem
|
||||
configuration section.
|
||||
</para>
|
||||
<para>
|
||||
<programlisting><![CDATA[
|
||||
<server xmlns="urn:jboss:domain:1.4">
|
||||
|
||||
<profile>
|
||||
<subsystem xmlns="urn:jboss:domain:keycloak:1.0">
|
||||
<secure-deployment name="WAR MODULE NAME.war">
|
||||
<realm>demo</realm>
|
||||
<realm-public-key>MIGfMA0GCSqGSIb3DQEBAQUAA</realm-public-key>
|
||||
<auth-server-url>http://localhost:8081/auth</auth-server-url>
|
||||
<ssl-not-required>true</ssl-not-required>
|
||||
<resource>customer-portal</resource>
|
||||
<credential name="secret">password</credential>
|
||||
</secure-deployment>
|
||||
</subsystem>
|
||||
</profile>
|
||||
]]>
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
The <literal>security-deployment</literal> <literal>name</literal> attribute identifies the WAR you want
|
||||
to secure. Its value is the <literal>module-name</literal> defined in <literal>web.xml</literal> with
|
||||
<literal>.war</literal> appended. The rest of the configuration corresponds pretty much one to one
|
||||
with the <literal>keycloak.json</literal> configuration options defined in <link linkend='adapter-config'>general adapter configuration</link>.
|
||||
The exception is the <literal>credential</literal> element.
|
||||
</para>
|
||||
<para>
|
||||
To make it easier for you, you can go to the Keycloak Adminstration Console and go to the Application/Installation
|
||||
tab of the application this WAR is aligned with. It provides an example XML file you can cut and paste.
|
||||
</para>
|
||||
<para>
|
||||
There is an additional convenience format for this XML if you have multiple WARs you are deployment that
|
||||
are secured by the same domain. This format allows you to define common configuration items in one place
|
||||
under the <literal>realm</literal> element.
|
||||
</para>
|
||||
<para>
|
||||
<programlisting><![CDATA[
|
||||
<subsystem xmlns="urn:jboss:domain:keycloak:1.0">
|
||||
<realm name="demo">
|
||||
<realm-public-key>MIGfMA0GCSqGSIb3DQEBA</realm-public-key>
|
||||
<auth-server-url>http://localhost:8080/auth</auth-server-url>
|
||||
<ssl-not-required>true</ssl-not-required>
|
||||
</realm>
|
||||
<secure-deployment name="customer-portal.war">
|
||||
<realm>demo</realm>
|
||||
<resource>customer-portal</resource>
|
||||
<credential name="secret">password</credential>
|
||||
</secure-deployment>
|
||||
<secure-deployment name="product-portal.war">
|
||||
<realm>demo</realm>
|
||||
<resource>product-portal</resource>
|
||||
<credential name="secret">password</credential>
|
||||
</secure-deployment>
|
||||
<secure-deployment name="database.war">
|
||||
<realm>demo</realm>
|
||||
<resource>database-service</resource>
|
||||
<bearer-only>true</bearer-only>
|
||||
</secure-deployment>
|
||||
</subsystem>
|
||||
]]>
|
||||
</programlisting>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
</section>
|
||||
|
|
@ -1,107 +0,0 @@
|
|||
<section>
|
||||
<title>Wildfly 8 Adapter</title>
|
||||
<section>
|
||||
<title>Wildfly Adapter Installation</title>
|
||||
<para>
|
||||
The Wildfly 8 Adapter is contained in the Keycloak distribution within the <literal>adapters/keycloak-wildfly-adapter-dist.zip</literal>
|
||||
file. To install it:
|
||||
</para>
|
||||
<para>
|
||||
<programlisting>
|
||||
$ cd $WILDFLY_HOME
|
||||
$ unzip keycloak-wildfly-adapter-dist.zip
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
This zip file creates new JBoss Modules specific to the Wildfly Keycloak Adapter within your Wildfly distro.
|
||||
</para>
|
||||
</section>
|
||||
<section>
|
||||
<title>Wildfly 8 Adapter Configuration</title>
|
||||
<para>
|
||||
The Wildfly 8 Adapter is enabled per WAR application. The adapter code is contained in a JBoss Module
|
||||
so you must first create a <literal>jboss-deployment-structure.xml</literal> within your WAR's
|
||||
<literal>WEB-INF</literal> directory that imports the Wildfly Keycloak Adapter.
|
||||
</para>
|
||||
<para>
|
||||
<programlisting><![CDATA[
|
||||
<jboss-deployment-structure>
|
||||
<deployment>
|
||||
<dependencies>
|
||||
<module name="org.keycloak.keycloak-undertow-adapter" services="import"/>
|
||||
</dependencies>
|
||||
</deployment>
|
||||
</jboss-deployment-structure>]]>
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
It is possible to add the adapter jars directory to your WAR, but its best to do module imports because
|
||||
the adapter's dependencies may conflict with your application's.
|
||||
</para>
|
||||
<para>
|
||||
After creating the <literal>jboss-deployment-structure.xml</literal> configuration file, you must create
|
||||
a <literal>keycloak.json</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 set the <literal>auth-method</literal> to <literal>KEYCLOAK</literal> in <literal>web.xml</literal>. You also
|
||||
have to use standard servlet security to specify role-base constraints on your URLs. Here's an example
|
||||
pulled from one of the examples that comes distributed with Keycloak.
|
||||
</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>Admins</web-resource-name>
|
||||
<url-pattern>/admin/*</url-pattern>
|
||||
</web-resource-collection>
|
||||
<auth-constraint>
|
||||
<role-name>admin</role-name>
|
||||
</auth-constraint>
|
||||
</security-constraint>
|
||||
<security-constraint>
|
||||
<web-resource-collection>
|
||||
<web-resource-name>Customers</web-resource-name>
|
||||
<url-pattern>/customers/*</url-pattern>
|
||||
</web-resource-collection>
|
||||
<auth-constraint>
|
||||
<role-name>user</role-name>
|
||||
</auth-constraint>
|
||||
</security-constraint>
|
||||
|
||||
<security-constraint>
|
||||
<web-resource-collection>
|
||||
<url-pattern>/*</url-pattern>
|
||||
</web-resource-collection>
|
||||
<user-data-constraint>
|
||||
<transport-guarantee>CONFIDENTIAL</transport-guarantee>
|
||||
</user-data-constraint>
|
||||
</security-constraint>
|
||||
|
||||
<login-config>
|
||||
<auth-method>KEYCLOAK</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> ]
|
||||
|
||||
</section>
|
||||
Loading…
Reference in a new issue