Remove OIDC and SAML adapters for Wildfly/EAP ZIP downloads. Update documentation. (#24877)
* Update EAP documentation for OIDC and SAML (#24734) Co-authored-by: andymunro <48995441+andymunro@users.noreply.github.com> (cherry picked from commit d7f2ad747d90dd0475a016fcfd528fea4ebed043) Signed-off-by: Stian Thorgersen <stianst@gmail.com> * Remove OIDC and SAML adapters for Wildfly/EAP ZIP downloads. Update documentation. Closes #24713 Signed-off-by: mposolda <mposolda@gmail.com> Co-authored-by: Stian Thorgersen <stian@redhat.com> --------- Signed-off-by: Stian Thorgersen <stianst@gmail.com> Co-authored-by: Stian Thorgersen <stianst@gmail.com> Co-authored-by: Stian Thorgersen <stian@redhat.com>
This commit is contained in:
Marek Posolda
GitHub
parent
15a83985b1
commit
765e4838e9
9 changed files with 125 additions and 525 deletions
|
|
@ -3,11 +3,9 @@ mvn:keycloak-api-docs-dist:keycloak-api-docs
|
|||
|
||||
mvn:keycloak-jetty94-adapter-dist:keycloak-oidc-jetty94-adapter
|
||||
mvn:keycloak-tomcat-adapter-dist:keycloak-oidc-tomcat-adapter
|
||||
mvn:keycloak-wildfly-adapter-dist:keycloak-oidc-wildfly-adapter
|
||||
|
||||
mvn:keycloak-saml-jetty94-adapter-dist:keycloak-saml-jetty94-adapter
|
||||
mvn:keycloak-saml-tomcat-adapter-dist:keycloak-saml-tomcat-adapter
|
||||
mvn:keycloak-saml-wildfly-adapter-dist:keycloak-saml-wildfly-adapter
|
||||
|
||||
mvn:documentation/keycloak-documentation:keycloak-documentation
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,9 @@
|
|||
= OIDC and SAML adapter changes for WildFly and JBoss EAP
|
||||
|
||||
OIDC adapter for the WildFly and JBoss EAP, which was deprecated in previous versions, is removed in this release. It is being replaced by the Elytron OIDC adapter,
|
||||
which is included in WildFly. The SAML adapter ZIP download for WildFly/EAP is removed as it is being replaced by the Galleon feature pack.
|
||||
See the link:{adapterguide_link}[{adapterguide_name}] for the details.
|
||||
|
||||
= Localization files for themes default to UTF-8 encoding
|
||||
|
||||
Message properties files for themes are now read in UTF-8 encoding, with an automatic fallback to ISO-8859-1 encoding.
|
||||
|
|
|
|||
|
|
@ -15,6 +15,9 @@ include::topics/oidc/supported-grant-types.adoc[]
|
|||
ifeval::[{project_community}==true]
|
||||
include::topics/oidc/java/java-adapters.adoc[]
|
||||
endif::[]
|
||||
ifeval::[{project_product}==true]
|
||||
include::topics/oidc/java/java-adapters-product.adoc[]
|
||||
endif::[]
|
||||
|
||||
include::topics/oidc/javascript-adapter.adoc[]
|
||||
|
||||
|
|
@ -29,51 +32,14 @@ include::topics/oidc/fapi-support.adoc[]
|
|||
include::topics/oidc/recommendations.adoc[]
|
||||
|
||||
include::topics/saml/saml-overview.adoc[]
|
||||
ifeval::[{project_community}==true]
|
||||
include::topics/saml/java/java-adapters.adoc[]
|
||||
include::topics/saml/java/general-config.adoc[]
|
||||
include::topics/saml/java/general-config/sp_element.adoc[]
|
||||
include::topics/saml/java/general-config/sp-keys.adoc[]
|
||||
include::topics/saml/java/general-config/sp-keys/keystore_element.adoc[]
|
||||
include::topics/saml/java/general-config/sp-keys/key_pems.adoc[]
|
||||
include::topics/saml/java/general-config/sp_principalname_mapping_element.adoc[]
|
||||
include::topics/saml/java/general-config/roleidentifiers_element.adoc[]
|
||||
include::topics/saml/java/general-config/sp_role_mappings_provider_element.adoc[]
|
||||
include::topics/saml/java/general-config/idp_element.adoc[]
|
||||
include::topics/saml/java/general-config/idp_allowedclockskew_subelement.adoc[]
|
||||
include::topics/saml/java/general-config/idp_singlesignonservice_subelement.adoc[]
|
||||
include::topics/saml/java/general-config/idp_singlelogoutservice_subelement.adoc[]
|
||||
include::topics/saml/java/general-config/idp_keys_subelement.adoc[]
|
||||
include::topics/saml/java/general-config/idp_httpclient_subelement.adoc[]
|
||||
include::topics/saml/java/saml-jboss-adapter.adoc[]
|
||||
include::topics/saml/java/jboss-adapter/jboss_adapter_installation.adoc[]
|
||||
include::topics/saml/java/jboss-adapter/jboss-adapter-samesite-setting.adoc[]
|
||||
|
||||
ifeval::[{project_product}==true]
|
||||
include::topics/saml/java/jboss-adapter/jboss-adapter-rpms.adoc[]
|
||||
endif::[]
|
||||
include::topics/saml/java/jboss-adapter/required_per_war_configuration.adoc[]
|
||||
include::topics/saml/java/jboss-adapter/securing_wars.adoc[]
|
||||
ifeval::[{project_community}==true]
|
||||
include::topics/saml/java/tomcat-adapter.adoc[]
|
||||
include::topics/saml/java/tomcat-adapter/tomcat_adapter_installation.adoc[]
|
||||
include::topics/saml/java/tomcat-adapter/tomcat_adapter_per_war_config.adoc[]
|
||||
include::topics/saml/java/tomcat-adapter/tomcat-adapter-samesite-setting.adoc[]
|
||||
include::topics/saml/java/jetty-adapter.adoc[]
|
||||
include::topics/saml/java/jetty-adapter/jetty9_installation.adoc[]
|
||||
include::topics/saml/java/jetty-adapter/jetty9_per_war_config.adoc[]
|
||||
endif::[]
|
||||
|
||||
include::topics/saml/java/servlet-filter-adapter.adoc[]
|
||||
include::topics/saml/java/idp-registration.adoc[]
|
||||
include::topics/saml/java/logout.adoc[]
|
||||
include::topics/saml/java/assertion-api.adoc[]
|
||||
include::topics/saml/java/error_handling.adoc[]
|
||||
include::topics/saml/java/debugging.adoc[]
|
||||
include::topics/saml/java/multi-tenancy.adoc[]
|
||||
ifeval::[{project_community}==true]
|
||||
include::topics/saml/java/MigrationFromOlderVersions.adoc[]
|
||||
endif::[]
|
||||
include::topics/saml/mod-auth-mellon.adoc[]
|
||||
endif::[]
|
||||
ifeval::[{project_product}==true]
|
||||
include::topics/saml/java/java-adapters-product.adoc[]
|
||||
endif::[]
|
||||
|
||||
include::topics/docker/docker-overview.adoc[]
|
||||
include::topics/client-registration.adoc[]
|
||||
include::topics/client-registration/client-registration-cli.adoc[]
|
||||
|
|
|
|||
|
|
@ -0,0 +1,35 @@
|
|||
=== {project_name} Java adapters
|
||||
|
||||
==== Red Hat JBoss Enterprise Application Platform
|
||||
|
||||
{project_name} does not include any adapters for Red Hat JBoss Enterprise Application Platform. However, there are
|
||||
alternatives for existing applications deployed to Red Hat JBoss Enterprise Application Platform.
|
||||
|
||||
===== 8.0 Beta
|
||||
|
||||
Red Hat Enterprise Application Platform 8.0 Beta provides a native OpenID Connect client through the Elytron OIDC client
|
||||
subsystem.
|
||||
|
||||
For more information, see the https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/8-beta/html/using_single_sign-on_with_jboss_eap/index[Red Hat JBoss Enterprise Application Platform documentation].
|
||||
|
||||
===== 6.4 and 7.x
|
||||
|
||||
Existing applications deployed to Red Hat JBoss Enterprise Application Platform 6.4 and 7.x can leverage adapters from
|
||||
Red Hat Single Sign-On 7.6 in combination with the {project_name} server.
|
||||
|
||||
For more information, see the
|
||||
https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.6/html/securing_applications_and_services_guide/oidc#jboss_adapter[Red Hat Single Sign-On documentation].
|
||||
|
||||
|
||||
==== Spring Boot adapter
|
||||
|
||||
{project_name} does not include any adapters for Spring Boot. However, there are
|
||||
alternatives for existing applications built with Spring Boot.
|
||||
|
||||
Spring Security provides comprehensive support for OAuth 2 and OpenID Connect. For more information, see the
|
||||
https://spring.io/projects/spring-security[Spring Security documentation].
|
||||
|
||||
Alternatively, for Spring Boot 2.x the Spring Boot adapter from Red Hat Single Sign-On 7.6 can be used in combination with the {project_name} server. For more information, see the
|
||||
https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.6/html/securing_applications_and_services_guide/oidc#jboss_adapter[Red Hat Single Sign-On documentation].
|
||||
|
||||
|
||||
|
|
@ -1,269 +1,15 @@
|
|||
[[_jboss_adapter]]
|
||||
|
||||
ifeval::[{project_community}==true]
|
||||
==== JBoss EAP/WildFly adapter
|
||||
endif::[]
|
||||
ifeval::[{project_product}==true]
|
||||
==== JBoss EAP adapter
|
||||
|
||||
You can install this adapter from a ZIP file or from an RPM.
|
||||
|
||||
* xref:jboss_adapter_installation[Installing JBOSS EAP adapters from a ZIP file]
|
||||
* xref:jboss7_adapter_rpm[Installing JBoss EAP 7 Adapters from an RPM]
|
||||
* xref:jboss6_adapter_rpm[Installing JBoss EAP 6 Adapters from an RPM]
|
||||
|
||||
[id="jboss_adapter_installation"]
|
||||
===== Installing JBOSS EAP adapters from a ZIP file
|
||||
endif::[]
|
||||
|
||||
ifeval::[{project_community}==true]
|
||||
|
||||
[WARNING]
|
||||
====
|
||||
This adapter is deprecated and will be removed in a future release of {project_name}. No further enhancements or new features
|
||||
will be added to this adapter.
|
||||
{project_name} provided this adapter in the past, but it is not provided anymore.
|
||||
|
||||
We recommend that you switch to the Elytron OIDC library to secure your applications.
|
||||
This library has a similar configuration to the {project_name} WildFly adapters, so you can expect a smooth migration of your applications.
|
||||
This library has a similar configuration to the {project_name} WildFly adapters, so you can expect a smooth migration of your applications
|
||||
if you used this adapter with the older {project_name} versions.
|
||||
|
||||
For more details about how to integrate {project_name} with JakartaEE applications running on latest Wildfly/EAP, consider looking at the
|
||||
{quickstartRepo_link}[Keycloak Quickstart GitHub Repository].
|
||||
====
|
||||
Elytron OIDC library works with WildFly 28 or newer versions. For the older WildFly versions or for JBoss EAP 7, it is recommended to upgrade
|
||||
to newer WildFly/EAP or look for some alternative OIDC client library. Otherwise, you will need to stick with the older {project_name} adapters, but those
|
||||
are not maintained and officially supported.
|
||||
|
||||
To be able to secure WAR apps deployed on JBoss EAP, WildFly or JBoss AS, you must install and configure the
|
||||
{project_name} adapter subsystem. You then have two options to secure your WARs.
|
||||
endif::[]
|
||||
ifeval::[{project_product}==true]
|
||||
To be able to secure WAR apps deployed on JBoss EAP, you must install and configure the
|
||||
{project_name} adapter subsystem. You then have two options to secure your WARs.
|
||||
endif::[]
|
||||
|
||||
* You can provide an adapter config file in your WAR and change the auth-method to KEYCLOAK within web.xml.
|
||||
|
||||
* Alternatively, you do not have to modify your WAR at all and you can secure it via the {project_name} adapter subsystem configuration in the configuration file, such as `standalone.xml`.
|
||||
|
||||
Both methods are described in this section.
|
||||
|
||||
Adapters are available as a separate archive depending on what server version you are using.
|
||||
|
||||
ifeval::[{project_community}==true]
|
||||
|
||||
.Procedure
|
||||
|
||||
. Install the adapter that applies to your application server from the link:https://www.keycloak.org/downloads[Downloads] site.
|
||||
|
||||
* Install on WildFly:
|
||||
+
|
||||
[source, subs="attributes"]
|
||||
----
|
||||
$ cd $WILDFLY_HOME
|
||||
$ unzip keycloak-wildfly-adapter-dist-{project_version}.zip
|
||||
----
|
||||
|
||||
* Install on JBoss EAP 7:
|
||||
+
|
||||
[source, subs="attributes"]
|
||||
----
|
||||
$ cd $EAP_HOME
|
||||
$ unzip keycloak-eap7-adapter-dist-{project_version}.zip
|
||||
----
|
||||
endif::[]
|
||||
ifeval::[{project_product}==true]
|
||||
|
||||
.Procedure
|
||||
|
||||
. Install the adapter that applies to your application server from the link:https://access.redhat.com/jbossnetwork/restricted/listSoftware.html?downloadType=distributions&product=core.service.rhsso[Software Downloads] site.
|
||||
|
||||
* Install on JBoss EAP 7:
|
||||
+
|
||||
[source, subs="attributes"]
|
||||
----
|
||||
$ cd $EAP_HOME
|
||||
$ unzip rh-sso-{project_version}-eap7-adapter.zip
|
||||
----
|
||||
endif::[]
|
||||
+
|
||||
This ZIP archive contains JBoss Modules specific to the {project_name} adapter. It also contains JBoss CLI scripts to configure the adapter subsystem.
|
||||
|
||||
. To configure the adapter subsystem, execute the appropriate command.
|
||||
ifeval::[{project_community}==true]
|
||||
* Install on WildFly if the server *is not* running
|
||||
+
|
||||
[source]
|
||||
----
|
||||
$ ./bin/jboss-cli.sh --file=bin/adapter-elytron-install-offline.cli
|
||||
----
|
||||
+
|
||||
* Install on WildFly if the server *is* running
|
||||
+
|
||||
[source]
|
||||
----
|
||||
$ ./bin/jboss-cli.sh -c --file=bin/adapter-elytron-install.cli
|
||||
----
|
||||
+
|
||||
|
||||
NOTE: Alternatively, you can specify the `server.config` property while installing adapters from the command line to install adapters using a different config, for example: `-Dserver.config=standalone-ha.xml`.
|
||||
endif::[]
|
||||
ifeval::[{project_product}==true]
|
||||
* Install on JBoss EAP 7.1 or newer if the server *is not* running.
|
||||
+
|
||||
[source]
|
||||
----
|
||||
$ ./bin/jboss-cli.sh --file=bin/adapter-elytron-install-offline.cli
|
||||
----
|
||||
+
|
||||
NOTE: The offline script is not available for JBoss EAP 6.4
|
||||
|
||||
* Install on JBoss EAP 7.1 or newer if the server *is* running.
|
||||
+
|
||||
[source]
|
||||
----
|
||||
$ ./bin/jboss-cli.sh -c --file=bin/adapter-elytron-install.cli
|
||||
----
|
||||
+
|
||||
NOTE: It is possible to use the legacy non-Elytron adapter on JBoss EAP 7.1 or newer as well, meaning you can use `adapter-install-offline.cli`
|
||||
+
|
||||
NOTE: https://access.redhat.com/articles/2026253#EAP_74[EAP supports OpenJDK 17 and Oracle JDK 17] since 7.4.CP7 and 7.4.CP8 respectively. Note that the new java version makes the elytron variant compulsory, so do not use the legacy adapter with JDK 17. Also, after running the adapter CLI file, execute the `enable-elytron-se17.cli` script provided by EAP. Both scripts are necessary to configure the elytron adapter and remove the incompatible EAP subsystems. For more details, see this https://access.redhat.com/articles/6956863[Security Configuration Changes] article.
|
||||
|
||||
* Install on JBoss EAP 6.4
|
||||
+
|
||||
[source]
|
||||
----
|
||||
$ ./bin/jboss-cli.sh -c --file=bin/adapter-install.cli
|
||||
----
|
||||
endif::[]
|
||||
|
||||
|
||||
===== JBoss SSO
|
||||
|
||||
{appserver_name} has built-in support for single sign-on for web applications deployed to the same {appserver_name}
|
||||
instance. This should not be enabled when using {project_name}.
|
||||
|
||||
===== Securing a WAR
|
||||
|
||||
This section describes how to secure a WAR directly by adding configuration and editing files within your WAR package.
|
||||
|
||||
.Procedure
|
||||
|
||||
. Create a `keycloak.json` adapter configuration file within the `WEB-INF` directory of your WAR.
|
||||
+
|
||||
The format of this configuration file is described in the <<_java_adapter_config,Java adapter configuration>> section.
|
||||
. Set the `auth-method` to `KEYCLOAK` in `web.xml`.
|
||||
|
||||
. Use standard servlet security to specify role-base constraints on your URLs.
|
||||
+
|
||||
Here's an example:
|
||||
+
|
||||
[source,xml]
|
||||
----
|
||||
|
||||
<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>application</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>
|
||||
<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>
|
||||
----
|
||||
|
||||
===== Securing WARs via adapter subsystem
|
||||
|
||||
You do not have to modify your WAR to secure it with {project_name}. Instead you can externally secure it via the {project_name} Adapter Subsystem.
|
||||
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.
|
||||
The metadata is instead defined within server configuration (`standalone.xml`) in the {project_name} subsystem definition.
|
||||
|
||||
[source,xml,subs="attributes+"]
|
||||
----
|
||||
<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>
|
||||
<auth-server-url>http://localhost:8081{kc_base_path}</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.
|
||||
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 <<_java_adapter_config,Java adapter configuration>>.
|
||||
|
||||
The exception is the `credential` element.
|
||||
|
||||
To simplify this change, log into the Admin Console and go to the Client details of the application this WAR is aligned with. Then, from the _Action_ menu, select the *Download adapter config* option.
|
||||
It provides an example XML file you can cut and paste.
|
||||
|
||||
If you have multiple deployments secured by the same realm you can share the realm configuration in a separate element. For example:
|
||||
|
||||
[source,xml,subs="attributes+"]
|
||||
----
|
||||
<subsystem xmlns="urn:jboss:domain:keycloak:1.1">
|
||||
<realm name="demo">
|
||||
<auth-server-url>http://localhost:8080{kc_base_path}</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>
|
||||
----
|
||||
|
||||
===== Security domain
|
||||
|
||||
The security context is propagated to the EJB tier automatically.
|
||||
For more details on how to integrate {project_name} with JakartaEE applications running on latest Wildfly/EAP, take a look at the Jakarta EE quickstarts within the {quickstartRepo_link}[Keycloak Quickstart GitHub Repository].
|
||||
|
|
|
|||
|
|
@ -0,0 +1,19 @@
|
|||
|
||||
=== {project_name} Java adapters
|
||||
|
||||
{project_name} comes with a range of different adapters for Java application. Selecting the correct adapter depends on the target platform.
|
||||
|
||||
==== Red Hat JBoss Enterprise Application Platform
|
||||
|
||||
===== 8.0 Beta
|
||||
|
||||
{project_name} provides a SAML adapter for Red Hat Enterprise Application Platform 8.0 Beta. However, the documentation
|
||||
is not currently available, and will be added in the near future.
|
||||
|
||||
===== 6.4 and 7.x
|
||||
|
||||
Existing applications deployed to Red Hat JBoss Enterprise Application Platform 6.4 and 7.x can leverage adapters from
|
||||
Red Hat Single Sign-On 7.6 in combination with the {project_name} server.
|
||||
|
||||
For more information, see the
|
||||
https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.6/html/securing_applications_and_services_guide/using_saml_to_secure_applications_and_services#saml_jboss_adapter[Red Hat Single Sign-On documentation].
|
||||
|
|
@ -2,3 +2,43 @@
|
|||
=== {project_name} Java adapters
|
||||
|
||||
{project_name} comes with a range of different adapters for Java application. Selecting the correct adapter depends on the target platform.
|
||||
|
||||
include::general-config.adoc[]
|
||||
include::general-config/sp_element.adoc[]
|
||||
include::general-config/sp-keys.adoc[]
|
||||
include::general-config/sp-keys/keystore_element.adoc[]
|
||||
include::general-config/sp-keys/key_pems.adoc[]
|
||||
include::general-config/sp_principalname_mapping_element.adoc[]
|
||||
include::general-config/roleidentifiers_element.adoc[]
|
||||
include::general-config/sp_role_mappings_provider_element.adoc[]
|
||||
include::general-config/idp_element.adoc[]
|
||||
include::general-config/idp_allowedclockskew_subelement.adoc[]
|
||||
include::general-config/idp_singlesignonservice_subelement.adoc[]
|
||||
include::general-config/idp_singlelogoutservice_subelement.adoc[]
|
||||
include::general-config/idp_keys_subelement.adoc[]
|
||||
include::general-config/idp_httpclient_subelement.adoc[]
|
||||
include::saml-jboss-adapter.adoc[]
|
||||
include::jboss-adapter/jboss_adapter_installation.adoc[]
|
||||
include::jboss-adapter/jboss-adapter-samesite-setting.adoc[]
|
||||
include::jboss-adapter/required_per_war_configuration.adoc[]
|
||||
include::jboss-adapter/securing_wars.adoc[]
|
||||
ifeval::[{project_community}==true]
|
||||
include::tomcat-adapter.adoc[]
|
||||
include::tomcat-adapter/tomcat_adapter_installation.adoc[]
|
||||
include::tomcat-adapter/tomcat_adapter_per_war_config.adoc[]
|
||||
include::tomcat-adapter/tomcat-adapter-samesite-setting.adoc[]
|
||||
include::jetty-adapter.adoc[]
|
||||
include::jetty-adapter/jetty9_installation.adoc[]
|
||||
include::jetty-adapter/jetty9_per_war_config.adoc[]
|
||||
endif::[]
|
||||
|
||||
include::servlet-filter-adapter.adoc[]
|
||||
include::idp-registration.adoc[]
|
||||
include::logout.adoc[]
|
||||
include::assertion-api.adoc[]
|
||||
include::error_handling.adoc[]
|
||||
include::debugging.adoc[]
|
||||
include::multi-tenancy.adoc[]
|
||||
ifeval::[{project_community}==true]
|
||||
include::MigrationFromOlderVersions.adoc[]
|
||||
endif::[]
|
||||
|
|
@ -1,95 +0,0 @@
|
|||
[[_jboss7_adapter_rpm_saml]]
|
||||
==== Installing JBoss EAP 7 Adapters from an RPM
|
||||
|
||||
NOTE: With Red Hat Enterprise Linux 7, the term channel was replaced with the term repository. In these instructions only the term repository is used.
|
||||
|
||||
.Prerequisites
|
||||
|
||||
You must subscribe to the JBoss EAP 7 repository before you can install the EAP 7 adapters from an RPM.
|
||||
|
||||
* Ensure that your Red Hat Enterprise Linux system is registered to your account using Red Hat Subscription Manager. For more information see the link:https://access.redhat.com/documentation/en-us/red_hat_subscription_management/2022[Red Hat Subscription Management documentation].
|
||||
|
||||
* If you are already subscribed to another JBoss EAP repository, you must unsubscribe from that repository first.
|
||||
+
|
||||
For Red Hat Enterprise Linux 6, 7: Using Red Hat Subscription Manager, subscribe to the {appserver_name} {appserver_version} repository using the following command. Replace <RHEL_VERSION> with either 6 or 7 depending on your Red Hat Enterprise Linux version.
|
||||
+
|
||||
[source,bash,subs="attributes+"]
|
||||
----
|
||||
$ sudo subscription-manager repos --enable=jb-eap-7-for-rhel-<RHEL_VERSION>-server-rpms
|
||||
----
|
||||
+
|
||||
For Red Hat Enterprise Linux 8: Using Red Hat Subscription Manager, subscribe to the {appserver_name} {appserver_version} repository using the following command:
|
||||
+
|
||||
[source,bash,subs="attributes+"]
|
||||
----
|
||||
$ sudo subscription-manager repos --enable=jb-eap-{appserver_version}-for-rhel-8-x86_64-rpms --enable=rhel-8-for-x86_64-baseos-rpms --enable=rhel-8-for-x86_64-appstream-rpms
|
||||
----
|
||||
|
||||
.Procedure
|
||||
|
||||
. Install the EAP 7 adapters for SAML based on your version of Red Hat Enterprise Linux.
|
||||
|
||||
* Install on Red Hat Linux 7:
|
||||
+
|
||||
[source,bash,subs="attributes+"]
|
||||
----
|
||||
$ sudo yum install eap7-keycloak-saml-adapter-sso7_6
|
||||
----
|
||||
|
||||
* Install on Red Hat Enterprise Linux 8:
|
||||
+
|
||||
[source,bash,subs="attributes+"]
|
||||
----
|
||||
$ sudo dnf install eap7-keycloak-adapter-sso7_6
|
||||
----
|
||||
+
|
||||
NOTE: The default EAP_HOME path for the RPM installation is /opt/rh/eap7/root/usr/share/wildfly.
|
||||
|
||||
. Run the installation script for the SAML module:
|
||||
+
|
||||
[source,bash,subs="attributes+"]
|
||||
----
|
||||
$ $EAP_HOME/bin/jboss-cli.sh -c --file=$EAP_HOME/bin/adapter-install-saml.cli
|
||||
----
|
||||
|
||||
Your installation is complete.
|
||||
|
||||
[[_jboss6_adapter_rpm_saml]]
|
||||
==== Installing JBoss EAP 6 Adapters from an RPM
|
||||
|
||||
NOTE: With Red Hat Enterprise Linux 7, the term channel was replaced with the term repository. In these instructions only the term repository is used.
|
||||
|
||||
.Prerequisites
|
||||
|
||||
You must subscribe to the JBoss EAP 6 repository before you can install the EAP 6 adapters from an RPM.
|
||||
|
||||
* Ensure that your Red Hat Enterprise Linux system is registered to your account using Red Hat Subscription Manager. For more information see the link:https://access.redhat.com/documentation/en-us/red_hat_subscription_management/2022[Red Hat Subscription Management documentation].
|
||||
|
||||
* If you are already subscribed to another JBoss EAP repository, you must unsubscribe from that repository first.
|
||||
|
||||
* Using Red Hat Subscription Manager, subscribe to the JBoss EAP 6 repository using the following command. Replace <RHEL_VERSION> with either 6 or 7 depending on your Red Hat Enterprise Linux version.
|
||||
+
|
||||
[source,bash,subs="attributes+"]
|
||||
----
|
||||
$ sudo subscription-manager repos --enable=jb-eap-6-for-rhel-<RHEL_VERSION>-server-rpms
|
||||
----
|
||||
|
||||
.Procedure
|
||||
|
||||
. Install the EAP 6 adapters for SAML using the following command:
|
||||
+
|
||||
[source,bash,subs="attributes+"]
|
||||
----
|
||||
$ sudo yum install keycloak-saml-adapter-sso7_6-eap6
|
||||
----
|
||||
+
|
||||
NOTE: The default EAP_HOME path for the RPM installation is /opt/rh/eap6/root/usr/share/wildfly.
|
||||
|
||||
. Run the installation script for the SAML module:
|
||||
+
|
||||
[source,bash,subs="attributes+"]
|
||||
----
|
||||
$ $EAP_HOME/bin/jboss-cli.sh -c --file=$EAP_HOME/bin/adapter-install-saml.cli
|
||||
----
|
||||
|
||||
Your installation is complete.
|
||||
|
|
@ -1,130 +1,15 @@
|
|||
|
||||
[[_saml-jboss-adapter-installation]]
|
||||
==== Installing adapters from a ZIP file
|
||||
==== Installing adapters from a Galleon feature pack
|
||||
|
||||
Each adapter is a separate download on the {project_name} download site.
|
||||
For the WildFly 29 or newer, the SAML adapter is provided as a Galleon feature pack. More details about this is
|
||||
in the https://docs.wildfly.org/30/WildFly_Elytron_Security.html#Keycloak_SAML_Integration[WildFly documentation]. The same option will be provided
|
||||
for JBoss EAP 8 GA.
|
||||
|
||||
ifeval::[{project_community}==true]
|
||||
{project_name} provided adapter ZIP download in the past, but it is not provided anymore. For the older WildFly versions, it is recommended to upgrade
|
||||
to newer WildFly/EAP and use Galleon. Otherwise, you will need to stick with the older {project_name} adapters, but those are not maintained and officially supported.
|
||||
For JBoss EAP 7, it is possible to stick with the Red Hat Single Sign-On 7.6 adapters, which is still supported.
|
||||
|
||||
NOTE: We only test and maintain adapter with the most recent version of WildFly available upon the release. Once the new version of WildFly is released, the current adapters become deprecated and support for them will be removed after the next WildFly release.
|
||||
The other alternative is to switch your applications from WildFly to the JBoss EAP, as the JBoss EAP adapter is supported for a much longer period.
|
||||
For more details on how to integrate {project_name} with JakartaEE applications running on latest Wildfly/EAP, take a look at the Jakarta EE quickstart in the {quickstartRepo_link}[Keycloak Quickstart GitHub Repository].
|
||||
|
||||
.Procedure
|
||||
|
||||
. Install the adapter that applies to your application server from the link:https://www.keycloak.org/downloads[Downloads] site.
|
||||
|
||||
* Install on WildFly or on JBoss EAP 7:
|
||||
+
|
||||
[source]
|
||||
----
|
||||
$ cd $WILDFLY_HOME
|
||||
$ unzip keycloak-saml-wildfly-adapter-dist.zip
|
||||
----
|
||||
+
|
||||
These zip files create new JBoss Modules specific to the WildFly/JBoss EAP SAML Adapter within your WildFly or JBoss EAP distro.
|
||||
endif::[]
|
||||
ifeval::[{project_product}==true]
|
||||
.Procedure
|
||||
|
||||
. Install the adapter that applies to your application server from the link:https://access.redhat.com/jbossnetwork/restricted/listSoftware.html?downloadType=distributions&product=core.service.rhsso[Downloads] site.
|
||||
|
||||
* Install on JBoss EAP 7.x:
|
||||
+
|
||||
[source]
|
||||
----
|
||||
$ cd $EAP_HOME
|
||||
$ unzip rh-sso-saml-eap7-adapter.zip
|
||||
----
|
||||
|
||||
* Install on JBoss EAP 6.x:
|
||||
+
|
||||
[source]
|
||||
+
|
||||
----
|
||||
$ cd $EAP_HOME
|
||||
$ unzip rh-sso-saml-eap6-adapter.zip
|
||||
----
|
||||
+
|
||||
These ZIP files create new JBoss Modules specific to the JBoss EAP SAML Adapter within your JBoss EAP distribution.
|
||||
endif::[]
|
||||
|
||||
. Use a CLI script to enable the {project_name} SAML Subsystem within your app server's server configuration: `domain.xml` or `standalone.xml`.
|
||||
+
|
||||
Start the server and run the script that applies to your application server.
|
||||
ifeval::[{project_community}==true]
|
||||
|
||||
* Install on WildFly.
|
||||
+
|
||||
[source]
|
||||
----
|
||||
$ cd $JBOSS_HOME
|
||||
$ ./bin/jboss-cli.sh -c --file=bin/adapter-elytron-install-saml.cli
|
||||
----
|
||||
|
||||
endif::[]
|
||||
ifeval::[{project_product}==true]
|
||||
* Use this command for JBoss EAP 7.1 or newer
|
||||
+
|
||||
[source]
|
||||
----
|
||||
$ cd $JBOSS_HOME
|
||||
$ ./bin/jboss-cli.sh -c --file=bin/adapter-elytron-install-saml.cli
|
||||
----
|
||||
+
|
||||
NOTE: https://access.redhat.com/articles/2026253#EAP_74[EAP supports OpenJDK 17 and Oracle JDK 17] since 7.4.CP7 and 7.4.CP8 respectively. Note that the new java version makes the elytron variant compulsory, so do not use the legacy adapter with JDK 17. Also, after running the adapter CLI file, execute the `enable-elytron-se17.cli` script provided by EAP. Both scripts are necessary to configure the elytron adapter and remove the incompatible EAP subsystems. For more details, see this https://access.redhat.com/articles/6956863[Security Configuration Changes] article.
|
||||
|
||||
* Use this command for JBoss EAP 7.0 and EAP 6.4
|
||||
+
|
||||
[source]
|
||||
----
|
||||
$ cd $JBOSS_HOME
|
||||
$ ./bin/jboss-cli.sh -c --file=bin/adapter-install-saml.cli
|
||||
----
|
||||
+
|
||||
NOTE: It is possible to use the legacy non-Elytron adapter on JBoss EAP 7.1 or newer as well, meaning you can use `adapter-install-saml.cli`
|
||||
even on those versions. However, we recommend to use the newer Elytron adapter.
|
||||
+
|
||||
endif::[]
|
||||
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>
|
||||
----
|
||||
|
||||
The security context is propagated to the EJB tier automatically.
|
||||
|
||||
===== JBoss SSO
|
||||
|
||||
{appserver_name} has built-in support for single sign-on for web applications deployed to the same {appserver_name}
|
||||
instance. This should not be enabled when using {project_name}.
|
||||
Below are the details on how to configure the SAML adapter secured by Galleon.
|
||||
|
|
|
|||
Loading…
Reference in a new issue