keycloak-uncached
Changes
docbook/reference/en/en-US/modules/jboss-adapter.xml 221(+221 -0)
Details
diff --git a/docbook/reference/en/en-US/master.xml b/docbook/reference/en/en-US/master.xml
index d87cb04..9d73cef 100755
--- a/docbook/reference/en/en-US/master.xml
+++ b/docbook/reference/en/en-US/master.xml
@@ -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>
docbook/reference/en/en-US/modules/jboss-adapter.xml 221(+221 -0)
diff --git a/docbook/reference/en/en-US/modules/jboss-adapter.xml b/docbook/reference/en/en-US/modules/jboss-adapter.xml
new file mode 100755
index 0000000..c6e6597
--- /dev/null
+++ b/docbook/reference/en/en-US/modules/jboss-adapter.xml
@@ -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>
\ No newline at end of file
diff --git a/docbook/reference/en/en-US/modules/MigrationFromOlderVersions.xml b/docbook/reference/en/en-US/modules/MigrationFromOlderVersions.xml
new file mode 100755
index 0000000..2c701b0
--- /dev/null
+++ b/docbook/reference/en/en-US/modules/MigrationFromOlderVersions.xml
@@ -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>
\ No newline at end of file