Convert chapter mod_auth_mellon from securing apps into guides

Closes #31569

Signed-off-by: rmartinc <rmartinc@redhat.com>

docs/documentation/securing_apps/topics.adoc

@@ -36,9 +36,6 @@ include::topics/oidc/oauth21-support.adoc[]
 include::topics/oidc/recommendations.adoc[]
 
 include::topics/saml/saml-overview.adoc[]
-ifeval::[{project_community}==true]
-include::topics/saml/mod-auth-mellon.adoc[]
-endif::[]
 ifeval::[{project_product}==true]
 include::topics/saml/java/java-adapters-product.adoc[]
 endif::[]

docs/guides/securing-apps/apisix.adoc

@@ -1,3 +0,0 @@
-: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

docs/guides/securing-apps/krakend.adoc

@@ -1,3 +0,0 @@
-:guide-title: KrakenD
-:guide-summary: Secure APIs with an API Gateway
-:external-link: https://www.krakend.io/docs/authorization/keycloak/

docs/guides/securing-apps/mod-auth-mellon.adoc

@@ -1,13 +1,18 @@
-[[_mod_auth_mellon]]
+<#import "/templates/guide.adoc" as tmpl>
+<#import "/templates/links.adoc" as links>
 
-=== mod_auth_mellon Apache HTTPD Module
+<@tmpl.guide
+title="mod_auth_mellon Apache Module"
+priority=30
+summary="Configuring the mod_auth_mellon Apache module with {project_name}">
+
+The https://github.com/latchset/mod_auth_mellon[mod_auth_mellon] is an authentication module for Apache. If your language/environment supports using Apache HTTPD as a proxy, then you can use mod_auth_mellon to secure your web application with SAML. For more details on this module see the _mod_auth_mellon_ GitHub repo.
 
 WARNING: {project_name} does not provide any official support to mod_auth_mellon. The instructions below are best-effort and may not be up-to-date.
+The {section} assumes that the server is a RHEL system. Although similar steps would be needed for other linux systems.
 We recommend that you stick to official mod_auth_mellon documentation for more details.
 
-The https://github.com/latchset/mod_auth_mellon[mod_auth_mellon] module is an Apache HTTPD plugin for SAML. If your language/environment supports using Apache HTTPD as a proxy, then you can use mod_auth_mellon to secure your web application with SAML. For more details on this module see the _mod_auth_mellon_ GitHub repo.
+To configure `mod_auth_mellon` you need the following files:
-
-To configure mod_auth_mellon you need:
 
 * An Identity Provider (IdP) entity descriptor XML file, which describes the connection to {project_name} or another SAML IdP
 * An SP entity descriptor XML file, which describes the SAML connections and configuration for the application you are securing.
@@ -15,7 +20,6 @@ To configure mod_auth_mellon you need:
 * A certificate PEM file, which is a text file that defines the certificate for your application.
 * mod_auth_mellon-specific Apache HTTPD module configuration.
 
-ifeval::[{project_community}==true]
 If you have already defined and registered the client application within a realm on the {project_name} application server, {project_name} can generate all the files you need except the Apache HTTPD module configuration.
 
 Perform the following procedure to generate the Apache HTTPD module configuration.
@@ -26,12 +30,11 @@ Perform the following procedure to generate the Apache HTTPD module configuratio
 . Select the *Mod Auth Mellon* files option.
 +
 .mod_auth_mellon config download
-image:images/mod-auth-mellon-config-download.png[]
+image::mod-auth-mellon-config-download.png[Download auth-melon configuration]
 
 . Click *Download* to download a ZIP file that contains the XML descriptor and PEM files you need.
-endif::[]
 
-==== Configuring mod_auth_mellon with {project_name}
+== Configuring mod_auth_mellon with {project_name}
 
 There are two hosts involved:
 
@@ -41,7 +44,7 @@ There are two hosts involved:
 
 All of the following steps need to performed on $sp_host with root privileges.
 
-===== Installing the packages
+=== Installing the packages
 
 To install the necessary packages, you will need:
 
@@ -53,17 +56,17 @@ To install the necessary packages, run this command:
 
  yum install httpd mod_auth_mellon mod_ssl openssl
 
-===== Creating a configuration directory for Apache SAML
+=== Creating a configuration directory for Apache SAML
 
 It is advisable to keep configuration files related to Apache's use of SAML in one location.
 
-Create a new directory named saml2 located under the Apache configuration root /etc/httpd:
+Create a new directory named saml2 located under the Apache configuration root `/etc/httpd`:
 
  mkdir /etc/httpd/saml2
 
-===== Configuring the Mellon Service Provider
+=== Configuring the Mellon Service Provider
 
