Hi all,
I wanted to share my thought process of fitting KC against a very common use case.
Perhaps this would lead to better docs (so other can avoid this process or ask the same questions in this forum)

Use case:
Build a fictious "Utlimate Produce Store Web App" SaaS application for produce store management. Basically,
a produce store owner wants to register his/her store, link it to credit ard/bank account,
and add other staffers under the store registration. It boils down to two roles per store registartion:
1. admins - can add/delete staffers, store credit cards and everything a staffer can do.
2. staffers - limited store management activites.

Here is how I look at KC for utilizing it for this kind of SaaS app:

1. Map each produce store to a separate Realm. Register store admin users with "manage users" realm-level built-in role.
==================
A. pros
   a1 Leverage almost all of UI of KC
   a2 there is some "multi-tenancy" section of the documentation, but it is not clear if the one can dynamically assign/remove realm to a WAR app.  
B. cons
   b1 Nothing in the KC suggest that realms can be created dynamically. There is lots of xml/json configurations that go into specific places, and with each realm
   b2 WAR app files need to have the realm hard-coded in the web.xml
   b2 No attributes for realms? There are attributes for users and groups, but not for clients,roles,realms. (Someone explain the thought process here...)
   b3 How does KC scales with 1000s of realms?
   b4 Realms can not share users (A store staffer can work at two stores, I suppose, and a manager can have several stores)
   b5 Produce store manager will see "user federation" in the menu that would confuse them a lot!
  
  
2. Map each produce store to a KC client. All under the same realm "Utlimate Produce Store Web App"
===================
A. pros
   a1. It looks like clients can be created dynamically without json/xml configuration.
   a2. There are "cleint templates" which can make the process even simpler.
   a3. The admin console has search for clients, which suggests that this approach may scale - e.g. having 1000s of clients
   a4. Via the KC Events, one can detect when a new user registers under the realm and automatically create a client(produce store) for him/her.
   a5. A user can work in one or more stores (clients)
B. cons
   b1. There is no admin console at the client level in KC to be leveraged. This would need to be developed from scratch.
   b2. Clients do not have attributes. A workaround is to create a surrogate group in each client, solely for the purpose of storing produce store attributes (e.g credit card)
   b3. UI for adding/removing people to store registration needs to be developed from scratch. Nothing out-of-the-box.

  
3. Map each produce store to a group. Have a single client "Utlimate Produce Store Web App" under a bogus realm.
====================
A. pros
   a1. Groups have attributes. There can even be a hierarchy of them for more sophisticated arrangements.
   a2. Each store can have specific group hierarchy.
   a3. A user can work in one or more stores (clients)
B. cons
   b1. Virtually no usefull KC out-of-the-box UI for managing groups on per-group bases. You cant really give store owners realm-level priviledges
   b2. The realm admin console does not look like optimized for serch managaement of large number of groups
  
I do not know if I am on the right track and would have to spend significant time reading KC docs and Java sources to figure out
A/ if KC is a good choice, and B/ if so, which appoach is best for such a common SaaS business case.  

The point here is that the KC documentation should discuss such business scenarious a lot more and help solution architects decide
quickly the 2 most important questions:
- Is KC right for my web/mobile app needs.
- If so, how do I map KC concepts to my business domain withouth making costly mistakes.

/Hristo Stoyanov