[[Keycloak_SAML_Integration]]
= Using Keycloak SAML

To secure applications deployed to WildFly using Keycloak SAML, a Galleon feature pack provided
by the Keycloak project needs to be used. This feature pack automatically installs the Keycloak
SAML adapter that results in the `keycloak-saml` subsystem being added to WildFly.

There are a few ways to install the Keycloak Galleon Feature Pack that provides the SAML adapter.

[[galleon-cli]]
== Galleon CLI

A server installation can be provisioned using the Galleon CLI.

More information can be found in the <<Galleon_Guide.adoc#Galleon_Guide,Provisioning WildFly with Galleon>>
documentation, but assuming you have provisioned a WildFly installation containing the `web-server` layer
with a command similar to the following:

[source]
----
galleon.sh install wildfly:current \
    --layers=web-server --dir=wildfly
----

The Keycloak SAML adapter can then be added to the WildFly installation with the following command:

[source]
----
TODO: Update the version here when we know what it is
galleon.sh install org.keycloak:keycloak-saml-adapter-galleon-pack:999 --layers=keycloak-client-saml --dir=wildfly
----

[NOTE]
====
Unlike the WildFly feature pack, this Keycloak feature pack is not part of a universe and so a fully
qualified `group:artifact:version` reference to the feature pack is required.
====

From this point, applications can be configured as described in the
https://www.keycloak.org/docs/latest/securing_apps/index.html#_jboss_adapter[Keycloak documentation].

[[bootable-jar]]
== Bootable JAR

The next installation option is if you are creating a bootable JAR for your deployment and want to
add the Keycloak SAML adapter to secure the deployment.  More details about bootable JAR support can
be found in the <<Bootable_Guide.adoc#wildfly_bootable_JAR_development,Bootable JAR Guide>>.

The following is an example plug-in configuration to create a bootable JAR for a web application
using both the `web-server` and `keycloak-client-saml` layers:

[source,xml,options="nowrap"]
----
<plugin>
    <groupId>org.wildfly.plugins</groupId>
    <artifactId>wildfly-jar-maven-plugin</artifactId>
    <version>${version.wildfly.jar.maven.plugin}</version>
    <configuration>
        <feature-packs>
            <feature-pack>
                <location>wildfly@maven(org.jboss.universe:community-universe):current</location>
            </feature-pack>
            <feature-pack>
                <groupId>org.keycloak</groupId>
                <artifactId>keycloak-saml-adapter-galleon-pack</artifactId>
                <version>999</version> <!-- TODO: Update version when we know what it is -->
            </feature-pack>
        </feature-packs>
        <layers>
            <layer>web-server</layer>
            <layer>keycloak-client-saml</layer>
        </layers>
        <context-root>simple-webapp</context-root>
        <cli-sessions>
            <cli-session>
                <script-files>
                    <script>configure-saml.cli</script>
                </script-files>
            </cli-session>
        </cli-sessions>
    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>package</goal>
            </goals>
        </execution>
    </executions>
</plugin>
----

[NOTE]
====
As with using the CLI, the latest version of WildFly in the universe can be dynamically selected but the
Keycloak feature pack requires the complete `groupId`, `artifactId`, and `version` to be specified.
====

The approaches to configure the web application are the same as described in the
https://www.keycloak.org/docs/latest/securing_apps/index.html#_jboss_adapter[Keycloak documentation].
In this example, a CLI script, `configure-saml.cli`, is executed to update the Keycloak SAML subsystem
with relevant configuration.

A sample script is shown below:

[source]
----
/subsystem=keycloak-saml/secure-deployment=simple-webapp.war/:add

/subsystem=keycloak-saml/secure-deployment=simple-webapp.war/SP="http://localhost:8090/simple-webapp"/:add(sslPolicy=EXTERNAL,logoutPage="logout")

/subsystem=keycloak-saml/secure-deployment=simple-webapp.war/SP="http://localhost:8090/simple-webapp"/IDP=idp/:add( \
    SingleSignOnService={ \
        signRequest=false, \
        validateResponseSignature=false, \
        validateAssertionSignature=false, \
        requestBinding=POST, \
        bindingUrl=http://localhost:8080/realms/myrealm/protocol/saml}, \
    SingleLogoutService={ \
        signRequest=false, \
        signResponse=false, \
        validateRequestSignature=false, \
        validateResponseSignature=false, \
        requestBinding=POST, \
        responseBinding=POST, \
        postBindingUrl=http://localhost:8080/realms/myrealm/protocol/saml, \
        redirectBindingUrl=http://localhost:8080/realms/myrealm/protocol/saml} \
)

----

Instead of adding configuration in the Keycloak SAML subsystem, configuration can be added in the deployment
instead. In particular, the `auth-method` of the web application could be set to `KEYCLOAK-SAML` and
adapter configuration could be provided in a `keycloak-saml.json` descriptor placed within the `WEB-INF` directory
of the deployment.

[[wildfly-maven-plugin]]
== WildFly Maven Plugin

The final installation option is to use the `wildfly-maven-plugin` to provision a server containing
the Keycloak SAML subsystem.

The following is an example plug-in configuration to create a server for a web application
using both the `web-server` and `keycloak-client-saml` layers:

[source,xml,options="nowrap"]
----
<plugin>
    <groupId>org.wildfly.plugins</groupId>
    <artifactId>wildfly-maven-plugin</artifactId>
    <version>4.0.0.Final</version>
    <configuration>
        <feature-packs>
            <feature-pack>
                <location>wildfly@maven(org.jboss.universe:community-universe):current</location>
            </feature-pack>
            <feature-pack>
                <groupId>org.keycloak</groupId>
                <artifactId>keycloak-saml-adapter-galleon-pack</artifactId>
                <version>999</version> <!-- TODO: Update version when we know what it is -->
            </feature-pack>
        </feature-packs>
        <layers>
            <layer>web-server</layer>
            <layer>keycloak-client-saml</layer>
        </layers>
    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>package</goal>
            </goals>
        </execution>
    </executions>
</plugin>
----

[NOTE]
====
As with the bootable JAR configuration, note that the latest version of WildFly in the universe can be dynamically
selected but the Keycloak feature pack requires the complete `groupId`, `artifactId`, and `version` to be
specified.
====

[[identity-propagation]]
== Propagating the Security Context to EJBs

The sample configuration in the above sections has referenced the `keycloak-client-saml` layer.
If the security context for the application that is being secured with Keycloak SAML needs to
be propagated to the EJB tier, the `keycloak-client-saml-ejb` layer should be used instead.
This layer adds an `application-security-domain` mapping in the EJB3 subsystem to map the default
security domain name `other` to the `KeycloakDomain` that is installed by the Keycloak feature pack.
