Merge pull request #484 from permitio/filipermit/advanced-walkthroughs

Advanced Walkthroughs

docs/overview/advanced-authorization-queries.mdx

@@ -0,0 +1,119 @@
+---
+sidebar_position: 8
+title: Advanced Authorization Queries
+---
+
+Authorization plays a crucial role in managing secure access to your systems, and advanced queries can make this process more
+precise and powerful. In this guide, we’ll explore various methods to retrieve permissions, manage authorized users,
+and efficiently sync user data with Permit.
+
+import WhatsNext from "../../src/components/whats-next/WhatsNext";
+import TimelineStep from "../../src/components/timeline/TimelineStep";
+import TimelineWrapper from "../../src/components/timeline/TimelineWrapper";
+import Video from "../../src/components/video/Video";
+import CodeBlock from "../../src/components/code-block/CodeBlock";
+
+---
+
+To better understand the principles of the advanced authorization queries below, let's base all these below principles on an example.
+
+:::info
+**Alice** and **Bob** are users in a blogging application. Here’s how they interact with the blog posts:
+
+| **User** | **Blog Post(s)**         | **Permissions**                                     |
+| -------- | ------------------------ | --------------------------------------------------- |
+| Alice    | Blog Post 1, Blog Post 2 | **Edit**, **Read** (Full permissions for her posts) |
+| Bob      | Blog Post 3              | **Edit**, **Read** (Full permissions for his post)  |
+| Alice    | Blog Post 3              | **Read** (View only)                                |
+| Bob      | Blog Post 1, Blog Post 2 | **Read** (View only)                                |
+
+Let's put this to practice.
+:::
+
+:::tip **The Challenge**
+
+**Alice** and **Bob** need to query the system to:
+
+- Determine what permissions they have for specific blog posts.
+- Retrieve blog posts they are allowed to view or edit.
+- List the users who can perform actions on a given blog post.
+
+:::
+
+## Bulk Check
+
+The `permit.bulkCheck` function allows validating multiple permissions in a single call, ideal for situations where Alice or
+Bob needs to check permissions for multiple blog posts at once.
+
+### Example: Alice Checks Read Permissions
+
+Alice wants to know which blog posts she can read.
+
+<CodeBlock folderPath="/bulk-check" />
+
+Alice can read Blog Post 1, Blog Post 2, and Blog Post 3. The system returns this in one call, saving time and improving
+efficiency.
+
+You can read more about the bulk check [here](/how-to/enforce-permissions/bulk-check/).
+
+## FilterObjects
+
+Use the `permit.filterObjects` function to perform PDP-level filtering.
+
+In this method, the data is fetched from the DB, and then use the filterObjects function, which returns a subset of the objects
+passed to it based on the policy.
+
+The `permit.filterObjects` function retrieves only the blog posts that Alice or Bob is permitted to access. This is useful when fetching all posts from the database but only displaying the ones a user is authorized to see.
+
+### Example: Alice Filters Blog Posts
+
+Alice wants to retrieve the blog posts she can edit.
+
+<CodeBlock folderPath="/walkthroughs/authz-queries/filter" />
+
+The function returns Blog Post 1 and Blog Post 2, as Alice has edit permissions for these posts.
+
+## Get Authorized Users
+
+Use the `permit.authorized_users` function to retrieve a list of users authorized to perform a specific action on a resource.
+This function takes an action and resource as inputs and returns the authorized users along with their role assignments that
+granted access.
+
+### Example: Retrieve Authorized Users
+
+Bob wants to know who can read Blog Post 3.
+
+<CodeBlock folderPath="/walkthroughs/authz-queries/getAuthorizedUsers" />
+
+The system responds with:
+
+- Alice (has read permissions).
+- Bob (has edit and read permissions).
+
+You can read more about getting resource authorized users [here](/how-to/enforce-permissions/authorized-users).
+
+## Get User Permissions
+
+Use the `permit.GetUserPermissions` function to retrieve all user permissions across all registered resources and tenants.
+Simply provide a "User" as input, optionally filter by a list of tenants, and receive an object detailing the permissions
+and attributes for each assigned tenant.
+
+### Example: Bob’s Permissions
+
+<CodeBlock folderPath="/walkthroughs/authz-queries/getUserPermissions" />
+
+The system returns a list of Bob’s permissions:
+
+- Blog Post 1: Read
+- Blog Post 2: Read
+- Blog Post 3: Read, Edit
+
+You can read more about getting user permissions [here](/how-to/enforce-permissions/user-permissions).
+
+## What did you learn?
+
+:::tip FUN FACT
+Did you know? The concept of "authorization" dates back to ancient times when officials used wax seals on documents to verify
+permission. Today, we use advanced databases and APIs, but the goal remains the same—ensuring the right people have access to
+the right things.
+:::