Merge pull request #1421 from FusionAuth/segmenting-users

Segmenting users

Author: mooreds

site/docs/v1/tech/core-concepts/users.adoc

@@ -16,6 +16,7 @@ The User itself is easy enough to understand, it represents your end user, your
 * <<User Sessions>>
 * <<What Makes a User Active>>
 * <<User Search>>
+* <<Segmenting Users>>
 
 Here's a brief video covering some aspects of users:
 
@@ -32,7 +33,7 @@ Users have sessions in FusionAuth. Sessions are equivalent to refresh tokens. Th
 
 These appear in the administrative user interface under the [breadcrumb]#Sessions# tab (you may need to scroll if your screen is small):
 
-image::core-concepts/user-session.png[User session screen in the adminstrative user interface.,width=1200,role=bottom-cropped]
+image::core-concepts/user-session.png[User session screen in the administrative user interface.,width=1200,role=bottom-cropped]
 
 There are two primary types of sessions/tokens shown in this table:
 
@@ -140,3 +141,124 @@ The following screenshot shows an Elasticsearch JSON query being constructed to
 image::core-concepts/user-search-json-query.png[User Search with JSON Query.,width=1200]
 
 To learn more about the Elasticsearch search engine in general, view the link:/docs/v1/tech/core-concepts/search[search core concepts section].
+
+== Segmenting Users
+
+Often you want to segment or separate your users.
+You have four options to do so in FusionAuth.
+They each have different tradeoffs.
+The options are:
+
+* Tenants
+* Applications and Registrations
+* Groups
+* Entities and Grants
+
+//TODO table?
+
+=== Tenants
+
+Each FusionAuth tenant is a logical grouping of users, configuration and applications.
+Users are tenant scoped.
+This means a user with the same identifier (email, username, etc) in two different tenants is a different user.
+They can have different passwords, different identity provider links and different attributes.
+You can search for users across tenants using the User Search API.
+
+An example use case is a private label todo SaaS application, where you want a user to sign up for two or more different instances of your SaaS and not know that there is a shared identity store behind them.
+For example, richard@piedpiper.com can sign up for the Pied Piper Todo application and the Hooli Todo Application with the same email address, but different passwords, MFA methods and more.
+
+One issue is that if you have admin users, such as customer support representatives, which need cross-tenant access, you can't keep their accounts in sync.
+One option is to set up an administrative identity server, whether that is a second instance of FusionAuth, Google GSuite, or Azure AD.
+Have the customer service representatives authenticate with it.
+
+Learn more about link:/docs/v1/tech/core-concepts/tenants[Tenants].
+
+=== Applications and Registrations
+
+Applications in FusionAuth represent something you can log in to.
+They are tenant scoped.
+You associate a user with an application via a registration.
+You may also optionally associate one or more roles with each user's registration.
+
+An example use case is a single company, where you have a forum, a todo application and an accounting application.
+If you have three users, Richard, Monica and Jared, you can grant Richard access to all three applications, Monica access to the forum and todo applications, and Jared access to the accounting application.
+
+Prohibit a user from logging into an application for which they are not registered by checking the claims in the token or enabling the [field]#Require registration# setting for the application.
+
+Applications also may have associated Identity Providers, such as Google or OIDC providers.
+When so configured, a user may log in to an application with the Identity Provider.
+
+Every user object contains an array of application registrations.
+You can search for all users with a given registration.
+
+Learn more about link:/docs/v1/tech/core-concepts/applications[Applications].
+
+=== Groups
+
+Groups are a way to group users in FusionAuth.
+They are tenant scoped.
+They may have application roles associated with them.
+Users with a registration for an application as well as a group membership will assume those roles upon login.
+
+Group membership is boolean in nature.
+A user is either in a group or out of a group.
+
+An example use case is a forum moderators group.
+The forum application can get the group memberships of any user.
+If the user is a member of the moderators group, the application can provide a 'flag' button on the forum software.
+
+Every user object contains an array of group memberships.
+You can search for all users with a given group memberships.
+
+One issue is that to get the group names of memberships for a user, you must use FusionAuth's proprietary APIs.
+Group names are not included in the user object.
+
+Learn more about link:/docs/v1/tech/core-concepts/groups[Groups].
+
+=== Entities and Grants
+
+Entities and grants allow you to model fine grained permissions in a flexible manner.
+Entities are things, while grants are expressions of permissions granted to a user or thing to another thing.
+Entities have configurable permissions.
+Entities are a good fit when you have users that may need access to different assets which can't be easily modeled as applications.
+
+An example use case which could be modeled using entities is GitHub organizations.
+A user can belong to zero or more GitHub organizations and have different access levels in each one.
+But a user logs in to GitHub, not to a GitHub organization.
+Additionally, permissions will vary between organizations.
+A user may be an admin in one GitHub organization and have read-only access in another one.
+To implement this, you'd represent each GitHub organization as an entity in FusionAuth, and grant users permissions to each organization of which they are a member.
+
+It is very common to have an interstitial page when using entities.
+(This page is custom built and is not provided by FusionAuth.)
+The user logs in to an application, and is then presented with a list of entities to which they've been granted permissions.
+The user selects an entity and then acts within the confines of that entity.
+
+You can search for all users granted access to a given entity.
+You can search for all entities for which a user has a grant.
+
+One issue is that to search for grants on a user, you must use FusionAuth's proprietary APIs.
+Additionally, since entities cannot be 'logged into', they don't have any relationship with external Identity Providers.
+
+Learn more about link:/docs/v1/tech/core-concepts/entity-management[Entities and Grants].
+
+==== Entities Compared to Applications
+
+Entities, grants and permissions are analogous to applications, registrations and roles, but you can't log into an entity.
+
+Entities may also be useful if you have two or more applications in FusionAuth, but you want to group access in an orthogonal way while still allowing users to assume different roles.
+
+Suppose you have a point of sales application and a scheduling application for your retail chain.
+You have ten stores.
+You want to allow employees to log in to each of these applications, but you want to limit them to access only stores where they are currently working.
+But if they move between stores to cover for a shift or because of a transfer, you want to handle that use case as well.
+This means you can't use tenants to model stores.
+
+You could model the point of sales and scheduling applications as applications.
+Each store would be an entity, and after the user has logged into an application, you'd show them the stores to which they'd have access.
+
+You could also provide different roles in different stores. 
+The scheduling software could know that Richard would have access to the scheduling application as a manager for store A but only as an employee for store B.
+
+If you were to model this using only applications, you'd have to have twenty applications in FusionAuth (two for each store) and keeping those configurations synchronized might be difficult.
+And if you added more applications or stores, you'd face a combinatorial explosion of applications.