keycloak-scim/topics/saml/java/jboss-adapter/jboss_adapter_installation.adoc

[[_saml-jboss-adapter-installation]]
===== Adapter Installation

Each adapter is a separate download on the {{book.project.name}} download site.

{% if book.community %}
Install on Wildfly 9 or 10, or JBoss EAP 7:

[source]
----

$ cd $WILDFLY_HOME
$ unzip keycloak-saml-wildfly-adapter-dist.zip
----
{% endif %}


{% if book.community %}
Install on JBoss EAP 6.x:
[source]
----

$ cd $JBOSS_HOME
$ unzip keycloak-saml-eap6-adapter-dist.zip
----
{% endif %}

{% if book.product %}
Install on JBoss EAP 6.x:
[source]
----

$ cd $JBOSS_HOME
$ unzip RH-SSO-saml-eap6-adapter.zip
----

Install on JBoss EAP 7.x:
[source]
----

$ cd $JBOSS_HOME
$ unzip RH-SSO-saml-eap7-adapter.zip
----
{% endif %}


These zip files create new JBoss Modules specific to the Wildfly/JBoss EPKeycloak SAML Adapter within your Wildfly or JBoss EAP distro.

After adding the modules, you must then enable the {{book.project.name}} SAML Subsystem within your app server's server configuration: `domain.xml` or `standalone.xml`.

There is a CLI script that will help you modify your server configuration.
Start the server and run the script  from the server's bin directory: 

[source]
----

$ cd $JBOSS_HOME/bin
$ jboss-cli.sh -c --file=adapter-install-saml.cli
----        
The script will add the extension, subsystem, and optional security-domain as described below. 

[source,xml]
----
<server xmlns="urn:jboss:domain:1.4">

    <extensions>
        <extension module="org.keycloak.keycloak-saml-adapter-subsystem"/>
          ...
    </extensions>

    <profile>
        <subsystem xmlns="urn:jboss:domain:keycloak-saml:1.1"/>
         ...
    </profile>
----    

The `keycloak` security domain should be used with EJBs and other components when you need the security context created
in the secured web tier to be propagated to the EJBs (other EE component) you are invoking.
Otherwise this configuration is optional. 

[source,xml]
----

<server xmlns="urn:jboss:domain:1.4">
 <subsystem xmlns="urn:jboss:domain:security:1.2">
    <security-domains>
...
      <security-domain name="keycloak">
         <authentication>
           <login-module code="org.keycloak.adapters.jboss.KeycloakLoginModule"
                         flag="required"/>
          </authentication>
      </security-domain>
    </security-domains>
----

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,xml]
----

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();
    }
}
----

We hope to improve our integration in the future so that you don't have to specify the
`@SecurityDomain` annotation when you want to propagate a keycloak security context to the EJB tier.