Draft modelling hierarchies

astro/src/content/docs/get-started/core-concepts/types-and-relationships.mdx

@@ -0,0 +1,67 @@
+---
+title: Types And Their Relationships
+description: Learn about the core types in FusionAuth and how they interact to manage authentication and authorization.
+section: get started
+subcategory: core concepts
+---
+
+import Aside from 'src/components/Aside.astro';
+import TypesDiagram from 'src/diagrams/docs/extend/examples/modeling-hierarchies/types.astro'
+
+This overview summarizes all the FusionAuth types and how they relate. To avoid confusion with FusionAuth Applications, this guide refers to the service you provide your users as your "website", rather than an application, app, or service.
+
+The first set of FusionAuth types are **Tenants**, **Applications**, **Groups**, **Roles**, and **Users**. These types manage users logging in to an application. (Applications are sometimes called clients in other systems.)
+
+The second set of types are **Entity Types**, **Entities**, **Permissions**, and **Entity Grants**. These types were added to FusionAuth in 2021, after the original set of types in the previous paragraph. These types are used for machine-to-machine authentication, and provide a case-specific way to model things (entities), rather than organizations. 
+
+### Applications And Users
+
+A tenant in FusionAuth is a completely isolated environment, with its own set of users, applications, and configurations, independent of other tenants, even if they share the same FusionAuth instance.
+
+An application represents an organization, website, or service that a person (a user) logs in to. A user is associated with an application through a registration, and can be registered with many applications, or none. A user has personal data, an email address, and a variable quantity of custom data stored in JSON. 
+
+Applications have roles. A role is just a string. A registration can assign multiple roles to a user for an application. Your website can use a user's role in any way, such as authorizing a user to perform specific actions or choosing to ignore roles entirely.
+
+A group is a collection of users. A user can belong to multiple groups, so you can think of a group as a tag that can be applied to a user. A group can have many roles in many applications. If a user belongs to a group and is also registered with an application, they will automatically be granted any roles the group has in the application.
+
+Consider the example of a bank website with clients and employees. The bank website is an application in FusionAuth. The application has two roles, client and employee. Clients and employees are users, and each has a single registration in the bank application. Each registration gives a user the role of client, employee, or both.
+
+In this scenario, you could make groups called "client" and "employee", each assigned the corresponding roles in the application. Users could be added to either or both groups on registration with the application and roles would not need to be assigned manually. This approach would be useful if an application has many roles. 
+
+You could also use groups to tag users with certain attributes, such as VIP users.
+
+<Aside type="caution">
+Digital security usually involves three types: users, roles, and permissions. A user can have many roles, and roles can have many permissions. The advantages of not granting users permissions directly are:
+- You can add (or remove) permissions to a role and they automatically apply to every user in that role. You don't have to add a permission to many users individually.
+- A user can have multiple roles, each with its own permissions, and automatically inherits the combined permissions from all their assigned roles. You don't have to evaluate each user individually or define the exact combination of permissions they require.
+- Your website can rely on permissions to determine whether a user has rights to do something, without needing to map users through roles to permissions.
+
+Although FusionAuth does not currently support permissions, there is a GitHub feature request for this functionality. You can vote for it [here](https://github.com/FusionAuth/fusionauth-issues/issues/15).
+
+In the meantime, there are two workarounds you can implement:
+
+- Treat roles as permissions. In other words, instead of the "employee" role, make roles called "can edit clients", "can adjust salaries", and so on. When a user logs in with FusionAuth, your website will receive a list of exactly which "permissions" (roles) the user has. The trade-off of this approach is that the advantages of working with roles described above are lost.
+- Manage permissions in your website code. Keep the user and role associations in FusionAuth, but link roles to permissions in your website database, not in FusionAuth. When a user logs in with FusionAuth, your website queries the database to retrieve all permissions associated with their roles and applies them to the user. This treats FusionAuth more as an authentication system than an authorization system.
+</Aside>
+
+### Entities And Permissions
+
+An entity in FusionAuth is just a name, and can represent anything — a company, document, or refrigerator. The only functional aspect to an entity is that it can be used for machine-to-machine authentication with the client credentials OAuth flow. In this case, an entity usually represents a service. Entities are only available with a paid FusionAuth license.
+
+An entity has an entity type. The type of an entity cannot be changed once an entity is created. An entity type can have many permissions, which are also just strings.
+
+Both users and entities can be linked to entities by entity grants. An entity grant lists which permissions of an entity the linked user or entity has access to.
+
+For example, you could make an entity type called "Company", with entities like "ChangeBank" and "ChangeInsurance". The "ChangeBank" entity could have permissions like "ReadAccess" and "WriteAccess". An entity grant could link "ChangeInsurance" to "ChangeBank" and grant it "ReadAccess" permission. Similarly, an employee who is a user (as described in the previous section) could also have an entity grant providing "ReadAccess" to the "ChangeBank" entity.
+
+As with roles, permissions in FusionAuth have no functional meaning. They are merely strings passed to your website when a user logs in, and your website can use them in any way.
+
+### A Diagram Of All FusionAuth Types
+
+The diagram below illustrates the relationships between FusionAuth types as described in the previous sections, pairing each type name with its corresponding example object. Read the diagram from bottom to top to see who is a member of what, or who has what attributes.
+
+Note that entities and applications cannot be related, even if they represent the same physical company. Only users can have entity grants to entities.
+
+![Types diagram](/img/docs/extend/examples/modeling-hierarchy/mermaid1.webp)
+
+To reduce clutter, this diagram includes only two permission blocks. However, this simplification isn't quite accurate, as in FusionAuth, each entity grant would point to a separate permission — objects don't share permissions.

astro/src/diagrams/docs/extend/examples/modeling-hierarchies/company.astro

@@ -0,0 +1,42 @@
+---
+import Diagram from 'src/components/mermaid/FlowchartDiagram.astro';
+
+const { alt } = Astro.props;
+
+//language=Mermaid
+const diagram = `
+graph BT
+  n1[Change Corp]
+  n2(Change Bank)
+  n3(Change Insurance)
+
+  n4[/Operations/]
+  n5[/Finance/]
+  n6[/HR/]
+  n7[/Operations/]
+  n8[/Finance/]
+  n9[/HR/]
+
+  n10((Alice))
+  n11((Bob))
+  n12@{ shape: doc, label: "Passwords doc" }
+  n13@{ shape: doc, label: "Financial statements" }
+  n14@{ shape: doc, label: "HR manual" }
+
+  n2 --o n1
+  n3 --o n1
+  n4 --o n2
+  n5 --o n2
+  n6 --o n2
+  n7 --o n3
+  n8 --o n3
+  n9 --o n3
+
+  n10 --o n4
+  n11 --o n5
+  n12 --o n4
+  n13 --o n5
+  n14 --o n9
+`;
+---
+<Diagram code={diagram} alt={alt}/>

astro/src/diagrams/docs/extend/examples/modeling-hierarchies/hierarchy.astro

@@ -0,0 +1,76 @@
+---
+import Diagram from 'src/components/mermaid/FlowchartDiagram.astro';
+
+const { alt } = Astro.props;
+
+//language=Mermaid
+const diagram = `
+graph BT
+
+  subgraph Change Bank
+    direction BT
+    n0(("``*User*
+  **Alice**``"))
+    n1@{ shape: doc, label: "*Entity of type Document*
+  **Passwords doc**" }
+    nBank("``*Entity of type Company*
+  **Change Bank**``")
+    nOperationsToBanks("*Entity grant*")
+    nAliceCompany("*Entity grant*")
+    nAliceDepartment("*Entity grant*")
+    n16("``*Permission*
+    **ReadAccess**``")
+    n17("``*Permission*
+    **WriteAccess**``")
+    n18("``*Permission*
+    **IsMember**``")
+    nBankOperations[/"``*Entity of type Department*
+  **Operations**``"/]
+    n19("``*Permission*
+    **ReadAccess**``")
+    n20("``*Permission*
+    **WriteAccess**``")
+    n21("``*Permission*
+    **IsMember**``")
+    n22("*Entity grant*")
+    n23("``*Permission*
+    **ReadAccess**``")
+    n24("``*Permission*
+    **WriteAccess**``")
+  end
+
+  subgraph Change Insurance
+    direction BT
+    n5[/"``*Entity of type Department*
+  **Operations**``"/]
+    n6("*Entity grant*")
+    n3("``*Entity of type Company*
+  **Change Insurance**``")
+    n10("``*Permission*
+    **ReadAccess**``")
+    n11("``*Permission*
+    **WriteAccess**``")
+    n12("``*Permission*
+    **IsMember**``")
+    n13("``*Permission*
+    **ReadAccess**``")
+    n14("``*Permission*
+    **WriteAccess**``")
+    n15("``*Permission*
+    **IsMember**``")
+  end
+
+    n0 --o nAliceCompany & nAliceDepartment
+    n1 --o n22 & n23 & n24
+    nBank --o n16 & n17 & n18
+    n3 --o n10 & n11 & n12
+    nBankOperations --o nOperationsToBanks & n19 & n20 & n21
+    n5 --o n6 & n13 & n14 & n15
+    n6 --o n3 & n12
+    nOperationsToBanks --o nBank & n18
+    nAliceCompany --o nBank
+    nAliceDepartment --o nBankOperations  & n19 & n20
+    n22 --o nBankOperations & n21
+`;
+---
+<Diagram code={diagram} alt={alt}/>

astro/src/diagrams/docs/extend/examples/modeling-hierarchies/types.astro

@@ -0,0 +1,58 @@
+---
+import Diagram from 'src/components/mermaid/FlowchartDiagram.astro';
+
+const { alt } = Astro.props;
+
+//language=Mermaid
+const diagram = `
+graph BT
+  subgraph Users & Applications
+    n1("``*Application*
+    **Change Bank**``")
+    n2("``*User*
+    **Alice**``")
+    n3("``*Registration*``")
+    n4("``*Role*
+    **Employee**``")
+    n5("``*Role*
+    **Client**``")
+    n6("``*User*
+    **Bob**``")
+    n7("``*Registration*``")
+    n8("``*User*
+    **Eve**``")
+    n9("``*Registration*``")
+    n10("``*Group*
+    **VIP Clients**``")
+  end
+
+  subgraph Entities & Permissions
+    n11("``*Entity Type*
+    **Company**``")
+    n12("``*Entity*
+    **Change Bank**``")
+    n13("``*Permission*
+    **ReadAccess**``")
+    n14("``*Permission*
+    **WriteAccess**``")
+    n15("``*Entity*
+    **Change Insurance**``")
+    n16("``*Entity Grant*``")
+    n17("``*Entity Grant*``")
+  end
+
+  n1 --o n4 & n5
+  n2 --o n3 & n17
+  n3 --o n1 & n4
+  n6 --o n7 & n4
+  n7 --o n1 & n5
+  n8 --o n9 & n10
+  n9 --o n1
+  n10 --o n1 & n5
+  n12 --o n11 & n13 & n14
+  n15 --o n11 & n16
+  n16 --o n13 & n12
+  n17 --o n13 & n12
+`;
+---
+<Diagram code={diagram} alt={alt}/>