Convert chapter planning for securing applications and services to gu…

…ides Final removal of the securing_apps documentation Final checks for links, order and other minor things Closes keycloak#31328 Signed-off-by: rmartinc <[email protected]>
wistefan · Aug 1, 2024 · 942d5d0 · 942d5d0
1 parent fed8041
commit 942d5d0
Show file tree

Hide file tree

Showing 43 changed files with 79 additions and 182 deletions.
diff --git a/docs/documentation/aggregation/pom.xml b/docs/documentation/aggregation/pom.xml
@@ -26,12 +26,6 @@
             <version>${project.version}</version>
             <type>pom</type>
         </dependency>
-        <dependency>
-            <groupId>org.keycloak.documentation</groupId>
-            <artifactId>securing-apps</artifactId>
-            <version>${project.version}</version>
-            <type>pom</type>
-        </dependency>
         <dependency>
             <groupId>org.keycloak.documentation</groupId>
             <artifactId>server-admin</artifactId>
@@ -107,22 +101,6 @@
                             </resources>
                         </configuration>
                     </execution>
-                    <execution>
-                        <id>copy-securing_apps</id>
-                        <phase>process-resources</phase>
-                        <goals>
-                            <goal>copy-resources</goal>
-                        </goals>
-                        <configuration>
-                            <outputDirectory>${project.build.outputDirectory}/securing_apps/</outputDirectory>
-                            <resources>
-                                <resource>
-                                    <directory>../securing_apps/target/generated-docs</directory>
-                                    <include>**/**</include>
-                                </resource>
-                            </resources>
-                        </configuration>
-                    </execution>
                     <execution>
                         <id>copy-server_admin</id>
                         <phase>process-resources</phase>

diff --git a/docs/documentation/aggregation/src/index.html b/docs/documentation/aggregation/src/index.html
@@ -34,7 +34,6 @@
 <body>
 <img src="keycloak_logo.png"/>
 <ul>
-    <li><a href="securing_apps/${masterFile}.html">Securing Apps</a></li>
     <li><a href="server_admin/${masterFile}.html">Server Admin</a></li>
     <li><a href="server_development/${masterFile}.html">Server Development</a></li>
     <li><a href="authorization_services/${masterFile}.html">Authorization Services</a></li>

diff --git a/docs/documentation/build-auto.sh b/docs/documentation/build-auto.sh
@@ -3,7 +3,7 @@
 OPTS=$1
 
 while true; do 
-    CHANGED=`inotifywait -r -e modify,move,create,delete authorization_services getting_started securing_apps server_admin server_development server_installation upgrading --format %w`
+    CHANGED=`inotifywait -r -e modify,move,create,delete authorization_services getting_started server_admin server_development server_installation upgrading --format %w`
     GUIDE=`echo $CHANGED | cut -d '/' -f 1`
     mvn clean install -f $GUIDE $OPTS  
 done
diff --git a/docs/documentation/pom.xml b/docs/documentation/pom.xml
@@ -35,7 +35,6 @@
         <module>header-maven-plugin</module>
         <module>api_documentation</module>
         <module>authorization_services</module>
-        <module>securing_apps</module>
         <module>server_admin</module>
         <module>server_development</module>
         <module>release_notes</module>

diff --git a/docs/documentation/release_notes/topics/23_0_0.adoc b/docs/documentation/release_notes/topics/23_0_0.adoc
@@ -95,7 +95,7 @@ It is being replaced by the Elytron OIDC adapter,which is included in WildFly, a
 The SAML adapter for WildFly and JBoss EAP is no longer distributed as a ZIP download, but rather a Galleon feature pack,
 making it easier and more seamless to install.
 
-See the link:{adapterguide_link}[{adapterguide_name}] for the details.
+See the link:{securing_apps_link}[{securing_apps_name}] for the details.
 
 endif::[]
 

diff --git a/docs/documentation/securing_apps/.asciidoctorconfig b/docs/documentation/securing_apps/.asciidoctorconfig
diff --git a/docs/documentation/securing_apps/docinfo-footer.html b/docs/documentation/securing_apps/docinfo-footer.html
diff --git a/docs/documentation/securing_apps/docinfo.html b/docs/documentation/securing_apps/docinfo.html
diff --git a/docs/documentation/securing_apps/images/keycloak_logo.png b/docs/documentation/securing_apps/images/keycloak_logo.png
diff --git a/docs/documentation/securing_apps/index.adoc b/docs/documentation/securing_apps/index.adoc
diff --git a/docs/documentation/securing_apps/pom.xml b/docs/documentation/securing_apps/pom.xml
diff --git a/docs/documentation/securing_apps/topics.adoc b/docs/documentation/securing_apps/topics.adoc
diff --git a/docs/documentation/securing_apps/topics/oidc/oidc-overview.adoc b/docs/documentation/securing_apps/topics/oidc/oidc-overview.adoc
diff --git a/docs/documentation/securing_apps/topics/saml/saml-overview.adoc b/docs/documentation/securing_apps/topics/saml/saml-overview.adoc
diff --git a/docs/documentation/securing_apps/topics/templates b/docs/documentation/securing_apps/topics/templates
diff --git a/docs/documentation/server_admin/topics/authentication/authentication-sessions.adoc b/docs/documentation/server_admin/topics/authentication/authentication-sessions.adoc
@@ -19,7 +19,7 @@ authentication factor than the currently authenticated factor.
 
 In some rare cases, it can happen that after authentication in the first browser tab, other browser tabs are not able to restart authentication because the authentication session is already
 expired. In this case, the particular browser tab will redirect the error about the expired authentication session back to the client in a protocol specific way. For more details, see the corresponding sections
-of  *OIDC documentation* in the link:{securing_apps_link}[securing apps] section and  link:{adapterguide_link}#_saml-errors[SAML documentation]. When the client application receives such an error, it can immediately resubmit the OIDC/SAML authentication request to {project_name} as
+of  *OIDC documentation* in the link:{securing_apps_link}[securing apps] section. When the client application receives such an error, it can immediately resubmit the OIDC/SAML authentication request to {project_name} as
 this should usually automatically authenticate the user due to the existing SSO session as described earlier. As a result, the end user is authenticated automatically in all browser tabs.
-The *Keycloak JavaScript adapter* in the link:{securing_apps_link}[securing apps] section, link:{adapterguide_link}#_saml[{project_name} SAML adapter], and <<_identity_broker, {project_name} Identity provider>>
+The *Keycloak JavaScript adapter* in the link:{securing_apps_link}[securing apps] section, and <<_identity_broker, {project_name} Identity provider>>
 support to handle this error automatically and retry the authentication to the {project_name} server in such a case.
diff --git a/docs/documentation/server_admin/topics/clients/client-policies.adoc b/docs/documentation/server_admin/topics/clients/client-policies.adoc
@@ -37,8 +37,8 @@ Conformance to a required security standards and profiles such as FAPI and OAuth
 
 == Protocol
 
-The client policy concept is independent of any specific protocol. {project_name} currently supports especially client profiles for the link:{securing_apps_link}[OpenID Connect (OIDC) protocol], but there is
-also a client profile available for the link:{adapterguide_link}#_saml[SAML protocol].
+The client policy concept is independent of any specific protocol. {project_name} currently supports especially client profiles for the link:{adminguide_link}#con-oidc_server_administration_guide[OpenID Connect (OIDC) protocol], but there is
+also a client profile available for the link:{adminguide_link}#_saml[SAML protocol].
 
 == Architecture
 

diff --git a/docs/documentation/server_admin/topics/clients/oidc/con-basic-settings.adoc b/docs/documentation/server_admin/topics/clients/oidc/con-basic-settings.adoc
@@ -38,11 +38,11 @@ This option handles link:https://fetch.spec.whatwg.org/[Cross-Origin Resource Sh
 If browser JavaScript attempts an AJAX HTTP request to a server whose domain is different from the one that the
 JavaScript code came from, the request must use CORS. The server must handle CORS requests, otherwise the browser will not display or allow the request to be processed. This protocol protects against XSS, CSRF, and other JavaScript-based attacks.
 +
-Domain URLs listed here are embedded within the access token sent to the client application. The client application uses this information to decide whether to allow a CORS request to be invoked on it. Only {project_name} client adapters support this feature. See link:{adapterguide_link}[{adapterguide_name}] for more information.
+Domain URLs listed here are embedded within the access token sent to the client application. The client application uses this information to decide whether to allow a CORS request to be invoked on it. Only {project_name} client adapters support this feature. See link:{securing_apps_link}[{securing_apps_name}] for more information.
 
 [[_admin-url]]
 Admin URL:: Callback endpoint for a client. The server uses this URL to make callbacks like pushing revocation policies, performing backchannel logout, and other administrative operations. For {project_name} servlet adapters, this URL can be the root URL of the servlet application.
-For more information, see link:{adapterguide_link}[{adapterguide_name}].
+For more information, see link:{securing_apps_link}[{securing_apps_name}].
 
 == Capability Config
 [[_access-type]]

diff --git a/docs/documentation/server_development/topics/admin-rest-api.adoc b/docs/documentation/server_development/topics/admin-rest-api.adoc
@@ -97,5 +97,4 @@ endif::[]
 === Additional resources
 [role="_additional-resources"]
 * {adminguide_link}[{adminguide_name}]
-* {adapterguide_link}[{adapterguide_name}]
 * {apidocs_link}[{apidocs_name}]
diff --git a/docs/documentation/server_development/topics/auth-spi.adoc b/docs/documentation/server_development/topics/auth-spi.adoc
@@ -1194,7 +1194,7 @@ or during `Service account` authentication (represented by OAuth2 `Client Creden
 
 [role="_additional-resource"]
 .Additional resources
-* For more details about {project_name} adapter and OAuth2 flows see link:{adapterguide_link}[{adapterguide_name}].
+* For more details about {project_name} adapter and OAuth2 flows see link:{securing_apps_link}[{securing_apps_name}].
 
 ==== Default implementations
 

diff --git a/docs/documentation/server_development/topics/saml-role-mappings-spi.adoc b/docs/documentation/server_development/topics/saml-role-mappings-spi.adoc
@@ -11,7 +11,7 @@ Implementations can not only map roles into other roles but also add or remove r
 roles assigned to the SAML principal) depending on the use case.
 
 For details about the configuration of the role mappings provider for the SAML adapter as well as a description of the default
-implementations available see the link:{adapterguide_link}[{adapterguide_name}].
+implementations available see the link:{securing_apps_link}[{securing_apps_name}].
 
 === Implementing a custom role mappings provider
 
@@ -26,4 +26,4 @@ of the custom implementation must be added to the archive that also contains the
 
 When the SP application is deployed, the role mappings provider that will be used is selected by the id that was set in
 `keycloak-saml.xml` or in the `keycloak-saml` subsystem. So to enable your custom provider simply make sure that its id is
-properly set in the adapter configuration.
+properly set in the adapter configuration.
diff --git a/docs/documentation/tests/pom.xml b/docs/documentation/tests/pom.xml
@@ -80,12 +80,6 @@
             <version>${project.version}</version>
             <type>pom</type>
         </dependency>
-        <dependency>
-            <groupId>org.keycloak.documentation</groupId>
-            <artifactId>securing-apps</artifactId>
-            <version>${project.version}</version>
-            <type>pom</type>
-        </dependency>
         <dependency>
             <groupId>org.keycloak.documentation</groupId>
             <artifactId>server-admin</artifactId>

diff --git a/docs/documentation/tests/src/test/java/org/keycloak/documentation/test/Guides.java b/docs/documentation/tests/src/test/java/org/keycloak/documentation/test/Guides.java
@@ -12,7 +12,6 @@ public class Guides {
         List<String> g = new LinkedList<>();
         g.add("authorization_services");
         g.add("release_notes");
-        g.add("securing_apps");
         g.add("server_admin");
         g.add("server_development");
         g.add("upgrading");

diff --git a/docs/documentation/tests/src/test/resources/guide-url-fragments b/docs/documentation/tests/src/test/resources/guide-url-fragments
@@ -1,9 +1,8 @@
 api_documentation=api_documentation
 authorization_services=authorization_services
 getting_started=getting_started
-securing_apps=securing_apps
 server_admin=server_admin
 server_development=server_development
 server_installation=server_installation
 upgrading=upgrading
-release_notes=release_notes
+release_notes=release_notes
diff --git a/docs/documentation/topics/templates/document-attributes.adoc b/docs/documentation/topics/templates/document-attributes.adoc
@@ -40,13 +40,6 @@
 :authorizationguide_name_short: Authorization Services
 :authorizationguide_link: {project_doc_base_url}/authorization_services/
 :authorizationguide_link_latest: {project_doc_base_url_latest}/authorization_services/
-:adapterguide_name: Securing Applications and Services Guide
-:adapterguide_name_short: Securing Apps
-:adapterguide_link: {project_doc_base_url}/securing_apps/
-:adapterguide_link_js_adapter: {adapterguide_link}#_javascript_adapter
-:adapterguide_link_nodejs_adapter: {adapterguide_link}#_nodejs_adapter
-:adapterguide_link_latest: {project_doc_base_url_latest}/securing_apps/
-:adapterguide_logout_link: {adapterguide_link}#_java_adapter_logout
 :adminguide_name: Server Administration Guide
 :adminguide_name_short: Server Administration
 :adminguide_link: {project_doc_base_url}/server_admin/
@@ -128,4 +121,5 @@
 :section: guide
 :sections: guides
 :securing_apps_name: Securing applications Guides
+:securing_apps_name_short: Securing applications
 :securing_apps_link: https://www.keycloak.org/guides#securing-apps
diff --git a/docs/documentation/topics/templates/release-header.adoc b/docs/documentation/topics/templates/release-header.adoc
@@ -6,7 +6,7 @@ ifeval::["{release_header_guide}" != "{gettingstarted_name_short}"]
 * {gettingstarted_link}[{gettingstarted_name_short}]
 endif::[]
 ifeval::["{release_header_guide}" != "{adapterguide_name_short}"]
-* {adapterguide_link}[{adapterguide_name_short}]
+* {securing_apps_link}[{securing_apps_name_short}]
 endif::[]
 ifeval::["{release_header_guide}" != "{adminguide_name_short}"]
 * {adminguide_link}[{adminguide_name_short}]
@@ -28,4 +28,4 @@ endif::[]
 [.top-menu-version]
 ====
 Version *{project_version}*
-====
+====
diff --git a/docs/documentation/upgrading/topics/changes/changes.adoc b/docs/documentation/upgrading/topics/changes/changes.adoc
@@ -1091,7 +1091,7 @@ There are now 3 separate adapter downloads for WildFly, JBoss EAP and JBoss AS7:
 Make sure you grab the correct one.
 
 You also need to update standalone.xml as the extension module and subsystem definition has changed.
-See link:{adapterguide_link}[{adapterguide_name}] for details.
+See link:{securing_apps_link}[{securing_apps_name}] for details.
 
 === Migrating from 1.2.0.Beta1 to 1.2.0.RC1
 

diff --git a/docs/guides/attributes.adoc b/docs/guides/attributes.adoc
@@ -8,6 +8,8 @@
 :authorizationguide_name: Authorization Services Guide
 :authorizationguide_name_short: Authorization Services
 :authorizationguide_link: {project_doc_base_url}/authorization_services/
+:developerguide_name: Server Developer Guide
+:developerguide_link: {project_doc_base_url}/server_development/
 :section: guide
 :sections: guides
 :archivedownloadurl: https://github.com/keycloak/keycloak/releases/download/{version}/keycloak-{version}.zip
@@ -26,3 +28,4 @@
 :quickstartRepo_dir: keycloak-quickstarts
 :securing_apps_link: https://www.keycloak.org/guides#securing-apps
 :kc_js_path: /js
+:kc_realms_path: /realms
diff --git a/docs/guides/securing-apps/client-registration-cli.adoc b/docs/guides/securing-apps/client-registration-cli.adoc
@@ -3,7 +3,7 @@
 
 <@tmpl.guide
 title="Client registration CLI"
-priority=60
+priority=110
 summary="Automating Client Registration with the CLI">
 
 The Client Registration CLI is a command-line interface (CLI) tool for application developers to configure new clients in a self-service manner when integrating with {project_name}. It is specifically designed to interact with {project_name} Client Registration REST endpoints.
@@ -383,4 +383,4 @@ Run the [command]`kcreg update-token --help` command for more information about
 +
 A: This error means your client is configured with [filename]`Signed JWT` token credentials, which means you have to use the [command]`--keystore` parameter when logging in.
 
-</@tmpl.guide>
+</@tmpl.guide>
diff --git a/docs/guides/securing-apps/client-registration.adoc b/docs/guides/securing-apps/client-registration.adoc
@@ -3,7 +3,7 @@
 
 <@tmpl.guide
 title="Client registration service"
-priority=50
+priority=100
 summary="Using the client registration service">
 
 In order for an application or service to utilize {project_name} it has to register a client in {project_name}.
@@ -218,4 +218,4 @@ realm roles or client roles of other clients.
 * Client Disabled Policy - Newly registered client will be disabled. This means that admin needs to manually approve and enable all newly registered clients.
 This policy is not used by default even for anonymous registration.
 
-</@tmpl.guide>
+</@tmpl.guide>
diff --git a/docs/guides/securing-apps/docker-registry.adoc b/docs/guides/securing-apps/docker-registry.adoc
@@ -3,7 +3,7 @@
 
 <@tmpl.guide
 title="Docker registry"
-priority=40
+priority=90
 summary="Configuring a Docker registry to use {project_name}">
 
 NOTE: Docker authentication is disabled by default. To enable see the https://www.keycloak.org/server/features[Enabling and disabling features] {section}.
@@ -64,4 +64,4 @@ Once the above configuration has taken place, and the keycloak server and Docker
 	Password: *******
 	Login Succeeded
 
-</@tmpl.guide>
+</@tmpl.guide>