-Configuration files for Apache add-on modules are located in the /etc/httpd/conf.d directory and have a file name extension of .conf. You need to create the /etc/httpd/conf.d/mellon.conf file and place Mellon's configuration directives in it.
+Configuration files for Apache add-on modules are located in the `/etc/httpd/conf.d` directory and have a file name extension of `.conf`. You need to create the `/etc/httpd/conf.d/mellon.conf` file and place Mellon's configuration directives in it.
 
 Mellon's configuration directives can roughly be broken down into two classes of information:
 
@@ -78,7 +81,7 @@ To configure the Mellon service provider, perform the following procedure.
 
 .Procedure
 
-. Create the file /etc/httpd/conf.d/mellon.conf with this content:
+. Create the file `/etc/httpd/conf.d/mellon.conf` with this content:
 
 [source,xml]
 ----
@@ -99,7 +102,7 @@ To configure the Mellon service provider, perform the following procedure.
 
 NOTE: Some of the files referenced in the code above are created in later steps.
 
-==== Setting the SameSite value for the cookie used by mod_auth_mellon
+=== Setting the SameSite value for the cookie used by mod_auth_mellon
 
 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
@@ -118,7 +121,7 @@ MellonCookieSameSite none
 
 The support for this configuration is available in the _mod_auth_mellon_ module from version 0.16.0.
 
-===== Creating the Service Provider metadata
+=== Creating the Service Provider metadata
 
 In SAML IdPs and SPs exchange SAML metadata, which is in XML format. The schema for the metadata is a standard, thus assuring participating SAML entities can consume each other's metadata. You need:
 
@@ -132,7 +135,7 @@ One of the components of SAML metadata is X509 certificates. These certificates
 
 You can use your own certificates if you already have a Certificate Authority (CA) or you can generate a self-signed certificate. For simplicity in this example a self-signed certificate is used.
 
-Because Mellon's SP metadata must reflect the capabilities of the installed version of mod_auth_mellon, must be valid SP metadata XML, and must contain an X509 certificate (whose creation can be obtuse unless you are familiar with X509 certificate generation) the most expedient way to produce the SP metadata is to use a tool included in the mod_auth_mellon package (mellon_create_metadata.sh). The generated metadata can always be edited later because it is a text file. The tool also creates your X509 key and certificate.
+Because Mellon's SP metadata must reflect the capabilities of the installed version of mod_auth_mellon, must be valid SP metadata XML, and must contain an X509 certificate (whose creation can be obtuse unless you are familiar with X509 certificate generation) the most expedient way to produce the SP metadata is to use a tool included in the mod_auth_mellon package (`mellon_create_metadata.sh`). The generated metadata can always be edited later because it is a text file. The tool also creates your X509 key and certificate.
 
 SAML IdPs and SPs identify themselves using a unique name known as an EntityID. To use the Mellon metadata creation tool you need:
 
@@ -148,8 +151,8 @@ To create the SP metadata, perform the following procedure.
 [source]
 ----
 fqdn=`hostname`
-mellon_endpoint_url="https://${fqdn}/mellon"
+mellon_endpoint_url="https://${r"${fqdn}"}/mellon"
-mellon_entity_id="${mellon_endpoint_url}/metadata"
+mellon_entity_id="${r"${mellon_endpoint_url}"}/metadata"
 file_prefix="$(echo "$mellon_entity_id" | sed 's/[^A-Za-z.]/_/g' | sed 's/__*/_/g')"
 ----
 
@@ -160,16 +163,16 @@ file_prefix="$(echo "$mellon_entity_id" | sed 's/[^A-Za-z.]/_/g' | sed 's/__*/_/
 /usr/libexec/mod_auth_mellon/mellon_create_metadata.sh $mellon_entity_id $mellon_endpoint_url
 ----
 
-. Move the generated files to their destination (referenced in the /etc/httpd/conf.d/mellon.conf file created above):
+. Move the generated files to their destination (referenced in the `/etc/httpd/conf.d/mellon.conf` file created above):
 +
 [source]
 ----
-mv ${file_prefix}.cert /etc/httpd/saml2/mellon.crt
+mv ${r"${file_prefix}"}.cert /etc/httpd/saml2/mellon.crt
-mv ${file_prefix}.key /etc/httpd/saml2/mellon.key
+mv ${r"${file_prefix}"}.key /etc/httpd/saml2/mellon.key
-mv ${file_prefix}.xml /etc/httpd/saml2/mellon_metadata.xml
+mv ${r"${file_prefix}"}.xml /etc/httpd/saml2/mellon_metadata.xml
 ----
 
-===== Adding the Mellon Service Provider to the {project_name} Identity Provider
+=== Adding the Mellon Service Provider to the {project_name} Identity Provider
 
 Assumption: The {project_name} IdP has already been installed on the $idp_host.
 
