2016-04-18 19:10:32 +00:00
[[_jboss_adapter]]
2016-06-03 08:02:59 +00:00
{% if book.community %}
=== JBoss EAP/Wildfly Adapter
{% endif %}
{% if book.product %}
=== JBoss EAP Adapter
{% endif %}
2016-04-18 19:10:32 +00:00
2016-06-03 08:02:59 +00:00
To be able to secure WAR apps deployed on JBoss EAP {% if book.community %}, WildFly or JBoss AS{% endif %}, you must install and configure the
{{book.project.name}} adapter subsystem. You then have two options to secure your WARs.
You can provide an adapter config file in your WAR and change the auth-method to KEYCLOAK within web.xml.
Alternatively, you don't have to modify your WAR at all and you can secure it via the {{book.project.name}} adapter subsystem configuration in `standalone.xml`.
Both methods are described in this section.
2016-04-18 19:10:32 +00:00
[[_jboss_adapter_installation]]
2016-06-01 11:02:44 +00:00
==== Adapter Installation
2016-04-18 19:10:32 +00:00
2016-06-03 08:02:59 +00:00
Adapters are available as a separate archive and are also available as Maven artifacts.
2016-04-18 19:10:32 +00:00
2016-06-03 08:02:59 +00:00
{% if book.community %}
Install on Wildfly 9 or 10:
2016-04-18 19:10:32 +00:00
2016-06-09 12:54:13 +00:00
[source, subs="attributes"]
2016-04-18 19:10:32 +00:00
----
2016-06-03 08:02:59 +00:00
$ cd $WILDFLY_HOME
$ unzip keycloak-wildfly-adapter-dist-{{book.project.version}}.zip
----
Install on Wildfly 8:
2016-04-18 19:10:32 +00:00
2016-06-09 12:54:13 +00:00
[source, subs="attributes"]
2016-06-03 08:02:59 +00:00
----
2016-04-18 19:10:32 +00:00
$ cd $WILDFLY_HOME
2016-06-03 08:02:59 +00:00
$ unzip keycloak-wf8-adapter-dist-{{book.project.version}}.zip
----
Install on JBoss EAP 7:
2016-04-18 19:10:32 +00:00
2016-06-09 12:54:13 +00:00
[source, subs="attributes"]
2016-04-18 19:10:32 +00:00
----
2016-06-03 08:02:59 +00:00
$ cd $EAP_HOME
$ unzip keycloak-eap7-adapter-dist-{{book.project.version}}.zip
----
2016-04-18 19:10:32 +00:00
2016-06-03 08:02:59 +00:00
Install on JBoss EAP 6:
2016-04-18 19:10:32 +00:00
2016-06-09 12:54:13 +00:00
[source, subs="attributes"]
2016-04-18 19:10:32 +00:00
----
2016-06-03 08:02:59 +00:00
$ cd $EAP_HOME
$ unzip keycloak-eap6-adapter-dist-{{book.project.version}}.zip
----
2016-04-18 19:10:32 +00:00
2016-06-03 08:02:59 +00:00
Install on JBoss AS 7.1:
2016-04-18 19:10:32 +00:00
2016-06-09 12:54:13 +00:00
[source, subs="attributes"]
2016-04-18 19:10:32 +00:00
----
$ cd $JBOSS_HOME
2016-06-03 08:02:59 +00:00
$ unzip keycloak-as7-adapter-dist-{{book.project.version}}.zip
----
{% endif %}
2016-04-18 19:10:32 +00:00
2016-06-03 08:02:59 +00:00
{% if book.product %}
Install on JBoss EAP 7:
2016-04-18 19:10:32 +00:00
2016-06-09 12:54:13 +00:00
[source, subs="attributes"]
2016-06-03 08:02:59 +00:00
----
$ cd $EAP_HOME
2016-06-09 12:41:13 +00:00
$ unzip rh-sso-{{book.project.version}}-eap7-adapter.zip
2016-06-03 08:02:59 +00:00
----
2016-04-18 19:10:32 +00:00
2016-06-03 08:02:59 +00:00
Install on JBoss EAP 6:
2016-04-18 19:10:32 +00:00
2016-06-09 12:54:13 +00:00
[source, subs="attributes"]
2016-04-18 19:10:32 +00:00
----
2016-06-03 08:02:59 +00:00
$ cd $EAP_HOME
2016-06-09 12:41:13 +00:00
$ unzip rh-sso-{{book.project.version}}-eap6-adapter.zip
2016-06-03 08:02:59 +00:00
----
{% endif %}
2016-04-18 19:10:32 +00:00
2016-06-03 08:02:59 +00:00
This ZIP archive contains JBoss Modules specific to the {{book.project.name}} adapter. It also contains JBoss CLI scripts to install and configure the adapter.
2016-04-18 19:10:32 +00:00
2016-06-03 08:02:59 +00:00
Once the ZIP archive is extracted you have to enable the {{book.project.name}} subystem in the server configuration (i.e. `standalone.xml`). The easiest way to
do this is to use the supplied JBoss CLI scripts.
To install and configure the adapter, first start the server and then run the JBoss CLI installation script :
2016-04-18 19:10:32 +00:00
[source]
----
2016-06-03 08:02:59 +00:00
$ ./bin/jboss-cli.sh -c --file=adapter-install.cli
----
2016-04-18 19:10:32 +00:00
2016-06-03 08:02:59 +00:00
The script will add the required configuration to the server configuration file.
For JBoss EAP 7 {% if book.community %} and WildFly 9+{% endif %} there is also an offline CLI script that can be used to install the adapter while the server
is not running:
2016-04-18 19:10:32 +00:00
[source]
----
2016-06-03 08:02:59 +00:00
$ ./bin/jboss-cli.sh -c --file=adapter-install-offline.cli
----
2016-04-18 19:10:32 +00:00
2016-06-03 08:02:59 +00:00
If you are planning to add it manually you need to add the extension and subsystem definition to the server configuration:
2016-04-18 19:10:32 +00:00
2016-06-03 08:02:59 +00:00
[source,xml]
----
<extensions>
<extension module="org.keycloak.keycloak-adapter-subsystem"/>
...
</extensions>
2016-04-18 19:10:32 +00:00
2016-06-03 08:02:59 +00:00
<profile>
<subsystem xmlns="urn:jboss:domain:keycloak:1.1"/>
...
</profile>
----
2016-04-18 19:10:32 +00:00
2016-06-03 08:02:59 +00:00
If you need to be able to propagate the security context from the web tier to the EJB tier you also need to add the `keycloak` security domain:
2016-04-18 19:10:32 +00:00
2016-06-03 08:02:59 +00:00
[source,xml]
2016-04-18 19:10:32 +00:00
----
2016-06-03 08:02:59 +00:00
<subsystem xmlns="urn:jboss:domain:security:...">
2016-04-18 19:10:32 +00:00
<security-domains>
2016-06-03 08:02:59 +00:00
...
<security-domain name="keycloak">
<authentication>
<login-module code="org.keycloak.adapters.jboss.KeycloakLoginModule"
flag="required"/>
</authentication>
</security-domain>
2016-04-18 19:10:32 +00:00
</security-domains>
2016-06-03 08:02:59 +00:00
...
2016-04-18 19:10:32 +00:00
----
For example, if you have a JAX-RS service that is an EJB within your WEB-INF/classes directory, you'll want to annotate it with the @SecurityDomain annotation as follows:
[source]
----
import org.jboss.ejb3.annotation.SecurityDomain;
import org.jboss.resteasy.annotations.cache.NoCache;
import javax.annotation.security.RolesAllowed;
import javax.ejb.EJB;
import javax.ejb.Stateless;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import java.util.ArrayList;
import java.util.List;
@Path("customers")
@Stateless
@SecurityDomain("keycloak")
public class CustomerService {
@EJB
CustomerDB db;
@GET
@Produces("application/json")
@NoCache
@RolesAllowed("db_user")
public List<String> getCustomers() {
return db.getCustomers();
}
}
----
2016-06-01 11:02:44 +00:00
==== Required Per WAR Configuration
2016-04-18 19:10:32 +00:00
This section describes how to secure a WAR directly by adding config and editing files within your WAR package.
The first thing you must do is create a `keycloak.json` adapter config file within the `WEB-INF` directory of your WAR.
2016-06-06 09:25:35 +00:00
2016-06-06 09:13:45 +00:00
The format of this config file is describe in the <<fake/../java-adapter-config.adoc#_java_adapter_config,Java adapter configuration>> section.
2016-04-18 19:10:32 +00:00
Next you must set the `auth-method` to `KEYCLOAK` in `web.xml`.
You also have to use standard servlet security to specify role-base constraints on your URLs.
2016-06-03 08:02:59 +00:00
Here's an example:
2016-04-18 19:10:32 +00:00
2016-06-03 08:02:59 +00:00
[source,xml]
2016-04-18 19:10:32 +00:00
----
<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">
2016-06-03 08:02:59 +00:00
<module-name>application</module-name>
2016-04-18 19:10:32 +00:00
<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>
<user-data-constraint>
<transport-guarantee>CONFIDENTIAL</transport-guarantee>
</user-data-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>
<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>
----
2016-06-09 12:41:13 +00:00
==== Securing WARs via Adapter Subsystem
2016-04-18 19:10:32 +00:00
2016-06-09 12:33:42 +00:00
You do not have to modify your WAR to secure it with {{book.project.name}}. Instead you can externally secure it via the {{book.project.name}} Adapter Subsystem.
2016-04-18 19:10:32 +00:00
While you don't have to specify KEYCLOAK as an `auth-method`, you still have to define the `security-constraints` in `web.xml`.
You do not, however, have to create a `WEB-INF/keycloak.json` file.
2016-06-09 12:33:42 +00:00
This metadata is instead defined within server configuration (i.e. `standalone.xml`) in the {{book.project.name}} subsystem definition.
2016-04-18 19:10:32 +00:00
2016-06-03 08:02:59 +00:00
[source,xml]
2016-04-18 19:10:32 +00:00
----
<extensions>
<extension module="org.keycloak.keycloak-adapter-subsystem"/>
</extensions>
<profile>
<subsystem xmlns="urn:jboss:domain:keycloak:1.1">
<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-required>external</ssl-required>
<resource>customer-portal</resource>
<credential name="secret">password</credential>
</secure-deployment>
</subsystem>
</profile>
----
The `secure-deployment` `name` attribute identifies the WAR you want to secure.
2016-06-09 13:03:16 +00:00
Its value is the `module-name` defined in `web.xml` with `.war` appended. The rest of the configuration corresponds pretty much one to one with the `keycloak.json` configuration options defined in <<fake/../java-adapter-config.adoc#_java_adapter_config,Java adapter configuration>>.
2016-06-06 09:25:35 +00:00
2016-04-18 19:10:32 +00:00
The exception is the `credential` element.
2016-06-09 12:58:36 +00:00
To make it easier for you, you can go to the {{book.project.name}} Administration Console and go to the Client/Installation tab of the application this WAR is aligned with.
2016-04-18 19:10:32 +00:00
It provides an example XML file you can cut and paste.
2016-06-09 12:57:50 +00:00
If you have multiple deployments secured by the same realm you can share the realm configuration in a separate element. For example:
2016-04-18 19:10:32 +00:00
2016-06-03 08:02:59 +00:00
[source,xml]
2016-04-18 19:10:32 +00:00
----
<subsystem xmlns="urn:jboss:domain:keycloak:1.1">
<realm name="demo">
2016-06-03 08:02:59 +00:00
<realm-public-key>MIGfMA0GCSqGSIb3DQEBA...</realm-public-key>
2016-04-18 19:10:32 +00:00
<auth-server-url>http://localhost:8080/auth</auth-server-url>
<ssl-required>external</ssl-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>
----