Converting Admin Console to Configuring Realms chapter including Realm Keys from Authentication chapter

server_admin/topics/admin-console.adoc

@@ -1,26 +1,16 @@
 
-== Working in the Admin Console
+== Configuring realms
 
-The bulk of your administrative tasks will be done through the {project_name} Admin Console.
-You can go to the console url directly at http://localhost:8080/auth/admin/
-
-.Login Page
-image:{project_images}/login-page.png[]
-
-Enter the username and password you created on the Welcome Page or the `add-user-keycloak` script in the bin directory.
-This will bring you to the {project_name} Admin Console.
-
-.Admin Console
-image:{project_images}/admin-console.png[]
-
-The left drop down menu allows you to pick a realm you want to manage or to create a new one.  The right drop down menu allows you to view your user account or logout.
-If you are curious about a certain feature, button, or field within the Admin Console, simply hover your mouse
-over any question mark `?` icon.  This will pop up tooltip text to describe the area of the console you are interested in.
-The image above shows the tooltip in action.
+Once you have an administrative account for the Admin Console, you can configure realms. A realm is a space where you manage objects, including users, applications, roles, and groups.  A user belongs to and logs into a realm.   One {project_name} deployment can define, store, and manage as many realms as there is space for in the database.
 
+include::realms/proc-using-admin-console.adoc[leveloffset=1]
 include::realms/master.adoc[leveloffset=2]
 include::realms/proc-creating-a-realm.adoc[leveloffset=2]
 include::realms/ssl.adoc[leveloffset=2][]
 include::realms/cache.adoc[leveloffset=2][]
 include::realms/email.adoc[leveloffset=2]
 include::realms/themes.adoc[leveloffset=2]
+include::login-settings.adoc[leveloffset=2]
+include::login-settings/forgot-password.adoc[leveloffset=2]
+include::login-settings/remember-me.adoc[leveloffset=2]
+include::realms/keys.adoc[]

server_admin/topics/initialization.adoc

@@ -1,7 +1,8 @@
 
+[id="creating-first-admin_{context}"]
 == Creating the first administrator
 
-After installing {project_name}, you need an administrator account that can act as a superuser with full permisions to manage all parts of {project_name}. With this account, you can log into the {project_name} Admin Console where you create realms and users and register applications that are secured by {project_name}. 
+After installing {project_name}, you need an administrator account that can act as a _super_ admin with full permisions to manage all parts of {project_name}. With this account, you can log into the {project_name} Admin Console where you create realms and users and register applications that are secured by {project_name}. 
 
 .Prerequisites
 

server_admin/topics/login-settings.adoc

@@ -1,4 +1,4 @@
 
-== Login Page Settings
+= Controlling login options
 
 {project_name} includes several built-in login page features.

server_admin/topics/login-settings/forgot-password.adoc

@@ -1,7 +1,7 @@
 
-=== Forgot Password
+== Enabling Forgot Password
 
-If you enable `Forgot Password`, users can reset their login credentials if they forget their password or lose their OTP generator. 
+If you enable `Forgot Password`, users can reset their login credentials if they forget their passwords or lose their OTP generator. 
 
 .Procedure
 . Click *Realm Settings* in the menu.
@@ -10,15 +10,15 @@ If you enable `Forgot Password`, users can reset their login credentials if they
 .Login Tab
 image:{project_images}/login-tab.png[Login Tab]
 +
-. Toggle the *Forgot Password* switch to *ON*.
-
+. Toggle *Forgot Password* to *ON*.
++
 A `forgot password` link displays in your login pages.
-
++
 .Forgot Password Link
 image:{project_images}/forgot-password-link.png[Forgot Password Link]
 
-Click this link to bring users where they can enter their username or email address and receive an email with a link to reset their credentials.
-
+. Click this link to bring users where they can enter their username or email address and receive an email with a link to reset their credentials.
++
 .Forgot Password Page
 image:{project_images}/forgot-password-page.png[Forgot Password Page]
 