@@ -187,34 +190,26 @@ After logging into the Admin Console, there will be an existing realm. When {pro
 
 . In the Name field type `test_realm` and click *Create*.
 
-====== Adding the Mellon Service Provider as a client of the realm
+==== Adding the Mellon Service Provider as a client of the realm
 
 In {project_name} SAML SPs are known as clients. To add the SP we must be in the Clients section of the realm.
 
-. Click the Clients menu item on the left and click *Create* in the upper right corner to create a new client.
+. Click the Clients menu item on the left and click the *Import client* button.
-
+. In the *Resource file* field, provide the Mellon SP metadata file created above (`/etc/httpd/saml2/mellon_metadata.xml`).
-====== Adding the Mellon SP client
-
-To add the Mellon SP client, perform the following procedure.
-
-.Procedure
-. Set the client protocol to SAML.
-. From the Client Protocol drop down list, select *saml*.
-. Provide the Mellon SP metadata file created above (/etc/httpd/saml2/mellon_metadata.xml).
 +
 Depending on where your browser is running you might have to copy the SP metadata from $sp_host to the machine on which your browser is running so the browser can find the file.
 . Click *Save*.
 
-====== Editing the Mellon SP client
+==== Editing the Mellon SP client
 
 Use this procedure to set important client configuration parameters.
 
 .Procedure
 
-. Ensure "Force POST Binding" is On.
+. Ensure *Force POST Binding* is On.
-. Add paosResponse to the Valid Redirect URIs list:
+. Add paosResponse to the *Valid Redirect URIs* list:
-. Copy the postResponse URL in "Valid Redirect URIs" and paste it into the empty add text fields just below the "+".
+. Copy the postResponse URL in *Valid Redirect URIs* and paste it into the empty add text fields just below the "+".
-. Change "postResponse" to "paosResponse". (The paosResponse URL is needed for SAML ECP.)
+. Change `postResponse` to  paosResponse`. (The paosResponse URL is needed for SAML ECP.)
 . Click *Save* at the bottom.
 
 Many SAML SPs determine authorization based on a user's membership in a group. The {project_name} IdP can manage user group information but it does not supply the user's groups unless the IdP is configured to supply it as a SAML attribute.
@@ -223,18 +218,19 @@ Perform the following procedure to configure the IdP to supply the user's groups
 
 .Procedure
 
-. Click the Mappers tab of the client.
+. Click the *Client scopes* tab of the client.
-. In the upper right corner of the Mappers page, click *Create*.
+. Click the dedicated scope placed in the first row.
-. From the Mapper Type drop-down list select *Group list*.
+. In the Mappers page, click the *Add mapper* button and select *By configuration*.
-. Set Name to "group list".
+. From the Mapper Type list select *Group list*.
-. Set the SAML attribute name to "groups".
+. Set Name to `group list`.
+. Set the SAML attribute name to `groups`.
 . Click *Save*.
 
 The remaining steps are performed on $sp_host.
 
-====== Retrieving the Identity Provider metadata
+==== Retrieving the Identity Provider metadata
 
-Now that you have created the realm on the IdP you need to retrieve the IdP metadata associated with it so the Mellon SP recognizes it. In the /etc/httpd/conf.d/mellon.conf file created previously, the MellonIdPMetadataFile is specified as /etc/httpd/saml2/idp_metadata.xml but until now that file has not existed on $sp_host.
+Now that you have created the realm on the IdP you need to retrieve the IdP metadata associated with it so the Mellon SP recognizes it. In the `/etc/httpd/conf.d/mellon.conf` file created previously, the `MellonIdPMetadataFile` is specified as `/etc/httpd/saml2/idp_metadata.xml` but until now that file has not existed on $sp_host.
 
 Use this procedure to retrieve that file from the IdP.
 
@@ -245,7 +241,7 @@ Use this procedure to retrieve that file from the IdP.
 [source,subs="attributes+"]
 ----
 curl -k -o /etc/httpd/saml2/idp_metadata.xml \
-https://$idp_host{kc_realms_path}/test_realm/protocol/saml/descriptor
+https://$idp_host/realms/test_realm/protocol/saml/descriptor
 ----
 +
 Mellon is now fully configured.
@@ -267,3 +263,5 @@ systemctl restart httpd.service
 ----
 
 You have now set up both {project_name} as a SAML IdP in the test_realm and mod_auth_mellon as SAML SP protecting the URL $sp_host/protected (and everything beneath it) by authenticating against the ``$idp_host`` IdP.
+
+</@tmpl.guide>

docs/guides/securing-apps/quarkus.adoc

@@ -1,3 +0,0 @@
-:guide-title: Quarkus
-:guide-summary: Using OpenID Connect and Keycloak to secure your Quarkus applications
-:external-link: https://quarkus.io/guides/security-keycloak-authorization

docs/guides/securing-apps/traefik-hub.adoc

@@ -1,3 +0,0 @@
-: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

docs/guides/securing-apps/wildfly.adoc

@@ -1,3 +0,0 @@
-: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/