Move saml documentation to guides
Closes #31330 Signed-off-by: rmartinc <rmartinc@redhat.com>
This commit is contained in:
rmartinc
Marek Posolda
parent
aab7a912c4
commit
ccab30d5f2
44 changed files with 260 additions and 183 deletions
|
|
@ -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]
|
||||
* Ability to specify signature algorithm in Signed JWT Client Authentication. Thanks to https://github.com/tnorimat[Takashi Norimatsu]
|
||||
|
|
|
|||
|
|
@ -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]
|
||||
|
|
|
|||
|
|
@ -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::[]
|
||||
|
|
@ -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.
|
||||
|
||||
|
||||
|
|
@ -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].
|
||||
|
|
@ -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::[]
|
||||
|
|
@ -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.
|
||||
|
|
@ -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::[]
|
||||
|
||||
|
|
@ -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.
|
||||
|
|
@ -40,5 +40,12 @@
|
|||
<include>pinned-guides</include>
|
||||
</includes>
|
||||
</fileSet>
|
||||
<fileSet>
|
||||
<directory>${project.basedir}/securing-apps</directory>
|
||||
<outputDirectory>/generated-guides/securing-apps/</outputDirectory>
|
||||
<includes>
|
||||
<include>pinned-guides</include>
|
||||
</includes>
|
||||
</fileSet>
|
||||
</fileSets>
|
||||
</assembly>
|
||||
|
|
|
|||
|
|
@ -201,6 +201,18 @@
|
|||
<outputDirectory>${project.build.directory}/generated-docs/high-availability</outputDirectory>
|
||||
</configuration>
|
||||
</execution>
|
||||
<execution>
|
||||
<id>securing-apps-asciidoc-to-html</id>
|
||||
<phase>generate-resources</phase>
|
||||
<goals>
|
||||
<goal>process-asciidoc</goal>
|
||||
</goals>
|
||||
<configuration>
|
||||
<sourceDirectory>${basedir}/target/generated-guides/securing-apps</sourceDirectory>
|
||||
<outputDirectory>${project.build.directory}/generated-docs/securing-apps</outputDirectory>
|
||||
<preserveDirectories>true</preserveDirectories>
|
||||
</configuration>
|
||||
</execution>
|
||||
</executions>
|
||||
</plugin>
|
||||
<plugin>
|
||||
|
|
@ -223,4 +235,4 @@
|
|||
</plugins>
|
||||
</build>
|
||||
|
||||
</project>
|
||||
</project>
|
||||
|
|
|
|||
3
docs/guides/securing-apps/apisix.adoc
Normal file
3
docs/guides/securing-apps/apisix.adoc
Normal file
|
|
@ -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
|
||||
12
docs/guides/securing-apps/index.adoc
Normal file
12
docs/guides/securing-apps/index.adoc
Normal file
|
|
@ -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>
|
||||
|
||||
<#list ctx.guides as guide>
|
||||
include::${guide.template}[leveloffset=+1]
|
||||
</#list>
|
||||
3
docs/guides/securing-apps/krakend.adoc
Normal file
3
docs/guides/securing-apps/krakend.adoc
Normal file
|
|
@ -0,0 +1,3 @@
|
|||
:guide-title: KrakenD
|
||||
:guide-summary: Secure APIs with an API Gateway
|
||||
:external-link: https://www.krakend.io/docs/authorization/keycloak/
|
||||
|
|
@ -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
|
||||
|
|
@ -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.
|
||||
|
|
@ -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()`.
|
||||
|
|
@ -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:
|
|||
</keycloak-saml-adapter>
|
||||
----
|
||||
|
||||
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[]
|
||||
|
|
@ -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$$`.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
||||
|
|
@ -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
|
||||
|
|
@ -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>>.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
126
docs/guides/securing-apps/partials/saml/installation.adoc
Normal file
126
docs/guides/securing-apps/partials/saml/installation.adoc
Normal file
|
|
@ -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+"]
|
||||
----
|
||||
<plugin>
|
||||
<groupId>org.wildfly.plugins</groupId>
|
||||
<artifactId>wildfly-maven-plugin</artifactId>
|
||||
<version>5.0.0.Final</version>
|
||||
<configuration>
|
||||
<feature-packs>
|
||||
<feature-pack>
|
||||
<location>wildfly@maven(org.jboss.universe:community-universe)#32.0.1.Final</location>
|
||||
</feature-pack>
|
||||
<feature-pack>
|
||||
<groupId>org.keycloak</groupId>
|
||||
<artifactId>keycloak-saml-adapter-galleon-pack</artifactId>
|
||||
<version>25.0.2</version>
|
||||
</feature-pack>
|
||||
</feature-packs>
|
||||
<layers>
|
||||
<layer>core-server</layer>
|
||||
<layer>web-server</layer>
|
||||
<layer>jaxrs-server</layer>
|
||||
<layer>datasources-web-server</layer>
|
||||
<layer>webservices</layer>
|
||||
<layer>keycloak-saml</layer>
|
||||
<layer>keycloak-client-saml</layer>
|
||||
<layer>keycloak-client-saml-ejb</layer>
|
||||
</layers>
|
||||
</configuration>
|
||||
<executions>
|
||||
<execution>
|
||||
<goals>
|
||||
<goal>package</goal>
|
||||
</goals>
|
||||
</execution>
|
||||
</executions>
|
||||
</plugin>
|
||||
----
|
||||
|
||||
=== Example of provision using wildfly jar maven plugin
|
||||
|
||||
[source,xml,subs="attributes+"]
|
||||
----
|
||||
<plugin>
|
||||
<groupId>org.wildfly.plugins</groupId>
|
||||
<artifactId>wildfly-jar-maven-plugin</artifactId>
|
||||
<version>11.0.2.Final</version>
|
||||
<configuration>
|
||||
<feature-packs>
|
||||
<feature-pack>
|
||||
<location>wildfly@maven(org.jboss.universe:community-universe)#32.0.1.Final</location>
|
||||
</feature-pack>
|
||||
<feature-pack>
|
||||
<groupId>org.keycloak</groupId>
|
||||
<artifactId>keycloak-saml-adapter-galleon-pack</artifactId>
|
||||
<version>25.0.2</version>
|
||||
</feature-pack>
|
||||
</feature-packs>
|
||||
<layers>
|
||||
<layer>core-server</layer>
|
||||
<layer>web-server</layer>
|
||||
<layer>jaxrs-server</layer>
|
||||
<layer>datasources-web-server</layer>
|
||||
<layer>webservices</layer>
|
||||
<layer>keycloak-saml</layer>
|
||||
<layer>keycloak-client-saml</layer>
|
||||
<layer>keycloak-client-saml-ejb</layer>
|
||||
</layers>
|
||||
</configuration>
|
||||
<executions>
|
||||
<execution>
|
||||
<goals>
|
||||
<goal>package</goal>
|
||||
</goals>
|
||||
</execution>
|
||||
</executions>
|
||||
</plugin>
|
||||
----
|
||||
|
||||
=== Example of provision using EAP maven plugin
|
||||
|
||||
[source,xml,subs="attributes+"]
|
||||
----
|
||||
<plugin>
|
||||
<groupId>org.jboss.eap.plugins</groupId>
|
||||
<artifactId>eap-maven-plugin</artifactId>
|
||||
<version>1.0.0.Final-redhat-00014</version>
|
||||
<configuration>
|
||||
<channels>
|
||||
<channel>
|
||||
<manifest>
|
||||
<groupId>org.jboss.eap.channels</groupId>
|
||||
<artifactId>eap-8.0</artifactId>
|
||||
</manifest>
|
||||
</channel>
|
||||
</channels>
|
||||
<feature-packs>
|
||||
<feature-pack>
|
||||
<location>org.keycloak:keycloak-saml-adapter-galleon-pack</location>
|
||||
</feature-pack>
|
||||
</feature-packs>
|
||||
<layers>
|
||||
<layer>core-server</layer>
|
||||
<layer>web-server</layer>
|
||||
<layer>jaxrs-server</layer>
|
||||
<layer>datasources-web-server</layer>
|
||||
<layer>webservices</layer>
|
||||
<layer>keycloak-saml</layer>
|
||||
<layer>keycloak-client-saml</layer>
|
||||
<layer>keycloak-client-saml-ejb</layer>
|
||||
</layers>
|
||||
</configuration>
|
||||
<executions>
|
||||
<execution>
|
||||
<goals>
|
||||
<goal>package</goal>
|
||||
</goals>
|
||||
</execution>
|
||||
</executions>
|
||||
</plugin>
|
||||
----
|
||||
|
|
@ -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
|
||||
|
|
@ -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]
|
||||
----
|
||||
<context-param>
|
||||
|
|
@ -25,16 +23,6 @@ For EAP 7, WildFly 10/11:
|
|||
</context-param>
|
||||
----
|
||||
|
||||
For EAP 6:
|
||||
|
||||
[source,xml]
|
||||
----
|
||||
<context-param>
|
||||
<param-name>keycloak.sessionIdMapperUpdater.classes</param-name>
|
||||
<param-value>org.keycloak.adapters.saml.jbossweb.infinispan.InfinispanSessionCacheIdMapperUpdater</param-value>
|
||||
</context-param>
|
||||
----
|
||||
|
||||
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:
|
||||
|
||||
|
|
@ -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.
|
||||
|
||||
|
|
@ -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:
|
||||
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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`.
|
||||
|
|
@ -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.
|
||||
|
|
@ -1,5 +1,5 @@
|
|||
|
||||
===== SP element
|
||||
== SP element
|
||||
|
||||
Here is the explanation of the SP element attributes:
|
||||
|
||||
|
|
@ -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.
|
||||
|
|
@ -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}].
|
||||
3
docs/guides/securing-apps/quarkus.adoc
Normal file
3
docs/guides/securing-apps/quarkus.adoc
Normal file
|
|
@ -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
|
||||
|
|
@ -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[]
|
||||
|
||||
</@tmpl.guide>
|
||||
24
docs/guides/securing-apps/saml-galleon-layers.adoc
Normal file
24
docs/guides/securing-apps/saml-galleon-layers.adoc
Normal file
|
|
@ -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[]
|
||||
|
||||
</@tmpl.guide>
|
||||
3
docs/guides/securing-apps/traefik-hub.adoc
Normal file
3
docs/guides/securing-apps/traefik-hub.adoc
Normal file
|
|
@ -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
|
||||
3
docs/guides/securing-apps/wildfly.adoc
Normal file
3
docs/guides/securing-apps/wildfly.adoc
Normal file
|
|
@ -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/
|
||||
|
|
@ -1,3 +1,4 @@
|
|||
<#macro server id anchor="">link:{links_server_${id}_url}<#if anchor != "">#${anchor}</#if>[{links_server_${id}_name}]</#macro>
|
||||
<#macro operator id anchor="">link:{links_operator_${id}_url}<#if anchor != "">#${anchor}</#if>[{links_operator_${id}_name}]</#macro>
|
||||
<#macro ha id anchor="">link:{links_high-availability_${id}_url}<#if anchor != "">#${anchor}</#if>[{links_high-availability_${id}_name}]</#macro>
|
||||
<#macro securingapps id anchor="">link:{links_securing-apps_${id}_url}<#if anchor != "">#${anchor}</#if>[{links_securing-apps_${id}_name}]</#macro>
|
||||
|
|
|
|||
Loading…
Reference in a new issue