diff --git a/docs/documentation/release_notes/topics/11_0_0.adoc b/docs/documentation/release_notes/topics/11_0_0.adoc index 576d935219..a309c6c1df 100644 --- a/docs/documentation/release_notes/topics/11_0_0.adoc +++ b/docs/documentation/release_notes/topics/11_0_0.adoc @@ -26,7 +26,7 @@ please take a look at link:{upgradingguide_link_latest}[{upgradingguide_name}]. The `SameSite` value `None` for `JSESSIONID` cookie is necessary for correct behavior of the {project_name} SAML adapter. Usage of a different value is causing resetting of the container's session with each request to {project_name}, when the SAML POST binging is used. Refer to the following steps for -link:{adapterguide_link}#_saml-jboss-adapter-samesite-setting[Wildfly] to keep the correct behavior. Notice, that this +link:https://www.keycloak.org/guides#securing-apps[Keycloak SAML Galleon feature pack for WildFly and EAP] guide to keep the correct behavior. Notice, that this workaround should be working also with the previous versions of the adapter. == Other improvements @@ -36,4 +36,4 @@ workaround should be working also with the previous versions of the adapter. * Czech translation. Thanks to https://github.com/jakubknejzlik[Jakub Knejzlík] * Possibility to fetch additional fields from the Facebook identity provider. Thanks to https://github.com/BartoszSiemienczuk[Bartosz Siemieńczuk] * Support for AES 192 and AES 256 algorithms used for signed and encrypted ID tokens. Thanks to https://github.com/tnorimat[Takashi Norimatsu] -* Ability to specify signature algorithm in Signed JWT Client Authentication. Thanks to https://github.com/tnorimat[Takashi Norimatsu] \ No newline at end of file +* Ability to specify signature algorithm in Signed JWT Client Authentication. Thanks to https://github.com/tnorimat[Takashi Norimatsu] diff --git a/docs/documentation/securing_apps/topics.adoc b/docs/documentation/securing_apps/topics.adoc index 0c887d43fd..9557725b86 100644 --- a/docs/documentation/securing_apps/topics.adoc +++ b/docs/documentation/securing_apps/topics.adoc @@ -37,7 +37,6 @@ 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/mod-auth-mellon.adoc[] endif::[] ifeval::[{project_product}==true] diff --git a/docs/documentation/securing_apps/topics/overview/getting-started.adoc b/docs/documentation/securing_apps/topics/overview/getting-started.adoc index cc7dd1c913..bcafd17376 100644 --- a/docs/documentation/securing_apps/topics/overview/getting-started.adoc +++ b/docs/documentation/securing_apps/topics/overview/getting-started.adoc @@ -39,17 +39,3 @@ ifeval::[{project_community}==true] * https://github.com/OpenIDC/mod_auth_openidc[mod_auth_openidc] endif::[] -==== SAML - -===== Java - -* <<_saml_jboss_adapter,JBoss EAP>> -ifeval::[{project_community}==true] -* <<_saml_jboss_adapter,WildFly>> -endif::[] - -ifeval::[{project_community}==true] -===== Apache HTTP Server - -* <<_mod_auth_mellon,mod_auth_mellon>> -endif::[] \ No newline at end of file diff --git a/docs/documentation/securing_apps/topics/saml/java/MigrationFromOlderVersions.adoc b/docs/documentation/securing_apps/topics/saml/java/MigrationFromOlderVersions.adoc deleted file mode 100644 index 05cbfe216f..0000000000 --- a/docs/documentation/securing_apps/topics/saml/java/MigrationFromOlderVersions.adoc +++ /dev/null @@ -1,11 +0,0 @@ -==== Migration from older versions - -===== Migrating to 1.9.0 - -====== SAML SP Client Adapter changes - -Keycloak SAML SP Client Adapter now requires a specific endpoint, `/saml` to be registered with your IdP. -The SamlFilter must also be bound to /saml in addition to any other binding it has. -This had to be done because SAML POST binding would eat the request input stream and this would be really bad for clients that relied on it. - - diff --git a/docs/documentation/securing_apps/topics/saml/java/java-adapters-product.adoc b/docs/documentation/securing_apps/topics/saml/java/java-adapters-product.adoc deleted file mode 100644 index b92b740827..0000000000 --- a/docs/documentation/securing_apps/topics/saml/java/java-adapters-product.adoc +++ /dev/null @@ -1,20 +0,0 @@ - -=== {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. - -[[_saml_jboss_adapter]] -==== 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]. diff --git a/docs/documentation/securing_apps/topics/saml/java/java-adapters.adoc b/docs/documentation/securing_apps/topics/saml/java/java-adapters.adoc deleted file mode 100644 index b61c370098..0000000000 --- a/docs/documentation/securing_apps/topics/saml/java/java-adapters.adoc +++ /dev/null @@ -1,36 +0,0 @@ - -=== {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] -endif::[] - -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::[] \ No newline at end of file diff --git a/docs/documentation/securing_apps/topics/saml/java/jboss-adapter/jboss_adapter_installation.adoc b/docs/documentation/securing_apps/topics/saml/java/jboss-adapter/jboss_adapter_installation.adoc deleted file mode 100644 index 7ef6b3b33b..0000000000 --- a/docs/documentation/securing_apps/topics/saml/java/jboss-adapter/jboss_adapter_installation.adoc +++ /dev/null @@ -1,15 +0,0 @@ - -[[_saml-jboss-adapter-installation]] -==== Installing adapters from a Galleon feature pack - -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. - -{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. - -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]. - -Below are the details on how to configure the SAML adapter secured by Galleon. diff --git a/docs/documentation/securing_apps/topics/saml/java/saml-jboss-adapter.adoc b/docs/documentation/securing_apps/topics/saml/java/saml-jboss-adapter.adoc deleted file mode 100644 index 4fc0ca7743..0000000000 --- a/docs/documentation/securing_apps/topics/saml/java/saml-jboss-adapter.adoc +++ /dev/null @@ -1,26 +0,0 @@ -[[_saml_jboss_adapter]] - -ifeval::[{project_community}==true] -==== JBoss EAP/WildFly adapter -endif::[] -ifeval::[{project_product}==true] -==== JBoss EAP adapter -endif::[] - -ifeval::[{project_community}==true] -To be able to secure WAR apps deployed on JBoss EAP or WildFly, you must install and configure the {project_name} SAML Adapter Subsystem. -endif::[] -ifeval::[{project_product}==true] -To be able to secure WAR apps deployed on JBoss EAP, you must install and configure the {project_name} SAML Adapter Subsystem. -endif::[] - -You then provide a keycloak config, `/WEB-INF/keycloak-saml.xml` file in your WAR and change the auth-method to KEYCLOAK-SAML within web.xml. - -ifeval::[{project_product}==true] -You install the adapters by using a ZIP file or an RPM. - -* <<_saml-jboss-adapter-installation, Installing adapters from a ZIP file>> -* <<_jboss7_adapter_rpm_saml, Installing JBoss EAP 7 Adapters from an RPM>> -* <<_jboss6_adapter_rpm_saml, Installing JBoss EAP 6 Adapters from an RPM>> -endif::[] - diff --git a/docs/documentation/securing_apps/topics/saml/java/saml_adapter_overview.adoc b/docs/documentation/securing_apps/topics/saml/java/saml_adapter_overview.adoc deleted file mode 100644 index 7cb0677496..0000000000 --- a/docs/documentation/securing_apps/topics/saml/java/saml_adapter_overview.adoc +++ /dev/null @@ -1,6 +0,0 @@ -= Overview - -This document describes the Keycloak SAML client adapter and how it can be configured for a variety of platforms. -The Keycloak SAML client adapter is a standalone component that provides generic SAML 2.0 support for your web applications. -There are no Keycloak server extensions built into it. -As long as the Identity Provider (IdP) being communicated with supports standard SAML, the Keycloak SAML client adapter should be able to integrate with it. diff --git a/docs/guides/assembly.xml b/docs/guides/assembly.xml index c359c21416..1514e55031 100644 --- a/docs/guides/assembly.xml +++ b/docs/guides/assembly.xml @@ -40,5 +40,12 @@ pinned-guides + + ${project.basedir}/securing-apps + /generated-guides/securing-apps/ + + pinned-guides + + diff --git a/docs/guides/pom.xml b/docs/guides/pom.xml index a8b6d203ed..60f5249f5c 100644 --- a/docs/guides/pom.xml +++ b/docs/guides/pom.xml @@ -201,6 +201,18 @@ ${project.build.directory}/generated-docs/high-availability + + securing-apps-asciidoc-to-html + generate-resources + + process-asciidoc + + + ${basedir}/target/generated-guides/securing-apps + ${project.build.directory}/generated-docs/securing-apps + true + + @@ -223,4 +235,4 @@ - \ No newline at end of file + diff --git a/docs/guides/securing-apps/apisix.adoc b/docs/guides/securing-apps/apisix.adoc new file mode 100644 index 0000000000..b2965ba760 --- /dev/null +++ b/docs/guides/securing-apps/apisix.adoc @@ -0,0 +1,3 @@ +:guide-title: Apache APISIX +:guide-summary: Integrate Keycloak for Authentication with Apache APISIX +:external-link: https://apisix.apache.org/blog/2021/12/10/integrate-keycloak-auth-in-apisix \ No newline at end of file diff --git a/docs/guides/securing-apps/index.adoc b/docs/guides/securing-apps/index.adoc new file mode 100644 index 0000000000..3858f2c149 --- /dev/null +++ b/docs/guides/securing-apps/index.adoc @@ -0,0 +1,12 @@ += Securing applications + +include::../attributes.adoc[] + +<#list ctx.guides as guide> +:links_securing-apps_${guide.id}_name: ${guide.title} +:links_securing-apps_${guide.id}_url: #${guide.id} + + +<#list ctx.guides as guide> +include::${guide.template}[leveloffset=+1] + diff --git a/docs/guides/securing-apps/krakend.adoc b/docs/guides/securing-apps/krakend.adoc new file mode 100644 index 0000000000..edb4407afa --- /dev/null +++ b/docs/guides/securing-apps/krakend.adoc @@ -0,0 +1,3 @@ +:guide-title: KrakenD +:guide-summary: Secure APIs with an API Gateway +:external-link: https://www.krakend.io/docs/authorization/keycloak/ \ No newline at end of file diff --git a/docs/documentation/securing_apps/topics/saml/java/assertion-api.adoc b/docs/guides/securing-apps/partials/saml/assertion-api.adoc similarity index 98% rename from docs/documentation/securing_apps/topics/saml/java/assertion-api.adoc rename to docs/guides/securing-apps/partials/saml/assertion-api.adoc index cd1457ae0e..1534a8e56f 100644 --- a/docs/documentation/securing_apps/topics/saml/java/assertion-api.adoc +++ b/docs/guides/securing-apps/partials/saml/assertion-api.adoc @@ -1,5 +1,5 @@ -==== Obtaining assertion attributes +== Obtaining assertion attributes After a successful SAML login, your application code may want to obtain attribute values passed with the SAML assertion. `HttpServletRequest.getUserPrincipal()` returns a `Principal` object that you can typecast into a {project_name} specific class diff --git a/docs/documentation/securing_apps/topics/saml/java/debugging.adoc b/docs/guides/securing-apps/partials/saml/debugging.adoc similarity index 94% rename from docs/documentation/securing_apps/topics/saml/java/debugging.adoc rename to docs/guides/securing-apps/partials/saml/debugging.adoc index d6de7c5c1f..cc09810a1e 100644 --- a/docs/documentation/securing_apps/topics/saml/java/debugging.adoc +++ b/docs/guides/securing-apps/partials/saml/debugging.adoc @@ -1,4 +1,4 @@ -==== Troubleshooting +== Troubleshooting The best way to troubleshoot problems is to turn on debugging for SAML in both the client adapter and {project_name} Server. Using your logging framework, set the log level to `DEBUG` for the `org.keycloak.saml` package. Turning this on allows you to see the SAML requests and response documents being sent to and from the server. diff --git a/docs/documentation/securing_apps/topics/saml/java/error_handling.adoc b/docs/guides/securing-apps/partials/saml/error_handling.adoc similarity index 98% rename from docs/documentation/securing_apps/topics/saml/java/error_handling.adoc rename to docs/guides/securing-apps/partials/saml/error_handling.adoc index e4220b6d65..9d014615ec 100644 --- a/docs/documentation/securing_apps/topics/saml/java/error_handling.adoc +++ b/docs/guides/securing-apps/partials/saml/error_handling.adoc @@ -1,5 +1,5 @@ -==== Error Handling +== Error Handling {project_name} has some error handling facilities for servlet based client adapters. When an error is encountered in authentication, the client adapter will call `HttpServletResponse.sendError()`. diff --git a/docs/documentation/securing_apps/topics/saml/java/general-config.adoc b/docs/guides/securing-apps/partials/saml/general-config.adoc similarity index 78% rename from docs/documentation/securing_apps/topics/saml/java/general-config.adoc rename to docs/guides/securing-apps/partials/saml/general-config.adoc index bed98f929f..359ccd0ec4 100644 --- a/docs/documentation/securing_apps/topics/saml/java/general-config.adoc +++ b/docs/guides/securing-apps/partials/saml/general-config.adoc @@ -1,9 +1,8 @@ [[_saml-general-config]] -==== General Adapter Config +== Configuration -Each SAML client adapter supported by {project_name} can be configured by a simple XML text file. -This is what one might look like: +The SAML client adapter is configured by a XML file `/WEB-INF/keycloak-saml.xml` placed inside the WAR deployment. The configuration might look like the following: [source,xml,subs="attributes+"] ---- @@ -57,8 +56,9 @@ This is what one might look like: ---- -Some of these configuration switches may be adapter specific and some are common across all adapters. -For Java adapters you can use `${...}` enclosure as System property replacement. -For example `${jboss.server.config.dir}`. - +You can use `${r"${...}"}` enclosure as System property replacement. For example `${r"${jboss.server.config.dir}"}`. +To get detailed information of the different elements in the XML configuration file see <@links.securingapps id="saml-galleon-layers-detailed-config"/>. +include::partials/saml/required_per_war_configuration.adoc[] +include::partials/saml/securing_wars.adoc[] +include::partials/saml/jboss-adapter-samesite-setting.adoc[] diff --git a/docs/documentation/securing_apps/topics/saml/java/idp-registration.adoc b/docs/guides/securing-apps/partials/saml/idp-registration.adoc similarity index 85% rename from docs/documentation/securing_apps/topics/saml/java/idp-registration.adoc rename to docs/guides/securing-apps/partials/saml/idp-registration.adoc index 452850b69a..34d992d13e 100644 --- a/docs/documentation/securing_apps/topics/saml/java/idp-registration.adoc +++ b/docs/guides/securing-apps/partials/saml/idp-registration.adoc @@ -1,5 +1,5 @@ -==== Registering with an Identity Provider +== Registering with an Identity Provider For each servlet-based adapter, the endpoint you register for the assert consumer service URL and single logout service must be the base URL of your servlet application with `/saml` appended to it, that is, `$$https://example.com/contextPath/saml$$`. diff --git a/docs/documentation/securing_apps/topics/saml/java/general-config/idp_allowedclockskew_subelement.adoc b/docs/guides/securing-apps/partials/saml/idp_allowedclockskew_subelement.adoc similarity index 92% rename from docs/documentation/securing_apps/topics/saml/java/general-config/idp_allowedclockskew_subelement.adoc rename to docs/guides/securing-apps/partials/saml/idp_allowedclockskew_subelement.adoc index 25c03ca2eb..b1ee5e15b9 100644 --- a/docs/documentation/securing_apps/topics/saml/java/general-config/idp_allowedclockskew_subelement.adoc +++ b/docs/guides/securing-apps/partials/saml/idp_allowedclockskew_subelement.adoc @@ -1,6 +1,6 @@ [[_sp-idp-allowedclockskew]] -===== IDP AllowedClockSkew sub element +== IDP AllowedClockSkew sub element The `AllowedClockSkew` optional sub element defines the allowed clock skew between IDP and SP. The default value is 0. diff --git a/docs/documentation/securing_apps/topics/saml/java/general-config/idp_element.adoc b/docs/guides/securing-apps/partials/saml/idp_element.adoc similarity index 99% rename from docs/documentation/securing_apps/topics/saml/java/general-config/idp_element.adoc rename to docs/guides/securing-apps/partials/saml/idp_element.adoc index b264dcbaba..b13a9b5684 100644 --- a/docs/documentation/securing_apps/topics/saml/java/general-config/idp_element.adoc +++ b/docs/guides/securing-apps/partials/saml/idp_element.adoc @@ -1,5 +1,5 @@ -===== IDP Element +== IDP Element Everything in the IDP element describes the settings for the identity provider (authentication server) the SP is communicating with. diff --git a/docs/documentation/securing_apps/topics/saml/java/general-config/idp_httpclient_subelement.adoc b/docs/guides/securing-apps/partials/saml/idp_httpclient_subelement.adoc similarity index 99% rename from docs/documentation/securing_apps/topics/saml/java/general-config/idp_httpclient_subelement.adoc rename to docs/guides/securing-apps/partials/saml/idp_httpclient_subelement.adoc index 120dd510a1..42d36f379a 100644 --- a/docs/documentation/securing_apps/topics/saml/java/general-config/idp_httpclient_subelement.adoc +++ b/docs/guides/securing-apps/partials/saml/idp_httpclient_subelement.adoc @@ -1,6 +1,6 @@ [[_sp-idp-httpclient]] -===== IDP HttpClient sub element +== IDP HttpClient sub element The `HttpClient` optional sub element defines the properties of HTTP client used for automatic obtaining of certificates containing public keys for IDP signature diff --git a/docs/documentation/securing_apps/topics/saml/java/general-config/idp_keys_subelement.adoc b/docs/guides/securing-apps/partials/saml/idp_keys_subelement.adoc similarity index 98% rename from docs/documentation/securing_apps/topics/saml/java/general-config/idp_keys_subelement.adoc rename to docs/guides/securing-apps/partials/saml/idp_keys_subelement.adoc index af36c64d09..0f17c91e19 100644 --- a/docs/documentation/securing_apps/topics/saml/java/general-config/idp_keys_subelement.adoc +++ b/docs/guides/securing-apps/partials/saml/idp_keys_subelement.adoc @@ -1,6 +1,6 @@ [[_sp-idp-keys]] -===== IDP Keys sub element +== IDP Keys sub element The Keys sub element of IDP is only used to define the certificate or public key to use to verify documents signed by the IDP. It is defined in the same way as the <<_saml-sp-keys,SP's Keys element>>. diff --git a/docs/documentation/securing_apps/topics/saml/java/general-config/idp_singlelogoutservice_subelement.adoc b/docs/guides/securing-apps/partials/saml/idp_singlelogoutservice_subelement.adoc similarity index 98% rename from docs/documentation/securing_apps/topics/saml/java/general-config/idp_singlelogoutservice_subelement.adoc rename to docs/guides/securing-apps/partials/saml/idp_singlelogoutservice_subelement.adoc index 8636999575..435077be57 100644 --- a/docs/documentation/securing_apps/topics/saml/java/general-config/idp_singlelogoutservice_subelement.adoc +++ b/docs/guides/securing-apps/partials/saml/idp_singlelogoutservice_subelement.adoc @@ -1,5 +1,5 @@ -===== IDP SingleLogoutService sub element +== IDP SingleLogoutService sub element The `SingleLogoutService` sub element defines the logout SAML endpoint of the IDP. The client adapter will send requests to the IDP formatted via the settings within this element when it wants to log out. diff --git a/docs/documentation/securing_apps/topics/saml/java/general-config/idp_singlesignonservice_subelement.adoc b/docs/guides/securing-apps/partials/saml/idp_singlesignonservice_subelement.adoc similarity index 97% rename from docs/documentation/securing_apps/topics/saml/java/general-config/idp_singlesignonservice_subelement.adoc rename to docs/guides/securing-apps/partials/saml/idp_singlesignonservice_subelement.adoc index 2ec113575e..a637d4685d 100644 --- a/docs/documentation/securing_apps/topics/saml/java/general-config/idp_singlesignonservice_subelement.adoc +++ b/docs/guides/securing-apps/partials/saml/idp_singlesignonservice_subelement.adoc @@ -1,6 +1,6 @@ [[_sp-idp-singlesignonservice]] -===== IDP SingleSignOnService sub element +== IDP SingleSignOnService sub element The `SingleSignOnService` sub element defines the login SAML endpoint of the IDP. The client adapter will send requests diff --git a/docs/guides/securing-apps/partials/saml/installation.adoc b/docs/guides/securing-apps/partials/saml/installation.adoc new file mode 100644 index 0000000000..8f5536b022 --- /dev/null +++ b/docs/guides/securing-apps/partials/saml/installation.adoc @@ -0,0 +1,126 @@ +== Installation + +The provision of the feature pack is done using the https://docs.wildfly.org/wildfly-maven-plugin[wildfly-maven-plugin], https://docs.wildfly.org/bootablejar/[wildfly-jar-maven-plugin] or https://docs.redhat.com/en/documentation/red_hat_jboss_enterprise_application_platform/8.0/html/using_jboss_eap_on_openshift_container_platform/assembly_provisioning-a-jboss-eap-server-using-the-maven-plugin_default[eap-maven-plugin] respectively. + +=== Example of provision using wildfly maven plugin + +[source,xml,subs="attributes+"] +---- + + org.wildfly.plugins + wildfly-maven-plugin + 5.0.0.Final + + + + wildfly@maven(org.jboss.universe:community-universe)#32.0.1.Final + + + org.keycloak + keycloak-saml-adapter-galleon-pack + 25.0.2 + + + + core-server + web-server + jaxrs-server + datasources-web-server + webservices + keycloak-saml + keycloak-client-saml + keycloak-client-saml-ejb + + + + + + package + + + + +---- + +=== Example of provision using wildfly jar maven plugin + +[source,xml,subs="attributes+"] +---- + + org.wildfly.plugins + wildfly-jar-maven-plugin + 11.0.2.Final + + + + wildfly@maven(org.jboss.universe:community-universe)#32.0.1.Final + + + org.keycloak + keycloak-saml-adapter-galleon-pack + 25.0.2 + + + + core-server + web-server + jaxrs-server + datasources-web-server + webservices + keycloak-saml + keycloak-client-saml + keycloak-client-saml-ejb + + + + + + package + + + + +---- + +=== Example of provision using EAP maven plugin + +[source,xml,subs="attributes+"] +---- + + org.jboss.eap.plugins + eap-maven-plugin + 1.0.0.Final-redhat-00014 + + + + + org.jboss.eap.channels + eap-8.0 + + + + + + org.keycloak:keycloak-saml-adapter-galleon-pack + + + + core-server + web-server + jaxrs-server + datasources-web-server + webservices + keycloak-saml + keycloak-client-saml + keycloak-client-saml-ejb + + + + + + package + + + + +---- diff --git a/docs/documentation/securing_apps/topics/saml/java/jboss-adapter/jboss-adapter-samesite-setting.adoc b/docs/guides/securing-apps/partials/saml/jboss-adapter-samesite-setting.adoc similarity index 95% rename from docs/documentation/securing_apps/topics/saml/java/jboss-adapter/jboss-adapter-samesite-setting.adoc rename to docs/guides/securing-apps/partials/saml/jboss-adapter-samesite-setting.adoc index 423e8955cd..7aec1db901 100644 --- a/docs/documentation/securing_apps/topics/saml/java/jboss-adapter/jboss-adapter-samesite-setting.adoc +++ b/docs/guides/securing-apps/partials/saml/jboss-adapter-samesite-setting.adoc @@ -1,5 +1,5 @@ [[_saml-jboss-adapter-samesite-setting]] -===== Setting SameSite value for JSESSIONID cookie +=== Setting SameSite value for JSESSIONID cookie Browsers are planning to set the default value for the `SameSite` attribute for cookies to `Lax`. This setting means that cookies will be sent to applications only if the request originates in the same domain. This behavior can affect diff --git a/docs/documentation/securing_apps/topics/saml/java/logout.adoc b/docs/guides/securing-apps/partials/saml/logout.adoc similarity index 88% rename from docs/documentation/securing_apps/topics/saml/java/logout.adoc rename to docs/guides/securing-apps/partials/saml/logout.adoc index 7ba190d5b3..d2f5c3de61 100644 --- a/docs/documentation/securing_apps/topics/saml/java/logout.adoc +++ b/docs/guides/securing-apps/partials/saml/logout.adoc @@ -1,4 +1,4 @@ -==== Logout +== Logout There are multiple ways you can log out from a web application. For Jakarta EE servlet containers, you can call `HttpServletRequest.logout()`. For any other browser application, you can point @@ -6,7 +6,7 @@ the browser at any url of your web application that has a security constraint an This will log you out if you have an SSO session with your browser. [[_saml_logout_in_cluster]] -===== Logout in clustered environment +=== Logout in clustered environment Internally, the SAML adapter stores a mapping between the SAML session index, principal name (when known), and HTTP session ID. This mapping can be maintained in JBoss application server family (WildFly 10/11, EAP 6/7) across cluster for distributable @@ -15,8 +15,6 @@ applications. As a precondition, the HTTP sessions need to be distributed across To enable the functionality, add the following section to your `/WEB_INF/web.xml` file: -For EAP 7, WildFly 10/11: - [source,xml] ---- @@ -25,16 +23,6 @@ For EAP 7, WildFly 10/11: ---- -For EAP 6: - -[source,xml] ----- - - keycloak.sessionIdMapperUpdater.classes - org.keycloak.adapters.saml.jbossweb.infinispan.InfinispanSessionCacheIdMapperUpdater - ----- - If the session cache of the deployment is named `_deployment-cache_`, the cache used for SAML mapping will be named as `_deployment-cache_.ssoCache`. The name of the cache can be overridden by a context parameter `keycloak.sessionIdMapperUpdater.infinispan.cacheName`. The cache container containing the cache will be the same as @@ -49,9 +37,7 @@ Using distributed cache may lead to results where the SAML logout request would to SAML session index to HTTP session mapping which would lead to unsuccessful logout. [[_saml_logout_in_cross_dc]] -===== Logout in cross-site scenario - -The cross-site scenario only applies to WildFly 10 and higher, and EAP 7 and higher. +=== Logout in cross-site scenario Special handling is needed for handling sessions that span multiple data centers. Imagine the following scenario: diff --git a/docs/documentation/securing_apps/topics/saml/java/multi-tenancy.adoc b/docs/guides/securing-apps/partials/saml/multi-tenancy.adoc similarity index 99% rename from docs/documentation/securing_apps/topics/saml/java/multi-tenancy.adoc rename to docs/guides/securing-apps/partials/saml/multi-tenancy.adoc index ac72b6a4fb..18d19d33d4 100644 --- a/docs/documentation/securing_apps/topics/saml/java/multi-tenancy.adoc +++ b/docs/guides/securing-apps/partials/saml/multi-tenancy.adoc @@ -1,5 +1,5 @@ [[_saml_multi_tenancy]] -==== Multi Tenancy +== Multi Tenancy SAML offers Multi Tenancy, meaning that a single target application (WAR) can be secured with multiple {project_name} realms. The realms can be located on the same {project_name} instance or on different instances. diff --git a/docs/documentation/securing_apps/topics/saml/java/jboss-adapter/required_per_war_configuration.adoc b/docs/guides/securing-apps/partials/saml/required_per_war_configuration.adoc similarity index 85% rename from docs/documentation/securing_apps/topics/saml/java/jboss-adapter/required_per_war_configuration.adoc rename to docs/guides/securing-apps/partials/saml/required_per_war_configuration.adoc index 6ce8063d66..de1668a082 100644 --- a/docs/documentation/securing_apps/topics/saml/java/jboss-adapter/required_per_war_configuration.adoc +++ b/docs/guides/securing-apps/partials/saml/required_per_war_configuration.adoc @@ -1,12 +1,9 @@ -===== Securing a WAR +=== Securing a WAR 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-saml.xml` adapter config file within the `WEB-INF` directory of your WAR. -The format of this config file is described in the <<_saml-general-config,General Adapter Config>> section. - -Next you must set the `auth-method` to `KEYCLOAK-SAML` in `web.xml`. +Once `keycloak-saml.xml` is created and in the `WEB-INF` directory of your WAR, you must set the `auth-method` to `KEYCLOAK-SAML` in `web.xml`. You also have to use standard servlet security to specify role-base constraints on your URLs. Here's an example _web.xml_ file: diff --git a/docs/documentation/securing_apps/topics/saml/java/general-config/roleidentifiers_element.adoc b/docs/guides/securing-apps/partials/saml/roleidentifiers_element.adoc similarity index 95% rename from docs/documentation/securing_apps/topics/saml/java/general-config/roleidentifiers_element.adoc rename to docs/guides/securing-apps/partials/saml/roleidentifiers_element.adoc index 94eafcd4d5..716285a4c6 100644 --- a/docs/documentation/securing_apps/topics/saml/java/general-config/roleidentifiers_element.adoc +++ b/docs/guides/securing-apps/partials/saml/roleidentifiers_element.adoc @@ -1,5 +1,5 @@ -===== RoleIdentifiers element +== RoleIdentifiers element The `RoleIdentifiers` element defines what SAML attributes within the assertion received from the user should be used as role identifiers within the Jakarta EE Security Context for the user. diff --git a/docs/documentation/securing_apps/topics/saml/java/jboss-adapter/securing_wars.adoc b/docs/guides/securing-apps/partials/saml/securing_wars.adoc similarity index 98% rename from docs/documentation/securing_apps/topics/saml/java/jboss-adapter/securing_wars.adoc rename to docs/guides/securing-apps/partials/saml/securing_wars.adoc index 11f1efb2ee..fa7a2a22e6 100644 --- a/docs/documentation/securing_apps/topics/saml/java/jboss-adapter/securing_wars.adoc +++ b/docs/guides/securing-apps/partials/saml/securing_wars.adoc @@ -1,5 +1,5 @@ -===== Securing WARs using the {project_name} SAML Subsystem +=== Securing WARs using the {project_name} SAML Subsystem You do not have to open a WAR to secure it with {project_name}. Alternatively, you can externally secure it via the {project_name} SAML Adapter Subsystem. diff --git a/docs/documentation/securing_apps/topics/saml/java/general-config/sp-keys.adoc b/docs/guides/securing-apps/partials/saml/sp-keys.adoc similarity index 95% rename from docs/documentation/securing_apps/topics/saml/java/general-config/sp-keys.adoc rename to docs/guides/securing-apps/partials/saml/sp-keys.adoc index e56b6477fc..bbba3417f4 100644 --- a/docs/documentation/securing_apps/topics/saml/java/general-config/sp-keys.adoc +++ b/docs/guides/securing-apps/partials/saml/sp-keys.adoc @@ -1,6 +1,6 @@ [[_saml-sp-keys]] -===== Service Provider keys and key elements +== Service Provider keys and key elements If the IdP requires that the client application (or SP) sign all of its requests and/or if the IdP will encrypt assertions, you must define the keys used to do this. For client-signed documents you must define both the private and public key or certificate that is used to sign documents. diff --git a/docs/documentation/securing_apps/topics/saml/java/general-config/sp-keys/key_pems.adoc b/docs/guides/securing-apps/partials/saml/sp-keys/key_pems.adoc similarity index 97% rename from docs/documentation/securing_apps/topics/saml/java/general-config/sp-keys/key_pems.adoc rename to docs/guides/securing-apps/partials/saml/sp-keys/key_pems.adoc index 43446f2c6b..3c19042941 100644 --- a/docs/documentation/securing_apps/topics/saml/java/general-config/sp-keys/key_pems.adoc +++ b/docs/guides/securing-apps/partials/saml/sp-keys/key_pems.adoc @@ -1,5 +1,5 @@ -====== Key PEMS +=== Key PEMS Within the `Key` element you declare your keys and certificates directly using the sub elements `PrivateKeyPem`, `PublicKeyPem`, and `CertificatePem`. diff --git a/docs/documentation/securing_apps/topics/saml/java/general-config/sp-keys/keystore_element.adoc b/docs/guides/securing-apps/partials/saml/sp-keys/keystore_element.adoc similarity index 98% rename from docs/documentation/securing_apps/topics/saml/java/general-config/sp-keys/keystore_element.adoc rename to docs/guides/securing-apps/partials/saml/sp-keys/keystore_element.adoc index f00f4ffd04..87b6dedf95 100644 --- a/docs/documentation/securing_apps/topics/saml/java/general-config/sp-keys/keystore_element.adoc +++ b/docs/guides/securing-apps/partials/saml/sp-keys/keystore_element.adoc @@ -1,6 +1,6 @@ [[_saml-keystore]] -====== KeyStore element +=== KeyStore element Within the `Key` element you can load your keys and certificates from a Java Keystore. This is declared within a `KeyStore` element. diff --git a/docs/documentation/securing_apps/topics/saml/java/general-config/sp_element.adoc b/docs/guides/securing-apps/partials/saml/sp_element.adoc similarity index 99% rename from docs/documentation/securing_apps/topics/saml/java/general-config/sp_element.adoc rename to docs/guides/securing-apps/partials/saml/sp_element.adoc index 9f6797c064..642cf4f37a 100644 --- a/docs/documentation/securing_apps/topics/saml/java/general-config/sp_element.adoc +++ b/docs/guides/securing-apps/partials/saml/sp_element.adoc @@ -1,5 +1,5 @@ -===== SP element +== SP element Here is the explanation of the SP element attributes: diff --git a/docs/documentation/securing_apps/topics/saml/java/general-config/sp_principalname_mapping_element.adoc b/docs/guides/securing-apps/partials/saml/sp_principalname_mapping_element.adoc similarity index 95% rename from docs/documentation/securing_apps/topics/saml/java/general-config/sp_principalname_mapping_element.adoc rename to docs/guides/securing-apps/partials/saml/sp_principalname_mapping_element.adoc index 8fb3b1bf8c..915d87244f 100644 --- a/docs/documentation/securing_apps/topics/saml/java/general-config/sp_principalname_mapping_element.adoc +++ b/docs/guides/securing-apps/partials/saml/sp_principalname_mapping_element.adoc @@ -1,5 +1,5 @@ -===== SP PrincipalNameMapping element +== SP PrincipalNameMapping element This element is optional. When creating a Java Principal object that you obtain from methods such as `HttpServletRequest.getUserPrincipal()`, you can define what name is returned by the `Principal.getName()` method. diff --git a/docs/documentation/securing_apps/topics/saml/java/general-config/sp_role_mappings_provider_element.adoc b/docs/guides/securing-apps/partials/saml/sp_role_mappings_provider_element.adoc similarity index 97% rename from docs/documentation/securing_apps/topics/saml/java/general-config/sp_role_mappings_provider_element.adoc rename to docs/guides/securing-apps/partials/saml/sp_role_mappings_provider_element.adoc index 916fc60720..7b0cca6a11 100644 --- a/docs/documentation/securing_apps/topics/saml/java/general-config/sp_role_mappings_provider_element.adoc +++ b/docs/guides/securing-apps/partials/saml/sp_role_mappings_provider_element.adoc @@ -1,5 +1,5 @@ -===== RoleMappingsProvider element +== RoleMappingsProvider element The `RoleMappingsProvider` is an optional element that allows for the specification of the id and configuration of the `org.keycloak.adapters.saml.RoleMappingsProvider` SPI implementation that is to be used by the SAML adapter. @@ -29,7 +29,7 @@ The configuration of the provider looks as follows: The `id` attribute identifies which of the installed providers is to be used. The `Property` sub-element can be used multiple times to specify configuration properties for the provider. -====== Properties Based role mappings provider +=== Properties Based role mappings provider {project_name} includes a `RoleMappingsProvider` implementation that performs the role mappings using a `properties` file. This provider is identified by the id `properties-based-role-mapper` and is implemented by the `org.keycloak.adapters.saml.PropertiesBasedRoleMapper` @@ -93,7 +93,7 @@ role\u0020A=roleX,roleY ---- ifeval::[{project_community}==true] -====== Adding your own role mappings provider +=== Adding your own role mappings provider To add a custom role mappings provider one simply needs to implement the `org.keycloak.adapters.saml.RoleMappingsProvider` SPI. For more details see the `SAML Role Mappings SPI` section in link:{developerguide_link}[{developerguide_name}]. diff --git a/docs/guides/securing-apps/quarkus.adoc b/docs/guides/securing-apps/quarkus.adoc new file mode 100644 index 0000000000..faf603aa95 --- /dev/null +++ b/docs/guides/securing-apps/quarkus.adoc @@ -0,0 +1,3 @@ +:guide-title: Quarkus +:guide-summary: Using OpenID Connect and Keycloak to secure your Quarkus applications +:external-link: https://quarkus.io/guides/security-keycloak-authorization \ No newline at end of file diff --git a/docs/guides/securing-apps/saml-galleon-layers-detailed-config.adoc b/docs/guides/securing-apps/saml-galleon-layers-detailed-config.adoc new file mode 100644 index 0000000000..8c2682cdbd --- /dev/null +++ b/docs/guides/securing-apps/saml-galleon-layers-detailed-config.adoc @@ -0,0 +1,26 @@ +<#import "/templates/guide.adoc" as tmpl> +<#import "/templates/links.adoc" as links> + +<@tmpl.guide +title="{project_name} SAML Galleon feature pack detailed configuration" +priority=20 +tileVisible="false" +summary="Detailed list of elements for the `keycloak-saml.xml` configuration file"> + +This {section} contains the detailed list of elements for the `keycloak-saml.xml` configuration file used by the {project_name} SAML Galleon feature pack. + +include::partials/saml/sp_element.adoc[] +include::partials/saml/sp-keys.adoc[] +include::partials/saml/sp-keys/keystore_element.adoc[] +include::partials/saml/sp-keys/key_pems.adoc[] +include::partials/saml/sp_principalname_mapping_element.adoc[] +include::partials/saml/roleidentifiers_element.adoc[] +include::partials/saml/sp_role_mappings_provider_element.adoc[] +include::partials/saml/idp_element.adoc[] +include::partials/saml/idp_allowedclockskew_subelement.adoc[] +include::partials/saml/idp_singlesignonservice_subelement.adoc[] +include::partials/saml/idp_singlelogoutservice_subelement.adoc[] +include::partials/saml/idp_keys_subelement.adoc[] +include::partials/saml/idp_httpclient_subelement.adoc[] + + diff --git a/docs/guides/securing-apps/saml-galleon-layers.adoc b/docs/guides/securing-apps/saml-galleon-layers.adoc new file mode 100644 index 0000000000..2acf8c4f12 --- /dev/null +++ b/docs/guides/securing-apps/saml-galleon-layers.adoc @@ -0,0 +1,24 @@ +<#import "/templates/guide.adoc" as tmpl> +<#import "/templates/links.adoc" as links> + +<@tmpl.guide +title="{project_name} SAML Galleon feature pack for WildFly and EAP" +priority=10 +summary="Using {project_name} SAML Galleon feature pack to secure applications in WildFly and EAP"> + +The SAML adapter is distributed as a Galleon feature pack for wildfly 29 or newer. More details about the subject +in the https://docs.wildfly.org/32/WildFly_Elytron_Security.html#Keycloak_SAML_Integration[WildFly documentation]. +The same option is provided for JBoss EAP 8 GA. + +For an example about how to integrate Keycloak with JakartaEE applications running on latest Wildfly/EAP, take a look at the `servlet-saml-service-provider` Jakarta folder in the https://github.com/keycloak/keycloak-quickstarts[Keycloak Quickstart GitHub Repository]. + +include::partials/saml/installation.adoc[] +<#include "partials/saml/general-config.adoc" /> +include::partials/saml/idp-registration.adoc[] +include::partials/saml/logout.adoc[] +include::partials/saml/assertion-api.adoc[] +include::partials/saml/error_handling.adoc[] +include::partials/saml/debugging.adoc[] +include::partials/saml/multi-tenancy.adoc[] + + diff --git a/docs/guides/securing-apps/traefik-hub.adoc b/docs/guides/securing-apps/traefik-hub.adoc new file mode 100644 index 0000000000..014d9a24d6 --- /dev/null +++ b/docs/guides/securing-apps/traefik-hub.adoc @@ -0,0 +1,3 @@ +:guide-title: Traefik Hub +:guide-summary: Use Keycloak as an identity provider or as an identity broker for Traefik Hub API management +:external-link: https://doc.traefik.io/traefik-hub/authentication-authorization/idp/keycloak diff --git a/docs/guides/securing-apps/wildfly.adoc b/docs/guides/securing-apps/wildfly.adoc new file mode 100644 index 0000000000..4dbbb3db6d --- /dev/null +++ b/docs/guides/securing-apps/wildfly.adoc @@ -0,0 +1,3 @@ +:guide-title: WildFly +:guide-summary: Secure WildFly Applications with Keycloak +:external-link: https://wildfly-security.github.io/wildfly-elytron/blog/securing-wildfly-apps-openid-connect/ \ No newline at end of file diff --git a/docs/guides/templates/links.adoc b/docs/guides/templates/links.adoc index bedd01a472..9d35fe0624 100644 --- a/docs/guides/templates/links.adoc +++ b/docs/guides/templates/links.adoc @@ -1,3 +1,4 @@ <#macro server id anchor="">link:{links_server_${id}_url}<#if anchor != "">#${anchor}[{links_server_${id}_name}] <#macro operator id anchor="">link:{links_operator_${id}_url}<#if anchor != "">#${anchor}[{links_operator_${id}_name}] <#macro ha id anchor="">link:{links_high-availability_${id}_url}<#if anchor != "">#${anchor}[{links_high-availability_${id}_name}] +<#macro securingapps id anchor="">link:{links_securing-apps_${id}_url}<#if anchor != "">#${anchor}[{links_securing-apps_${id}_name}]