@@ -26,7 +26,7 @@ The text sent in the email is configurable. See link:{developerguide_link}[{deve
 
 When users click the email link, {project_name} asks them to update their password, and if they have set up an OTP generator, {project_name} asks them to reconfigure the OTP generator.  Depending on security requirements of your organization, you may not want users to reset their OTP generator through email. 
 
-To change this behavior:
+To change this behavior, perform these steps:
 
 .Procedure
 . Click *Authentication* in the menu.

server_admin/topics/login-settings/remember-me.adoc

@@ -1,5 +1,5 @@
 
-=== Remember Me
+== Enabling Remember Me
 
 A logged-in user closing their browser destroys their session, and that user must log in again. You can set {project_name} to keep the user's login session open if that user clicks the _Remember Me_ checkbox upon login. This action turns the login cookie from a session-only cookie to a persistence cookie.
 

server_admin/topics/realms/cache.adoc

@@ -1,13 +1,16 @@
 [[_clear-cache]]
-= Clearing Server Caches
+= Clearing server caches
 
-{project_name} will cache everything it can in memory within the limits of your JVM and/or the limits you've configured
-it for.  If the {project_name} database is modified by a third party (i.e. a DBA) outside the scope of the server's REST APIs or Admin Console
-there's a chance parts of the in-memory cache may be stale.  You can clear the realm cache, user cache or cache of external public keys (Public keys of
- external clients or Identity providers, which {project_name} usually uses to verify signatures of particular external entity) from the Admin Console by going
-to the `Realm Settings` left menu item and the `Cache` tab.
+{project_name} caches everything it can in memory within the limits of your JVM and the limits you have configured.  If the {project_name} database is modified by a third party, such as a DBA, outside the scope of the server's REST APIs or Admin Console, parts of the in-memory cache could be stale.  You can clear the realm cache, user cache or cache of external public keys, such as Public keys of
+ external clients or Identity providers, which {project_name} may use to verify signatures of particular external entity.
 
+.Procedure
+
+. Click *Realm Settings* in the menu.
+
+. Click the *Cache* tab.
+
+. Click *Clear* for the cache you want to evict.
++
 .Cache tab
-image:{project_images}/cache-tab.png[]
-
-Just click the `clear` button on the cache you want to evict.
+image:{project_images}/cache-tab.png[Cache tab]

server_admin/topics/realms/email.adoc

@@ -1,40 +1,44 @@
 [[_email]]
 
-= Email Settings
+= Configuring email for a realm
 
-{project_name} sends emails to users to verify their email address, when they forget their passwords, or when an admin needs to
-receive notifications about a server event.
-To enable {project_name} to send emails you need to provide {project_name} with your SMTP server settings.
-This is configured per realm.  Go to the `Realm Settings` left menu
-item and click the `Email` tab.
+{project_name} sends emails to users to verify their email addresses, when they forget their passwords, or when an administrator needs to receive notifications about a server event. To enable {project_name} to send emails, you provide {project_name} with your SMTP server settings.
 
+.Procedure
+
+. Click *Realm Settings* in the menu.
+
+. Click the *Email* tab.
++
 .Email Tab
-image:{project_images}/email-tab.png[]
+image:{project_images}/email-tab.png[Email Tab]
 
+. Fill in the fields and toggle the switches as needed.
++
 Host::
-  `Host` denotes the SMTP server hostname used for sending emails.
+  *Host* denotes the SMTP server hostname used for sending emails.
 
 Port::
-  `Port` denotes the SMTP server port.
+  *Port* denotes the SMTP server port.
 
 From::
-  `From` denotes the address used for the `From` SMTP-Header for the emails sent.
+  *From* denotes the address used for the *From* SMTP-Header for the emails sent.
 
 From Display Name::
-  `From Display Name` allows to configure a user friendly email address aliases (optional). If not set the plain `From` email address will be displayed in email clients.
+  *From Display Name* allows to configure a user friendly email address aliases (optional). If not set the plain *From* email address will be displayed in email clients.
 
 Reply To::
-  `Reply To` denotes the address used for the `Reply-To` SMTP-Header for the mails sent (optional). If not set the plain `From` email address will be used.
+  *Reply To* denotes the address used for the *Reply-To* SMTP-Header for the mails sent (optional). If not set the plain *From* email address will be used.
 
 Reply To Display Name::
-  `Reply To Display Name` allows to configure a user friendly email address aliases (optional). If not set the plain `Reply To` email address will be displayed.
+  *Reply To Display Name* allows to configure a user friendly email address aliases (optional). If not set the plain *Reply To* email address will be displayed.
 
 Envelope From::
-  `Envelope From` denotes the https://en.wikipedia.org/wiki/Bounce_address[Bounce Address] used for the `Return-Path` SMTP-Header for the mails sent (optional).
+  *Envelope From* denotes the https://en.wikipedia.org/wiki/Bounce_address[Bounce Address] used for the *Return-Path* SMTP-Header for the mails sent (optional).
 
-As emails are used for recovering usernames and passwords it's recommended to use SSL or TLS, especially if the SMTP server is on an external network.
-To enable SSL click on `Enable SSL` or to enable TLS click on `Enable TLS`.
-You will most likely also need to change the `Port` (the default port for SSL/TLS is 465).
+Enable SSL and Enable StartTSL::
+  Toggle one of these switches to *ON* to support sending emails for recovering usernames and passwords, especially if the SMTP server is on an external network. You will most likely need to change the *Port* to 465, the default port for SSL/TLS.
 
-If your SMTP server requires authentication click on `Enable Authentication` and insert the `Username` and `Password`. The value of the `Password` field can refer a value from an external <<_vault-administration,vault>>.
+Enable Authentication::
+  Set this switch to *ON* if your SMTP server requires authentication. When prompted, supply the *Username* and *Password*. The value of the *Password* field can refer a value from an external <<_vault-administration,vault>>.
 

server_admin/topics/realms/keys.adoc

@@ -1,5 +1,5 @@
 [[realm_keys]]
-=== Realm Keys
+=== Configuring realm keys
 
 The authentication protocols that are used by {project_name} require cryptographic signatures and sometimes
 encryption.  {project_name} uses asymmetric key pairs, a private and public key, to accomplish this.
@@ -10,8 +10,12 @@ possible to regularly rotate the keys without any downtime or interruption to us
 
 When a realm is created a key pair and a self-signed certificate is automatically generated.
 
-To view the active keys for a realm select the realm in the admin console click on `Realm settings` then `Keys`. This
-will show the currently active keys for the realm.
+.Procedure
+. Select the realm in the Admin Console.
+. Click *Realm settings*.
+. Click *Keys*.
+. Click *Passive* to view passive keys.
+. Click *Disabled* to view disabled keys.
 
 To view passive or disabled keys select `Passive` or `Disabled`.
 A keypair can have the status `Active`, but still not be selected as the currently active keypair for the realm.
@@ -40,9 +44,15 @@ keys were created.
 
 ==== Adding a generated keypair
 
-To add a new generated keypair select `Providers` and choose `rsa-generated` from the dropdown. You can change the priority
-to make sure the new keypair becomes the active keypair. You can also change the `keysize` if you want smaller or larger keys (default is 2048,
-supported values are 1024, 2048 and 4096).
+.Procedure
+. Select the realm in the Admin Console.
+. Click *Realm settings*.
+. Click the *Keys* tab.
+. Click the *Providers* tab.
+. Click *Add keystore* and select *rsa-generated*.
+. Enter a number in the *Priority* field. This number determines if the new key pair becomes the active key pair.
+. Select a value for *keysize*.
+. Click *Save*.
 
 Click `Save` to add the new keys. This will generated a new keypair including a self-signed certificate.
 
@@ -54,29 +64,53 @@ you can edit the provider and new keys will be generated.
 To add a keypair and certificate obtained elsewhere select `Providers` and choose `rsa` from the dropdown. You can change
 the priority to make sure the new keypair becomes the active keypair.
 
-Click on `Select file` for `Private RSA Key` to upload your private key. The file should be encoded in PEM format. You
-don't need to upload the public key as it is automatically extracted from the private key.
+.Prerequisites
+* A private key file. The file must be PEM formatted.
 
-If you have a signed certificate for the keys click on `Select file` next to `X509 Certificate`. If you don't have one
- you can skip this and a self-signed certificate will be generated.
+.Procedure
+. Select the realm in the Admin Console.
+. Click *Realm settings*.
+. Click the *Keys* tab.
+. Click the *Providers* tab.
+. Click *Add keystore* and select *rsa*.
+. Enter a number in the *Priority* field. This number determines if the new key pair becomes the active key pair.
+. Click *Select file* beside *Private RSA Key* to upload the private key file.
+. If you have a signed certificate for your private key,  click *Select file* beside *X509 Certificate* to upload the certificate file. {project_name} autmatically generates a self-signed certificate if you do not upload a certificate.
+. Click *Save*.
 
 ==== Loading keys from a Java Keystore
 
 To add a keypair and certificate stored in a Java Keystore file on the host select `Providers` and choose `java-keystore`
 from the dropdown. You can change the priority to make sure the new keypair becomes the active keypair.
 
-Fill in the values for `Keystore`, `Keystore Password`, `Key Alias` and `Key Password` and click on `Save`.
+.Procedure
+. Select the realm in the Admin Console.
+. Click *Realm settings*.
+. Click the *Keys* tab.
+. Click the *Providers* tab.
+. Click *Add keystore* and select *java-keystore*.
+. Enter a number in the *Priority* field. This number determines if the new key pair becomes the active key pair.
+. Enter a value for *Keystore*.
+. Enter a value for *Keystore Password*.
+. Enter a value for *Key Alias*.
+. Enter a value for *Key Password*.
+. Click *Save*.
 
 ==== Making keys passive
 
-Locate the keypair in `Active` then click on the provider in the `Provider` column. This will take you to the
-configuration screen for the key provider for the keys. Click on `Active` to turn it `OFF`, then click on `Save`. The
-keys will no longer be active and can only be used for verifying signatures.
+.Procedure
+. Select the realm in the Admin Console.
+. Click Realm settings.
+. Click the *Keys* tab.
+. Click the *Active* tab.
+. Click the provider of the key you want to make passive.
+. Toggle *Active* to *OFF*.
+. Click *Save*.
 
 ==== Disabling keys
 
 .Procedure
-. Select the realm in the admin console.
+. Select the realm in the Admin Console.
 . Click Realm settings.
 . Click the *Keys* tab.
 . Click the *Active* tab.
@@ -87,19 +121,21 @@ keys will no longer be active and can only be used for verifying signatures.
 ==== Compromised keys
 
 {project_name} has the signing keys stored just locally and they are never shared with the client applications, users or other
-entities. However if you think that your realm signing key was compromised, you should first generate new keypair as described above and
+entities. However, if you think that your realm signing key was compromised, you should first generate new keypair as described above and
 then immediately remove the compromised keypair.
 
 Alternatively, you can delete the provider from the `Providers` table.
 
-==== Compromised keys
+.Procedure
+. Click *Clients* in the menu.
+. Click *security-admin-console*.
+. Click the *Revocation* tab.
+. Click *Set to now*.
+. Click *Push*.
 
-{project_name} has the signing keys stored just locally and they are never shared with the client applications, users or other
-entities. However if you think that your realm signing key was compromised, you should first generate new keypair as described above and
-then immediately remove the compromised keypair.
+Pushing the not-before policy ensures that client applications do not accept the existing tokens signed by the compromised key. The client application is forced to download new key pairs from {project_name} also so the tokens signed by the compromised key will be invalid.
 
-Then to ensure that client applications won't accept the tokens signed by the compromised key, you should update and push not-before policy for
-the realm, which is doable from the admin console. Pushing new policy will ensure that client applications won't accept the existing
-tokens signed by the compromised key, but also the client application will be forced to download new keypair from the {project_name}, hence
-the tokens signed by the compromised key won't be valid anymore. Note that your REST and confidential clients must have set `Admin URL`, so that
-{project_name} is able to send them the request about pushed not-before policy.
+[NOTE]
+====
+REST and confidential clients must set *Admin URL* so {project_name} can send clients the pushed not-before policy request.
+====

server_admin/topics/realms/master.adoc

@@ -1,22 +1,18 @@
 
-= The Master Realm
-When you boot {project_name} for the first time {project_name} creates a
-pre-defined realm for you. This initial realm is the _master_ realm. It is the
-highest level in the hierarchy of realms. Admin accounts in this realm have
-permissions to view and manage any other realm created on the server instance.
-When you define your initial admin account, you create an account in the
-_master_ realm. Your initial login to the admin console will also be via the
-_master_ realm.
+= The master realm
+In the Admin Console, two types of realms exist:
 
-We recommend that you do not use the _master_ realm to manage the users
-and applications in your organization. Reserve use of the _master_ realm for
-_super_ admins to create and manage the realms in your system. Following this
-security model helps prevent accidental changes and follows the tradition
+* `Master realm` - This realm was created for you when you first started {project_name}. It contains the administrator account you created at the first login.  Use the _master_ realm only to create and manage the realms in your system.
+
+* `Other realms` - These realms are created by the administrator in the master realm. In these realms, administrators manage the users in your organization and the applications they need. The applications are owned by the users.
+
+.Realms and applications
+image:../../../getting_started/images/master_realm.png[Realms and applications]
+
+Realms are isolated from one another and can only manage and authenticate the users that they control. Following this security model helps prevent accidental changes and follows the tradition
 of permitting user accounts access to only those privileges and powers necessary
 for the successful completion of their current task.
 
-It is possible to disable the _master_ realm and define admin accounts within
-each individual new realm you create. Each realm has its own dedicated Admin
-Console that you can log into with local accounts. This guide talks more about
-this in the <<_per_realm_admin_permissions, Dedicated Realm Admin Consoles>>
-chapter.
+.Additional resources
+
+* See <<_per_realm_admin_permissions, Dedicated Realm Admin Consoles>> if you want to disable the _master_ realm and define administrator accounts within any new realm you create. Each realm has its own dedicated Admin Console that you can log into with local accounts.

server_admin/topics/realms/proc-creating-a-realm.adoc

@@ -5,6 +5,10 @@
 [role="_abstract"]
 You create a realm to provide a management space where you can create users and give them permissions to use applications. At first login, you are typically in the _master_ realm, the top-level realm from which you create other realms.
 
+When deciding what realms you need, consider the kind of isolation you want to have for your users and applications.  For example, you might create a realm for the employees of your company and a separate realm for your customers.
+Your employees would log into the employee realm and only be able to visit internal company applications.  Customers would log into the customer
+realm and only be able to interact with customer-facing apps. 
+
 .Procedure
 
 . Point to the top of the left pane.
@@ -12,19 +16,19 @@ You create a realm to provide a management space where you can create users and
 . Click *Add Realm*.
 +
 .Add Realm Menu
-image:{project_images}/add-realm-menu.png[]
+image:{project_images}/add-realm-menu.png[Add Realm Menu]
 
 . Enter a name for the realm.
 
 . Click *Create*.
 +
 .Create Realm
-image:{project_images}/create-realm.png[]
+image:{project_images}/create-realm.png[Create Realm]
 
 The current realm is now set to the realm you just created.  You can switch between managing different realms by pointing to the top left corner to click *Select Realm*.
 
 ifdef::standalone[]
 [role="_additional-resources"]
 .Additional resources
-Alternatively you can import a JSON document that defines your new realm. For more detail, see the xref:assembly-exporting-importing_{context}[Export and Import] chapter.
+* Alternatively you can import a JSON document that defines your new realm. For more detail, see the xref:assembly-exporting-importing_{context}[Export and Import] chapter.
 endif::[]

server_admin/topics/realms/proc-using-admin-console.adoc

@@ -0,0 +1,30 @@
+== Using the Admin Console
+
+You configure realms and perform most administrative tasks in the {project_name} Admin Console.
+
+.Prerequisites
+
+* You need an administrator account.  See xref:creating-first-admin_{context}[Creating the first administrator].
+
+.Procedure
+
+. Go the the URL for the Admin Console.
++
+For example, for localhost, use this URL: http://localhost:8080/auth/admin/
++
+.Login Page
+image:{project_images}/login-page.png[Login Page]
+
+. Enter the username and password you created on the Welcome Page or the `add-user-keycloak` script in the bin directory.
+This action displays the Admin Console.
++
+.Admin Console
+image:{project_images}/admin-console.png[Admin Console]
+
+. Note the menus and other options that you can use:
++
+* Click the menu labeled *Master* to pick a realm you want to manage or to create a new one.
++
+* Click the top right list to view your account or log out.
++
+* Hover over a question mark *?* icon to show a tooltip text that describes that field. The image above shows the tooltip in action.

server_admin/topics/realms/ssl.adoc

@@ -1,27 +1,28 @@
 [[_ssl_modes]]
 
-= SSL Mode
+= Configuring SSL for a realm
 
-Each realm has an SSL Mode associated with it.  The SSL Mode defines the SSL/HTTPS requirements for interacting with the realm.
-Browsers and applications that interact with the realm must honor the SSL/HTTPS requirements defined by the SSL Mode or they
-will not be allowed to interact with the server.
+Each realm has an associated SSL Mode, which defines the SSL/HTTPS requirements for interacting with the realm.
+Browsers and applications that interact with the realm honor the SSL/HTTPS requirements defined by the SSL Mode or they cannot interact with the server.
 
 WARNING:  {project_name} generates a self-signed certificate the first time it runs.  Please note that self-signed certificates are not secure, and should only be used for testing purposes.  It is highly recommended that you install a CA-signed certificate on the {project_name} server itself or on a reverse proxy in front of the {project_name} server.  See the link:{installguide_link}[{installguide_name}].
 
-To configure the SSL Mode of your realm, you need to click on the `Realm Settings` left menu item and go to the `Login` tab.
+.Procedure 
+. Click *Realm Settings* in the menu.
 
+. Click the *Login* tab.
++
 .Login Tab
-image:{project_images}/login-tab.png[]
+image:{project_images}/login-tab.png[Login Tab]
 
-The `Require SSL` option allows you to pick the SSL Mode you want.  Here is an explanation of each mode:
+. Set *Require SSL* to one of the following SSL modes:
 
-external requests::
-  Users can interact with {project_name} without SSL so long as they stick to private IP addresses like `localhost`, `127.0.0.1`, `10.x.x.x`, `192.168.x.x`, and `172.16.x.x`.
-  If you try to access {project_name} without SSL from a non-private IP address you will get an error.
+* external requests::
+  Users can interact with {project_name} without SSL so long as they stick to private IP addresses such as `localhost`, `127.0.0.1`, `10.x.x.x`, `192.168.x.x`, and `172.16.x.x`.
+  If you try to access {project_name} without SSL from a non-private IP address, you will get an error.
 
-none::
-  {project_name} does not require SSL.  This should really only be used in development when you are playing around with things and don't want to bother
-  configuring SSL on your server.
-
-all requests::
+* none::
+  {project_name} does not require SSL.  This choice applies only in development when you are experimenting and do not plan to support this deployment.
+  
+* all requests::
   {project_name} requires SSL for all IP addresses.

server_admin/topics/realms/themes.adoc

@@ -1,44 +1,58 @@
 [[_themes]]
-= Themes and Internationalization
+= Configuring themes and internationalization
 
-Themes allow you to change the look and feel of any UI in {project_name}.  Themes are configured per realm.  To change
-a theme go to the `Realm Settings` left menu item and click on the `Themes` tab.
+For a given realm, you can change the appearance of any UI, including the language that appears, in {project_name} by using themes.
 
+.Procedure
+
+. Click *Realm Setting* in the menu.
+
+. Click the *Themes* tab.
++
 .Themes Tab
-image:{project_images}/themes-tab.png[]
-
-
-Pick the theme you want for each UI category and click `Save`.
+image:{project_images}/themes-tab.png[Themes Tab]
 
+. Pick the theme you want for each UI category and click *Save*.
++
 Login Theme::
   Username password entry, OTP entry, new user registration, and other similar screens related to login.
+
 Account Theme::
   Each user has an User Account Management UI.
+
 Admin Console Theme::
   The skin of the {project_name} Admin Console.
+
 Email Theme::
   Whenever {project_name} has to send out an email, it uses templates defined in this theme to craft the email.
 
+.Additional resources
+* The link:{developerguide_link}[{developerguide_name}] describes how to create a new theme or modify existing ones.
 
+== Enabling internationalization
 
-The link:{developerguide_link}[{developerguide_name}] goes into how to create a new themes or modify existing ones.
+Every UI screen is internationalized in {project_name}.  The default language is English, but you can choose which locales you want to support and what the default locale
+will be.
 
-== Internationalization
+.Procedure
 
-Every UI screen is internationalized in {project_name}.  The default language is English, but if you turn on the
-`Internationalization` switch on the `Theme` tab you can choose which locales you want to support and what the default locale
-will be.  The next time a user logs in, they will be able to choose a language on the login page to use for the login screens,
-User Account Management UI, and Admin Console.  The link:{developerguide_link}[{developerguide_name}] explains
-how you can offer additional languages. All internationalized texts which are provided by the theme can be overwritten
-by realm-specific texts on the `Localization` tab.
+. Click *Realm Settings* in the menu.
 
+. Click the *Theme* tab.
+
+. Set *Internationalization* to *ON*.
+
+The next time a user logs in, that user can choose a language on the login page to use for the login screens, Account Console, and Admin Console.
+
+.Additional resources
+
+* The link:{developerguide_link}[{developerguide_name}] explains
+how you can offer additional languages. All internationalized texts which are provided by the theme can be overwritten by realm-specific texts on the *Localization* tab.
 
 [[_user_locale_selection]]
 == User Locale selection
 
-In order to select the best possible locale for a user there is a locale selector provider that handles deciding what
-is the best locale on the information available. One thing to note here is that it is not always known who the user is.
-For this reason the previously authenticated users locale is remembered in a persisted cookie.
+A locale selector provider suggests the best locale on the information available. However, it is often unknown who the user is. For this reason, the previously authenticated user's locale is remembered in a persisted cookie.
 
 The logic for selecting the locale uses the first of the following that is available:
 
@@ -46,13 +60,13 @@ The logic for selecting the locale uses the first of the following that is avail
 * User profile - when there is an authenticated user and the user has a preferred locale set
 * Client selected - passed by the client using for example ui_locales parameter
 * Cookie - last locale selected on the browser
-* Accepted language - locale from `Accept-Language` header
+* Accepted language - locale from *Accept-Language* header
 * Realm default
-* If none of the above, fallback to English
+* If none of the above, fall back to English
 
 When a user is authenticated an action is triggered to update the locale in the persisted cookie mentioned earlier. If the
 user has actively switched the locale through the locale selector on the login pages the users locale is also updated at
 this point.
 
 If you want to change the logic for selecting the locale, you have an option to create custom `LocaleSelectorProvider`. For details, please refer to the
-link:{developerguide_link}#_locale_selector[{developerguide_name}].
+link:{developerguide_link}#_locale_selector[{developerguide_name}].