realms

SUMMARY.adoc

@@ -9,6 +9,11 @@
  .. link:topics/how.adoc[How Does Security Work?]
  .. link:topics/concepts.adoc[Core Concepts and Terms]
  . link:topics/initialization.adoc[Server Initialization]
+ . link:topics/admin-console.adoc[Admin Console]
+ . link:topics/realms.adoc[Configuring Realms]
+ .. link:topics/master.adoc[The Master Realm]
+ .. link:topics/create.adoc[Creating a New Realm]
+ .. link:topics/ssl.adoc[Realm SSL Mode]
  . link:topics/admin-permissions.adoc[Master Admin Access Control]
  . link:topics/per-realm-admin-permissions.adoc[Per Realm Admin Access Control]
  . link:topics/client-registration.adoc[Client Registration]

topics/admin-console.adoc

@@ -0,0 +1,20 @@
+
+== {{book.project.name}} Admin Console
+
+The bulk of your administrative tasks will be done through the {{book.project.name}} Admin Console.
+You can go to the console url directly at http://localhost:8080/auth/admin/
+
+.Login Page
+image:../{{book.images}}/login-page.png[]
+
+Enter the username and password you created on the Welcome Page or the `add-user-keycloak` script.  This will bring you to the {{book.project.name}} Admin Console
+
+.Admin Console
+image:../{{book.images}}/admin-console.png[]
+
+The left pull down menu allows you to pick a realm you want to manage or to create a new one.  The right pull 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.
+
+

topics/overview/concepts.adoc

@@ -26,7 +26,7 @@ groups::
   inherit the attributes and role mappings that group defines.
 realms::
   A realm manages a set of users, credentials, roles, and groups.  A user belongs to and logs into a realm.  Realms are isolated from one another
-  and can only manage and authenticate the users that they manage
+  and can only manage and authenticate the users that they control.
 clients::
   Clients are entities that can request {{book.project.name}} to authenticate a user.  Most often, clients are applications and services that
   want to use {{book.project.name}} to secure themselves and provide a single sign-on solution.  Clients can also be entities that just want to request

topics/realms.adoc

@@ -0,0 +1,9 @@
+
+== Configuring Realms
+
+A realm manages a set of users, credentials, roles, and groups.  A user belongs to and logs into a realm.  Realms are isolated from one another
+and can only manage and authenticate the users that they control.  One {{book.project.name}} deployment can define, store, and manage as many realms
+as there is space for in the database.  When deciding whether to have one or more realms think about what kind of isolation you want to have for
+your users and applications.  For example, you might define a realm for the employees of your company and have a separate realm for your customers.
+You 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.  In this section you'll learn some basics about realm creation and configuration.

topics/realms/create.adoc

@@ -0,0 +1,24 @@
+[[_create-realm]]
+
+=== Create a New Realm
+
+Creating a new realm is very simple.
+Mouse over the top left corner drop down menu that is titled with `Master`.  If you are logged in the master realm
+this drop down menu lists all the realms created.  The last entry of this drop down menu is always `Add Realm`.  Click
+this to add a realm.
+
+.Add Realm Menu
+image:../../{{book.images}}/add-realm-menu.png[]
+
+This menu option will bring you to the `Add Realm` page.  Specify the realm name you want to define and click the `Create` button.
+Alternatively you and import a JSON document that defines your new realm.  We'll go over this in more detail in the
+<<fake/../../export-import.adoc#_export-import, Export and Import>> chapter.
+
+.Create Realm
+image:../../{{book.images}}/create-realm.png[]
+
+After creating the realm you are brought back to the main Admin Console page. The current realm will now be set to
+the realm you just created.  You can switch between managing different realms by doing a mouse over on the
+top left corner drop down menu.
+
+

topics/realms/master.adoc

@@ -0,0 +1,14 @@
+
+=== The Master Realm
+
+When you boot {{book.project.name}} for the first time a pre-defined realm is created for you.  This initial realm is called
+the _master_ realm and is the king of all realms.  Admins 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 are creating an account in the _master_ realm.
+Your initial login to the admin console will also be through the _master_ realm.
+
+It is recommended that you do not use the _master_ realm to manage the users and applications in your organization.  Keep the _master_ realm
+as a place for _super_ admins to create and manage the realms in your system.  This keeps things clean and organized.
+
+It is possible to disable the _master_ realm and define admin accounts at 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 <<fake/../../managing-realms.adoc#_managing_realms, Managing Realms>>
+chapter.

topics/realms/ssl.adoc

@@ -0,0 +1,29 @@
+
+=== SSL Mode
+
+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.
+
+WARNING:  {{book.project.name}} is not set up by default to handle SSL/HTTPS.
+          It is highly recommended that you either enable SSL on the {{book.project.name}} server itself or on a reverse proxy in front of the {{book.project.name}} server.
+
+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.
+
+.Login Tab
+image:../../{{book.images}}/login-tab.png[]
+
+The `Require SSL` option allows you to pick the SSL Mode you want.  Here is an explanation of each mode:
+
+external requests::
+  Users can interact with {{book.project.name}} so long as they stick to private IP addresses like `localhost`, `127.0.0.1`, `10.0.x.x`, `192.168.x.x`, and `172..16.x.x`.
+  If you try to access {{book.project.name}} from a non-private IP adress you will get an error.
+
+none::
+  {{book.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::
+  {{book.project.name}} requires SSL for all IP addresses.
+
+