1 files changed, 42 insertions, 0 deletions
diff --git a/doc/share/authz/EXPERIMENT.md b/doc/share/authz/EXPERIMENT.md
new file mode 100644
index 0000000..0460fe3
--- /dev/null
+++ b/doc/share/authz/EXPERIMENT.md
@@ -0,0 +1,42 @@
+## Experiments
+
+### Twirp + gRPC (AuthZ)
+
+This experiment exposes a gRPC endpoint that aligns with the [`Ability.allowed?(subject, permission, resource)`][1] interface from GitLab's declarative authorization logic.
+
+It demonstrates a headless authorization service that provides a low-latency decision point for other services to verify permissions.
+
+Actors in this experiment:
+
+* Headless authz service: A facade over GitLab’s existing declarative policies.
+* API (Resource Server in OAuth terms): A slimmed-down GitLab REST API that delegates authorization decisions to the authz service.
+
+### SAML, OIDC, OAuth
+
+This experiment showcases how a separate authx service can handle both authentication and authorization using standard protocols:
+
+* SAML & OIDC for authentication
+* OAuth for authorization
+
+Actors in this experiment:
+
+* Authx service: Acts as a SAML Identity Provider and an OAuth Authorization Server.
+* API: A slimmed-down GitLab REST API.
+
+### API Gateway
+
+This experiment explores a stateless authorization mechanism by integrating a policy DSL (such as [Casbin][3]) into a reverse proxy.
+Authorization decisions are made early in the request pipeline based on HTTP request headers and body content.
+
+### Sidecar Process
+
+This experiment demonstrates a sidecar approach for making authorization decisions within an nginx process.
+Inspired by [Open Policy Agent][4] deployments. This experiment:
+
+* Uses lua bindings in nginx to connect to a local client process.
+* The client process proxies requests to a gRPC based policy decision service.
+
+
+[1]: https://gitlab.com/gitlab-org/gitlab/-/blob/e1f6db024561e35462ac8d9f54b8f9678f6ed6ee/app/models/ability.rb#L73
+[3]: https://casbin.org/
+[4]: https://www.openpolicyagent.org/