Clean Managing Users section (#37)

* Clean Managing Users section

* Update user.adoc

* Update text

* Update text

server_admin/topics/users.adoc

@@ -1,18 +1,18 @@
 
 ==  Managing Users
 
-From the admin console, you have a wide range actions you can perform to manage users.
+From the admin console, you have a wide range of actions you can perform to manage users.
 
 include::users/proc-searching-user.adoc[leveloffset=2]
 include::users/proc-creating-user.adoc[leveloffset=2]
 include::users/proc-deleting-user.adoc[leveloffset=2]
 include::users/proc-configuring-user-attributes.adoc[leveloffset=2]
-include::users/credentials.adoc[leveloffset=2]
+include::users/ref-user-credentials.adoc[leveloffset=2]
 include::users/proc-setting-password-user.adoc[leveloffset=3]
 include::users/proc-creating-otp.adoc[leveloffset=3]
 include::users/con-required-actions.adoc[leveloffset=2]
-include::users/impersonation.adoc[leveloffset=2]
-include::users/user-registration.adoc[leveloffset=2]
-include::users/recaptcha.adoc[leveloffset=2]
-include::users/personal_data.adoc[leveloffset=2]
+include::users/con-user-impersonation.adoc[leveloffset=2]
+include::users/con-user-registration.adoc[leveloffset=2]
+include::users/proc-enabling-recaptcha-support.adoc[leveloffset=2]
+include::users/ref-personal-data-collected.adoc[leveloffset=2]
 

server_admin/topics/users/con-required-actions.adoc

@@ -1,3 +1,7 @@
+// Module included in the following assemblies:
+//
+// server_admin/topics/users.adoc
+
 [id="con-required-actions_{context}"]
 = Required Actions
 
@@ -14,7 +18,7 @@ Configure OTP::
    The user must configure a one-time password generator on their mobile device using either the Free OTP or Google Authenticator application.
 
 Verify Email::
-   The user must verify their email account.  An email will be sent to the user with a validation link that they must click.  Once this workflow is successfully completed, the user will be allowed to log in.
+   The user must verify their email account. An email will be sent to the user with a validation link that they must click. Once this workflow is successfully completed, the user will be allowed to log in.
 
 Update Profile::
    The user must update profile information, such as name, address, email, and phone number.

server_admin/topics/users/con-user-impersonation.adoc

@@ -0,0 +1,23 @@
+// Module included in the following assemblies:
+//
+// server_admin/topics/users.adoc
+
+[id="con-user-impersonation_{context}"]
+= User Impersonation
+
+An administrator with the appropriate permissions can impersonate a user. For example, if a user experiences a bug in an application, an administrator can impersonate the user to investigate or duplicate the issue. 
+
+Any user with the `impersonation` role in the realm can impersonate a user. 
+
+image:{project_images}/user-details.png[]
+
+* If the administrator and the user are in the same realm, then the administrator will be logged out and automatically logged in as the user being impersonated.  
+* If the administrator and user are not in the same realm, the administrator will remain logged in, and additionally will be logged in as the user in that user's realm.  
+
+In both instances, the browser redirects to the impersonated user's *User Account Management* page. 
+
+You can access the *Impersonate* button from the *Details* tab on the *Users* page.
+
+
+.Additional resources
+* For more information on assigning administration permissions, see the <<_admin_permissions,Admin Console Access Control>> chapter.

server_admin/topics/users/con-user-registration.adoc

@@ -1,4 +1,8 @@
-[id="assembly-user-registration_{context}"]
+// Module included in the following assemblies:
+//
+// server_admin/topics/users.adoc
+
+[id="con-user-registration_{context}"]
 = User Registration
 
 [role="_abstract"]

server_admin/topics/users/impersonation.adoc

@@ -1,18 +0,0 @@
-[id="con-impersonating_{context}"]
-= Impersonation
-
-It is often useful for an admin to impersonate a user.  For example, a user may be experiencing a bug in one of your applications and an admin may want to impersonate the user to see if they can duplicate the problem.  Admins with the appropriate permission can impersonate a user. 
-
-Any user with the `impersonation` role in the realm can impersonate a user. 
-
-image:{project_images}/user-details.png[]
-
-When impersonating, if the admin and the user are in the same realm, then the admin will be logged out and automatically logged
-in as the user being impersonated.  If the admin and user are not in the same realm, the admin will remain logged in, but additionally be logged in as the user in that user's realm.  In both cases, the browser will be redirected to the impersonated user's User Account Management page. 
-
-
-There are two locations an admin can initiate impersonation.  The first is on the `Users` list tab.
-
-
-.Additional resources
-For more information on assigning administration permissions, see the <<_admin_permissions,Admin Console Access Control>> chapter.

server_admin/topics/users/personal_data.adoc

@@ -1,19 +0,0 @@
-[[_personal_data]]
-
-= Personal data collected by {project_name}
-
-By default, {project_name} collects the following:
-
-* Basic user profile, such as email, firstname, and lastname
-
-* Basic user profile used for social accounts and references to the social account when using a social login
-
-* Device information collected for audit and security purposes, such as the IP address, operating system name, and browser name
-
-The information collected in {project_name} is highly customizable.  Be aware of the following guidelines when making customizations:
-
-* Registration and account forms could contain custom fields, such as birthday, gender, and nationality.  An administrator could configure {project_name} to retrieve that data from a social provider or a user storage provider such as LDAP.
-
-* {project_name} collects user credentials, such as password, OTP codes, and WebAuthn public keys. This information is encrypted and saved in a database, so it is not visible to {project_name} administrators. However, each type of credential can include non-confidential metadata that is visible to administrators such as the algorithm that is used to hash the password and the number of hash iterations used to hash the password.
-
-* With authorization services and UMA support enabled, {project_name} can hold information about some objects for which a particular user is the owner. For example, {project_name} can track that the user *john* is the owner of a photoalbum *album with animals* and a few photos called *lion picture* and *cow picture* in this album.

server_admin/topics/users/proc-configuring-user-attributes.adoc

@@ -1,7 +1,11 @@
+// Module included in the following assemblies:
+//
+// server_admin/topics/users.adoc
+
 [id="proc-configuring-user-attributes_{context}"]
 = Configuring user attributes
 
-User attributes provide a customized experience for each user. With user attributes, you can can create a personalized identity for each user in the console.
+User attributes provide a customized experience for each user. You can create a personalized identity for each user in the console by configuring user attributes.
 
 .Prerequisite
 * You are in the realm where the user exists.

server_admin/topics/users/proc-creating-otp.adoc

@@ -1,8 +1,14 @@
+// Module included in the following assemblies:
+//
+// server_admin/topics/users.adoc
+
 [id="proc_creating-otp_{context}"]
 = Creating an OTP
 
 [role="_abstract"]
-If OTP is conditional in your realm, the user must navigate to the *User Account Management* page to reconfigure a new OTP generator. If OTP is required, then the user must reconfigure a new OTP generator when logging in. You can use the following procedure if the user already has an OTP credential. Alternatively, you can send an email to the user that requests the user reset the OTP generator. 
+If OTP is conditional in your realm, the user must navigate to the *User Account Management* page to reconfigure a new OTP generator. If OTP is required, then the user must reconfigure a new OTP generator when logging in. You can use the following procedure if the user already has an OTP credential. 
+
+Alternatively, you can send an email to the user that requests the user reset the OTP generator. 
 
 .Prerequisite
 * You are logged in to the appropriate realm.

server_admin/topics/users/proc-creating-user.adoc

@@ -1,3 +1,7 @@
+// Module included in the following assemblies:
+//
+// server_admin/topics/users.adoc
+
 [id="proc-creating-user_{context}"]
 = Creating a user
 
@@ -11,20 +15,14 @@ You create users in the realm where you intend to have applications needed by th
 . In the admin console, click *Users* in the left menu.
 . Click *Add User* on the right side of the empty user list.
 . Enter the details for the new user.
-ifdef::standalone[]
 +
 NOTE: *Username* is the only required field.
 +   
-. Click *Save*. After saving the details, the *management page* for the new user is displayed.  
-endif::[]
-
-ifdef::api-management[]
-. Set `Email Verified` *ON* and click Save.
-. On the Credentials tab
-.. Set the password in both fields.
-.. Set `Temporary` *OFF* to avoid a password reset at the next login
+. Click *Save*. After saving the details, the *Management* page for the new user is displayed.  
+. Set *Email Verified* to *ON*.
+. Click *Save*.
+. In the *Credentials* tab, set the password in both fields.
+.. Set *Temporary* to *OFF* to avoid resetting the password during the next log in.
 .. Click *Reset Password*.
-.. When the pop-up window displays, click *Change password*.
+.. Click *Change Password*.
 .. Click *Save*.
-endif::[]
-

server_admin/topics/users/proc-deleting-user.adoc

@@ -1,3 +1,7 @@
+// Module included in the following assemblies:
+//
+// server_admin/topics/users.adoc
+
 [id="proc-deleting-user_{context}"]
 = Deleting a user
 

server_admin/topics/users/proc-enabling-recaptcha-support.adoc

@@ -0,0 +1,41 @@
+// Module included in the following assemblies:
+//
+// server_admin/topics/users.adoc
+
+[id="proc-enabling-recaptcha-support_{context}"]
+= Enabling reCAPTCHA Support
+
+[role="_abstract"]
+To safeguard registration against bots, {project_name} has integration with Google reCAPTCHA.
+
+Once reCAPTCHA is enabled, you can edit `register.ftl` in your login theme to configure the placement and styling of the reCAPTCHA button on the registration page. 
+
+.Procedure
+. Navigate to the link:https://developers.google.com/recaptcha/[Google Recaptcha website].
+. Create an API key to get your reCAPTCHA site key and secret. Note the reCAPTCHA site key and secret for future use in this procedure.
++
+NOTE: The localhost works by default. You do not have to specify a domain.
++
+. Navigate to the {project_name} admin console.
+. Click *Authentication* in the left menu. 
+. Click the *Flows* tab.  
+. Select *Registration* from the drop down menu.
+. Set the *reCAPTCHA* requirement to *Required* by clicking the appropriate radio button. This enables
+reCAPTCHA.  
+. Click *Actions* to the right of the reCAPTCHA flow entry.
+. Click the *Config* link to redirect to the config page.
+. Enter the reCAPTCHA site key generated from the Google reCAPTCHA website, on the config page. 
+. Enter the secret generated from the Google reCAPTCHA website, on the config page.
+. Authorize Google to use the registration page as an iframe.
++
+NOTE: {project_name} prevents websites from including a login page dialog in an iframe. This restriction is to prevent clickjacking attacks. You need to change the default HTTP response headers that is set in {project_name}.
++
+.. Click *Realm Settings* in the left menu. 
+.. Click the *Security Defenses* tab.  
+.. Enter `https://www.google.com` in the field for the *X-Frame-Options* header.
+.. Enter `https://www.google.com` in the field for the *Content-Security-Policy* header.
+
+
+[role="_additional-resources"]
+.Additional resources
+* For more information on extending and creating themes, see the link:{developerguide_link}[{developerguide_name}].

server_admin/topics/users/proc-enabling-terms-conditions.adoc

@@ -1,12 +1,16 @@
+// Module included in the following assemblies:
+//
+// con-required-actions.adoc
+
 [id="proc-enabling-terms-conditions_{context}"]
 = Enabling terms and conditions
 
-You can enable a required action that new users must accept the terms and conditions before logging into {project_name} for the first time.    
+You can enable a required action that new users must accept the terms and conditions before logging in to {project_name} for the first time.    
 
 .Procedure
 . Click the *Required Actions* tab.
 . Enable the *Terms and Conditions* action.
-. Edit the `terms.ftl` file in the _base_ login theme.  
+. Edit the `terms.ftl` file in the base login theme.  
 
 .Additional resources
-For more information on extending and creating themes, see the link:{developerguide_link}[{developerguide_name}]. 
+* For more information on extending and creating themes, see the link:{developerguide_link}[{developerguide_name}]. 

server_admin/topics/users/proc-enabling-user-registration.adoc

@@ -1,3 +1,7 @@
+// Module included in the following assemblies:
+//
+// con-user-registration.adoc
+
 [id="proc-enabling-user-registration_{context}"]
 = Enabling user registration
 

server_admin/topics/users/proc-registering-new-user.adoc

@@ -1,17 +1,21 @@
+// Module included in the following assemblies:
+//
+// con-user-registration.adoc
+
 [id="proc-registering-new-user_{context}"]
 = Registering as a new user
 
 [role="_abstract"]
-As a new user, you must complete a registration form to log in for the first time. You add profile information and a password to register.
+As a new user, you must complete a registration form to log in for the first time. You must add profile information and a password to register.
+
+.Registration Form
+image:{project_images}/registration-form.png[]
 
 .Prerequisite
 * User registration is enabled.
 
 .Procedure
 . Click the *Register* link on the login page. You are directed to the registration page.
-+
-.Registration Form
-image:{project_images}/registration-form.png[]
 . Enter the user profile information.
 . Enter the new password.
 . Click *Save*.

server_admin/topics/users/proc-searching-user.adoc

@@ -1,3 +1,7 @@
+// Module included in the following assemblies:
+//
+// server_admin/topics/users.adoc
+
 [id="proc-searching-user_{context}"]
 = Searching for a user
 

server_admin/topics/users/proc-setting-default-required-actions.adoc

@@ -1,16 +1,22 @@
+// Module included in the following assemblies:
+//
+// con-required-actions.adoc
+
 [id="proc-setting-default-required-actions_{context}"]
 = Setting default required actions
 
-You can determine what actions are required before the first login for any new user created. Once the user is created, these default required actions can be modified for that user.
+You can specify what actions are required before the first login of any new user. The default required actions can be modified after a user is created.
+
+You can set default required actions in two ways. You 
+can use the user registration link or the *Required Actions* tab.
 
 .Procedure
 
 .Using the user registration link 
-. Click *Add User* to navigate to the user list page.
-. Click the xref:assembly-user-registration_{context}[user registration] link on the login page.  
+. Click the *User Registration* link on the login page.  
 . Specify the default required actions. 
 
 .Using the Required Actions tab
 . Click *Authentication* in the left menu.
 . Click the *Required Actions* tab.
-. Click the checkbox in the *Default Action* column for one or more required actions. When a new user logs in for the first time, the selected actions must be executed.
+. Click the checkbox in the *Default Action* column for one or more required actions. When a new user logs in for the first time, the selected actions must be executed.

server_admin/topics/users/proc-setting-password-user.adoc

@@ -1,12 +1,17 @@
+// Module included in the following assemblies:
+//
+// server_admin/topics/users.adoc
+
 [id="proc-setting-password-user_{context}"]
 = Setting a password for a user
 
 [role="_abstract"]
 If a user does not have a password, or if the password has been deleted, the *Set Password* section is displayed.
+
 If a user already has a password, it can be reset in the *Reset Password* section.
 
 .Procedure
-. Type in a new password, in the *Set Password* section.
+. Type a new password, in the *Set Password* section.
 . Click *Set Password*.
 +
 NOTE: If *Temporary* is set to *ON*, the user must change the password at the first login. To allow users to keep the password supplied, set *Temporary* to *OFF.*  The user must click *Set Password* to change the password.
@@ -15,4 +20,4 @@ NOTE: If *Temporary* is set to *ON*, the user must change the password at the fi
 .. Navigate to the *Reset Actions* list.
 .. Click *Update Password* from the list.
 .. Click *Send Email*. The sent email contains a link that directs the user to the *Update Password* window.
-.. Optionally, you can set the validity of the email link. This is set to the default preset in the *Tokens* tab in the realm setiings.
+.. Optionally, you can set the validity of the email link. This is set to the default preset in the *Tokens* tab, in the realm settings.

server_admin/topics/users/proc-setting-required-actions.adoc

@@ -1,3 +1,7 @@
+// Module included in the following assemblies:
+//
+// con-required-actions.adoc
+
 [id="proc-setting-required-actions_{context}"]
 = Setting required actions
 

server_admin/topics/users/recaptcha.adoc

@@ -1,37 +0,0 @@
-[[_recaptcha]]
-
-= reCAPTCHA Support
-
-To safeguard registration against bots, {project_name} has integration with Google reCAPTCHA.
-To enable this you need to first go to link:https://developers.google.com/recaptcha/[Google Recaptcha Website]
-and create an API key so that you can get your reCAPTCHA site key and secret.
-(FYI, localhost works by default so you don't have to specify a domain).
-
-Next, there are a few steps you need to perform in the {project_name} admin console.
-Click the `Authentication` left menu item and go to the `Flows` tab.  Select the `Registration` flow from the drop down
-list on this page.
-
-.Registration Flow
-image:{project_images}/registration-flow.png[]
-
-
-Set the `reCAPTCHA` requirement to `Required` by clicking the appropriate radio button.  This will enable
-reCAPTCHA on the screen.  Next, you have to enter in the reCAPTCHA site key and secret that you generated at the Google reCAPTCHA Website.
-Click on the 'Actions' button that is to the right of the reCAPTCHA flow entry, then "Config" link, and enter in the reCAPTCHA site key and secret on this config page.
-
-.Recaptcha Config Page
-image:{project_images}/recaptcha-config.png[]
-
-
-The final step you have to do is to change some default HTTP response headers that {project_name} sets.  {project_name}
-will prevent a website from including any login page within an iframe.  This is to prevent clickjacking attacks.  You need to
-authorize Google to use the registration page within an iframe.  Go to
-the `Realm Settings` left menu item and then go to the `Security Defenses` tab.  You will need to add `\https://www.google.com` to the
-values of both the `X-Frame-Options` and `Content-Security-Policy` headers.
-
-.Authorizing Iframes
-image:{project_images}/security-headers.png[]
-
-Once you do this, reCAPTCHA should show up on your registration page.  You may want to edit _register.ftl_ in your login
-theme to experiment with the placement and styling of the reCAPTCHA button.  See the link:{developerguide_link}[{developerguide_name}]
-for more information on extending and creating themes.

server_admin/topics/users/ref-personal-data-collected.adoc

@@ -0,0 +1,22 @@
+// Module included in the following assemblies:
+//
+// server_admin/topics/users.adoc
+
+[id="ref-personal-data-collected_{context}"]
+= Personal data collected by {project_name}
+
+By default, {project_name} collects the following data:
+
+* Basic user profile data, such as the user email, first name, and last name.
+
+* Basic user profile data used for social accounts and references to the social account when using a social login.
+
+* Device information collected for audit and security purposes, such as the IP address, operating system name, and the browser name.
+
+The information collected in {project_name} is highly customizable. The following guidelines apply when making customizations:	
+
+* Registration and account forms can contain custom fields, such as birthday, gender, and nationality.  An administrator can configure {project_name} to retrieve data from a social provider or a user storage provider such as LDAP.
+
+* {project_name} collects user credentials, such as password, OTP codes, and WebAuthn public keys. This information is encrypted and saved in a database, so it is not visible to {project_name} administrators. Each type of credential can include non-confidential metadata that is visible to administrators such as the algorithm that is used to hash the password and the number of hash iterations used to hash the password.	
+
+* With authorization services and UMA support enabled, {project_name} can hold information about some objects for which a particular user is the owner.

server_admin/topics/users/ref-user-credentials.adoc

@@ -1,3 +1,7 @@
+// Module included in the following assemblies:
+//
+// server_admin/topics/users.adoc
+
 [id="ref-user-credentials_{context}"]
 = User Credentials
 
@@ -12,7 +16,7 @@ Position::
    The arrow buttons in the *Position* column allow you to shift the priority of the credential for the user. The topmost credential has the highest priority. The priority determines which credential is displayed first after a user logs in.
 
 Type::
-   This shows the type of the credential, for example *password* or *OTP*.
+   This column displays the type of credential, for example *password* or *OTP*.
 
 User Label::
    This is an assignable label to recognize the credential when presented as a selection option during login. It can be set to any value to describe the
@@ -28,5 +32,4 @@ Actions::
 
 You cannot configure other types of credentials for a specific user in the admin console; that task is the user's responsibility.
 
-You can delete the credentials of a user in the event a user loses an OTP device or if credentials have been compromised. You can only delete credentials of a user in the *Credentials* tab. 
-
+You can delete the credentials of a user in the event a user loses an OTP device or if credentials have been compromised. You can only delete credentials of a user in the *Credentials* tab.