Update abstracts for accessing server assembly (#4340)

aneta-petrova · Lennonka · web-flow · commit 9bcce831ccaa · 2025-10-19T23:44:25.000+02:00
* Update abstracts for accessing server assembly

* Review abstracts in Configuring user auth

* Apply suggestions from style review

Co-authored-by: Lena Ansorgová &lt;zuansorg@redhat.com&gt;

* Reword abstracts for examples

---------

Co-authored-by: Lena Ansorgová &lt;zuansorg@redhat.com&gt;
diff --git a/guides/common/assembly_accessing-projectname-from-projectwebui.adoc b/guides/common/assembly_accessing-projectname-from-projectwebui.adoc
@@ -1,6 +1,6 @@
 :_mod-docs-content-type: ASSEMBLY
 
-include::modules/con_accessing-server.adoc[]
+include::modules/con_accessing-projectname-from-projectwebui.adoc[]
 
 include::modules/proc_logging-in-to-the-projectwebui.adoc[leveloffset=+1]
 
diff --git a/guides/common/assembly_configuring-kerberos-sso-with-freeipa-in-project.adoc b/guides/common/assembly_configuring-kerberos-sso-with-freeipa-in-project.adoc
@@ -2,7 +2,7 @@
 
 include::modules/con_configuring-kerberos-sso-with-freeipa-in-project.adoc[]
 
-include::modules/proc_enrolling-projectserver-in-freeipa-domain.adoc[leveloffset=+1]
+include::modules/proc_enrolling-projectserver-in-your-freeipa-domain.adoc[leveloffset=+1]
 
 include::modules/proc_configuring-the-freeipa-authentication-source-on-projectserver.adoc[leveloffset=+1]
 
diff --git a/guides/common/modules/con_accessing-projectname-from-projectwebui.adoc b/guides/common/modules/con_accessing-projectname-from-projectwebui.adoc
@@ -0,0 +1,7 @@
+:_mod-docs-content-type: CONCEPT
+
+[id="Accessing_Server_{context}"]
+= Accessing {ProjectName} from {ProjectWebUI}
+
+[role="_abstract"]
+After {ProjectName} has been installed and configured, you can use a browser to log in to the {ProjectWebUI}.
diff --git a/guides/common/modules/con_accessing-server.adoc b/guides/common/modules/con_accessing-server.adoc
diff --git a/guides/common/modules/con_configuring-sso-and-2fa-with-keycloak-quarkus-in-project.adoc b/guides/common/modules/con_configuring-sso-and-2fa-with-keycloak-quarkus-in-project.adoc
@@ -4,8 +4,8 @@
 = Configuring SSO and 2FA with {keycloak-quarkus} in {Project}
 
 [role="_abstract"]
-{keycloak-quarkus} is an open-source identity and access management solution that provides authentication features, such as single sign-on functionality, user federation, and centralized authentication management.
-With {keycloak-quarkus}, you can integrate {ProjectServer} with your existing {keycloak-quarkus} server to delegate user authentication and authorization to {keycloak-quarkus}.
+{keycloak-quarkus} is an open-source identity and access management solution that provides various authentication features.
+You can integrate {ProjectServer} with your existing {keycloak-quarkus} server to delegate user authentication and authorization to {keycloak-quarkus}.
 
 {keycloak} users can log in using the following login methods:
 
diff --git a/guides/common/modules/con_configuring-sso-and-2fa-with-keycloak-wildfly-in-project.adoc b/guides/common/modules/con_configuring-sso-and-2fa-with-keycloak-wildfly-in-project.adoc
@@ -4,8 +4,8 @@
 = Configuring SSO and 2FA with {keycloak-wildfly} in {Project}
 
 [role="_abstract"]
-{keycloak} is an open-source identity and access management solution that provides authentication features, such as single sign-on functionality, user federation, and centralized authentication management.
-With {keycloak-wildfly}, you can integrate {ProjectServer} with your existing {keycloak} server to delegate user authentication and authorization to {keycloak}.
+{keycloak} is an open source identity and access management solution that provides various authentication features.
+You can integrate {ProjectServer} with your existing {keycloak} server to delegate user authentication and authorization to {keycloak}.
 
 :FeatureName: Configuring {Project} with {keycloak-wildfly}
 include::snip_deprecated-feature.adoc[]
diff --git a/guides/common/modules/con_refreshing-external-user-groups-for-freeipa-or-ad.adoc b/guides/common/modules/con_refreshing-external-user-groups-for-freeipa-or-ad.adoc
@@ -4,5 +4,7 @@
 = Refreshing external user groups for {FreeIPA} or AD
 
 [role="_abstract"]
+If your environment includes external user groups based on {FreeIPA} or Active Directory (AD), review these guidelines for refreshing external user groups.
+
 External user groups based on {FreeIPA} or AD are refreshed only when a group member logs in to {Project}.
 It is not possible to alter user membership of external user groups in the {ProjectWebUI}, such changes are overwritten on the next group refresh.
diff --git a/guides/common/modules/proc_configuring-a-cross-forest-trust-between-freeipa-and-active-directory-for-project.adoc b/guides/common/modules/proc_configuring-a-cross-forest-trust-between-freeipa-and-active-directory-for-project.adoc
@@ -4,7 +4,7 @@
 = Configuring a cross-forest trust between {FreeIPA} and Active Directory for {Project}
 
 [role="_abstract"]
-When your {FreeIPA} deployment includes a cross-forest trust with Active Directory (AD), configure host-based access control (HBAC) and the System Security Services Daemon (SSSD) to enable AD users to log in to {Project}.
+If your {FreeIPA} deployment includes a cross-forest trust with Active Directory (AD), you must configure host-based access control (HBAC) and the System Security Services Daemon (SSSD) before AD users can log in to {Project}.
 
 .Prerequisites
 * An existing {FreeIPA} server with a cross-forest trust with AD established.
diff --git a/guides/common/modules/proc_configuring-a-project-client-to-provide-hammer-cli-authentication-with-keycloak.adoc b/guides/common/modules/proc_configuring-a-project-client-to-provide-hammer-cli-authentication-with-keycloak.adoc
@@ -5,6 +5,7 @@
 
 [role="_abstract"]
 If you are configuring a client that will provide Hammer CLI authentication to your {Project} deployment, delegate authentication to the {keycloak} server and add {keycloak} as an external authentication source in {Project}.
+
 Perform these steps on the {Project} client registered to {keycloak}.
 
 .Prerequisites
diff --git a/guides/common/modules/proc_configuring-a-project-client-to-provide-projectwebui-authentication-with-keycloak.adoc b/guides/common/modules/proc_configuring-a-project-client-to-provide-projectwebui-authentication-with-keycloak.adoc
@@ -5,6 +5,7 @@
 
 [role="_abstract"]
 If you are configuring a client that will provide {ProjectWebUI} authentication to your {Project} deployment, delegate authentication to the {keycloak} server and add {keycloak} as an external authentication source in {Project}.
+
 Perform these steps in the {ProjectWebUI}.
 
 .Prerequisites
diff --git a/guides/common/modules/proc_configuring-external-user-groups.adoc b/guides/common/modules/proc_configuring-external-user-groups.adoc
@@ -5,9 +5,9 @@
 
 [role="_abstract"]
 {Project} does not associate external users with their user group automatically.
-You must create a user group with the same name as in the external source on {Project}.
-Members of the external user group then automatically become members of the {Project} user group and receive the associated permissions.
+To associate these external users with their user group, you must create the user group on your {ProjectServer}.
 
+When you create a {Project} user group with the same name as in the external source, members of the external user group automatically become members of the {Project} user group and receive the associated permissions.
 The configuration of external user groups depends on the type of external authentication.
 
 To assign additional permissions to an external user, add this user to an internal user group that has no external mapping specified.
diff --git a/guides/common/modules/proc_configuring-hammer-cli-to-accept-freeipa-credentials.adoc b/guides/common/modules/proc_configuring-hammer-cli-to-accept-freeipa-credentials.adoc
@@ -4,7 +4,7 @@
 = Configuring Hammer CLI to accept {FreeIPA} credentials
 
 [role="_abstract"]
-Configure the {Project} Hammer CLI tool to use {FreeIPA} to authenticate users.
+To enable users to authenticate to the Hammer CLI by using their {FreeIPA} credentials, update Hammer configuration.
 
 .Prerequisites
 * You have enabled {FreeIPA} access to the {Project} API.
diff --git a/guides/common/modules/proc_configuring-the-freeipa-authentication-source-on-projectserver.adoc b/guides/common/modules/proc_configuring-the-freeipa-authentication-source-on-projectserver.adoc
@@ -4,7 +4,7 @@
 = Configuring the {FreeIPA} authentication source on {ProjectServer}
 
 [role="_abstract"]
-Enable {FreeIPA} users to access {Project} by configuring {FreeIPA} as an authentication provider on your {ProjectServer}.
+Connect your {ProjectServer} to your {FreeIPA} domain by configuring {FreeIPA} as an authentication provider on your {ProjectServer}.
 
 .Prerequisites
 * {ProjectServer} running on a system that is enrolled in the {FreeIPA} domain.
diff --git a/guides/common/modules/proc_configuring-the-project-client-in-keycloak-quarkus.adoc b/guides/common/modules/proc_configuring-the-project-client-in-keycloak-quarkus.adoc
@@ -4,7 +4,9 @@
 = Configuring the {Project} client in {keycloak-quarkus}
 
 [role="_abstract"]
-Configure the {Project} client in {keycloak-quarkus} with valid redirect URIs and mappers.
+On the {keycloak-quarkus} side, you must configure the {Project} client with valid redirect URIs and mappers.
+This includes setting the appropriate client authentication mode, redirect URIs, and necessary mappers to support {ProjectWebUI} or Hammer CLI authentication.
+
 Perform these steps in the {keycloak-quarkus} web UI.
 
 .Procedure
diff --git a/guides/common/modules/proc_configuring-the-project-client-in-keycloak-wildfly.adoc b/guides/common/modules/proc_configuring-the-project-client-in-keycloak-wildfly.adoc
@@ -4,7 +4,9 @@
 = Configuring the {Project} client in {keycloak-wildfly}
 
 [role="_abstract"]
-Configure the {Project} client in {keycloak-wildfly} with valid redirect URIs and mappers.
+On the {keycloak-wildfly} side, you must configure the {Project} client with valid redirect URIs and mappers.
+This includes setting the appropriate client authentication mode, redirect URIs, and necessary mappers to support {ProjectWebUI} or Hammer CLI authentication.
+
 Perform these steps in the {keycloak} web UI.
 
 .Procedure
diff --git a/guides/common/modules/proc_enrolling-projectserver-in-your-freeipa-domain.adoc b/guides/common/modules/proc_enrolling-projectserver-in-your-freeipa-domain.adoc
@@ -1,7 +1,7 @@
 :_mod-docs-content-type: PROCEDURE
 
 [id="enrolling-{project-context}-server-in-freeipa-domain"]
-= Enrolling {ProjectServer} in a {FreeIPA} domain
+= Enrolling {ProjectServer} in your {FreeIPA} domain
 
 [role="_abstract"]
 Create a host entry for your {ProjectServer} system in the {FreeIPA} LDAP and configure the system to be a client in your {FreeIPA} domain.
diff --git a/guides/common/modules/proc_importing-the-katello-root-ca-certificate-using-cli.adoc b/guides/common/modules/proc_importing-the-katello-root-ca-certificate-using-cli.adoc
@@ -4,8 +4,8 @@
 = Importing the Katello root CA certificate using CLI
 
 [role="_abstract"]
-The first time you log in to {Project}, you might see a warning informing you that you are using the default self-signed certificate and you might not be able to connect this browser to {Project} until the root CA certificate is imported in the browser.
-Use the following procedure to locate the root CA certificate on {Project} and to import it into your browser.
+After the first login to {ProjectWebUI}, you might see a warning that you are using the default self-signed certificate.
+To ensure a successful connection, locate the root CA certificate on {Project} and import it into your browser truststore.
 
 .Prerequisites
 * Your {ProjectName} is installed and configured.
diff --git a/guides/common/modules/proc_importing-the-katello-root-ca-certificate-using-web-ui.adoc b/guides/common/modules/proc_importing-the-katello-root-ca-certificate-using-web-ui.adoc
@@ -4,8 +4,8 @@
 = Importing the Katello root CA certificate using {ProjectWebUI}
 
 [role="_abstract"]
-The first time you log in to {Project}, you might see a warning informing you that you are using the default self-signed certificate and you might not be able to connect this browser to {Project} until the root CA certificate is imported in the browser.
-Use the following procedure to locate the root CA certificate on {Project} and to import it into your browser.
+After the first login to {ProjectWebUI}, you might see a warning that you are using the default self-signed certificate.
+To ensure a successful connection, locate the root CA certificate on {Project} and import it into your browser truststore.
 
 .Prerequisites
 * Your {ProjectName} is installed and configured.
diff --git a/guides/common/modules/proc_logging-in-to-the-projectwebui-with-freeipa-credentials-in-chrome.adoc b/guides/common/modules/proc_logging-in-to-the-projectwebui-with-freeipa-credentials-in-chrome.adoc
@@ -4,7 +4,7 @@
 = Logging in to the {ProjectWebUI} with {FreeIPA} credentials in Chrome
 
 [role="_abstract"]
-You can use Chrome to log in to the {ProjectWebUI} with your {FreeIPA} credentials.
+Users with valid {FreeIPA} login credentials can log in to the {ProjectWebUI} from the Chrome browser.
 
 Use the latest stable Chrome browser.
 
diff --git a/guides/common/modules/proc_logging-in-to-the-projectwebui-with-freeipa-credentials-in-mozilla-firefox.adoc b/guides/common/modules/proc_logging-in-to-the-projectwebui-with-freeipa-credentials-in-mozilla-firefox.adoc
@@ -4,7 +4,7 @@
 = Logging in to the {ProjectWebUI} with {FreeIPA} credentials in Mozilla Firefox
 
 [role="_abstract"]
-You can use Mozilla Firefox to log in to the {ProjectWebUI} with your {FreeIPA} credentials.
+Users with valid {FreeIPA} login credentials can log in to the {ProjectWebUI} from the Mozilla Firefox browser.
 
 Use the latest stable Mozilla Firefox browser.
 
diff --git a/guides/common/modules/proc_logging-in-to-the-projectwebui.adoc b/guides/common/modules/proc_logging-in-to-the-projectwebui.adoc
@@ -4,7 +4,8 @@
 = Logging in to the {ProjectWebUI}
 
 [role="_abstract"]
-Use the {ProjectWebUI} to log in to {Project} for further configuration.
+The {ProjectWebUI} is a browser-based user interface that you can use to manage and monitor your {Project} infrastructure.
+To access {ProjectWebUI}, use your web browser to navigate to the {ProjectWebUI} login page and enter your credentials.
 
 ifdef::katello,orcharhino,satellite[]
 .Prerequisites
diff --git a/guides/common/modules/proc_refreshing-external-user-groups-for-ldap-using-cli.adoc b/guides/common/modules/proc_refreshing-external-user-groups-for-ldap-using-cli.adoc
@@ -4,6 +4,9 @@
 = Refreshing external user groups for LDAP using CLI
 
 [role="_abstract"]
+You can refresh external user groups manually.
+This is useful if you want to immediately update membership changes from your LDAP source.
+
 To set the LDAP source to synchronize user group membership automatically on user login, in the *Auth Source* page, select the *Usergroup Sync* option.
 If this option is not selected, LDAP user groups are refreshed automatically through a scheduled cron job synchronizing the LDAP Authentication source every 30 minutes by default.
 
diff --git a/guides/common/modules/proc_refreshing-external-user-groups-for-ldap-using-web-ui.adoc b/guides/common/modules/proc_refreshing-external-user-groups-for-ldap-using-web-ui.adoc
@@ -4,6 +4,9 @@
 = Refreshing external user groups for LDAP using {ProjectWebUI}
 
 [role="_abstract"]
+You can refresh external user groups manually.
+This is useful if you want to immediately update membership changes from your LDAP source.
+
 To set the LDAP source to synchronize user group membership automatically on user login, in the *Auth Source* page, select the *Usergroup Sync* option.
 If this option is not selected, LDAP user groups are refreshed automatically through a scheduled cron job synchronizing the LDAP Authentication source every 30 minutes by default.
 
diff --git a/guides/common/modules/proc_registering-project-as-a-client-of-keycloak.adoc b/guides/common/modules/proc_registering-project-as-a-client-of-keycloak.adoc
@@ -4,9 +4,9 @@
 = Registering {Project} as a client of {keycloak}
 
 [role="_abstract"]
-Users defined in {keycloak} can authenticate to {Project} by using the {ProjectWebUI} or Hammer CLI.
+To allow {keycloak} users to authenticate to {Project}, you must register {Project} as a client of {keycloak} on your {ProjectServer}.
+This configuration requires selecting and configuring the authentication method: {ProjectWebUI} access or Hammer CLI access.
 
-Choose one of these methods to enable in your {Project} deployment.
 Perform these steps on your {ProjectServer}.
 
 .Procedure
diff --git a/guides/common/modules/ref_example-settings-for-ldap-connections.adoc b/guides/common/modules/ref_example-settings-for-ldap-connections.adoc
@@ -4,7 +4,7 @@
 = Example settings for LDAP connections
 
 [role="_abstract"]
-When connecting your {Project} to LDAP, review the following examples of LDAP connections for various authentication sources.
+Examples of settings for LDAP connections show how you can configure the necessary LDAP fields for user accounts from various external authentication sources.
 
 .Example settings for Active Directory LDAP connections
 ====
diff --git a/guides/common/modules/ref_examples-ldap-filters.adoc b/guides/common/modules/ref_examples-ldap-filters.adoc
@@ -4,7 +4,7 @@
 = Example LDAP filters
 
 [role="_abstract"]
-When connecting your {Project} to LDAP, review the following examples of LDAP filters.
+Examples of LDAP filters show how you can set up appropriate search filters for connecting your LDAP server as an external authentication source for {Project}.
 
 .Example LDAP filters for allowing specific users to login
 ====
diff --git a/guides/common/modules/ref_overview-of-authentication-methods-in-foreman.adoc b/guides/common/modules/ref_overview-of-authentication-methods-in-foreman.adoc
@@ -4,4 +4,7 @@
 = Overview of authentication methods in {Project}
 
 [role="_abstract"]
+The authentication methods you can configure depend on the authentication source you are using.
+If the native authentication features provided by {Project} are not sufficient for your use case, use this information to decide which external authentication provider best suits your requirements.
+
 include::snip_table-authentication-methods.adoc[]
diff --git a/guides/doc-Configuring_User_Authentication/master.adoc b/guides/doc-Configuring_User_Authentication/master.adoc
@@ -10,7 +10,7 @@ endif::[]
 
 include::common/modules/ref_overview-of-authentication-methods-in-foreman.adoc[leveloffset=+1]
 
-include::common/assembly_accessing-server.adoc[leveloffset=+1]
+include::common/assembly_accessing-projectname-from-projectwebui.adoc[leveloffset=+1]
 
 include::common/assembly_configuring-kerberos-sso-with-freeipa-in-project.adoc[leveloffset=+1]
 
