Commit 281f540

@@ -1,16 +1,22 @@
-# Spike
+# Authx - Spike
 
-![screencast](./screencast.webm)
+This repository contains a proof of concept that attempts to illustrate several
+different types of workflows that could exist by introducting a separate authn/authz service.
 
+The code in this repository is meant to be used to help express ideas and is not
+meant for production usage. I chose not to introduce too many external libraries
+in this repository to ensure that we have reference implementation of code that
+we can use as guidance for understanding concepts like:
 
-1. Twirp + GRPC (authz)
-  * idp (headless): provide a thrift/grpc endpoint that is the equivalent of `Ability.allowed?(subject, permission, resource)`
-  * gitlab
-2. OpenID Connect (authn) + OAuth (authz)
-  * idp (with login pages)
-  * gitlab
-3. API Gateway: using golang reverse proxy and one of the new policy dsl's
-4. OPA agent style side car process using declarative policy
+* SAML based Authn workflow (+IdP chaining to external Identity Providers)
+* OIDC based Authn workflow
+* OAuth endpoints with links to RFC's to provide guidance on how these endpoints
+  are meant to be used.
+
+Below is a recording of a SAML based service provider initiated login with the
+raw SAML XML printed out to illustrate each step of the workflow.
+
+![SAML Login](./screencast.webm)
 
 ## Identity Provider (SAML IdP)
 
@@ -32,3 +38,63 @@ This is a tiny SAML Service Provider for testing out interactions with a SAML Id
     $ ruby ./bin/sp
 
 1. Use `http://localhost:8283/metadata.xml` as your SAML SP Metadata url.
+
+
+### Experiments
+
+#### Twirp + GRPC (authz)
+
+The first experiment is to expose an gRPC endpoint that matches the [`Ability.allowed?(subject, permission, resource)`][1]
+interface that is the entrypoint into the declarative policies authz logic in
+the GitLab monolith.
+
+This experiment is meant to showcase a headless authz service that provides a
+low latency interface for other services to connect to in order to make an
+authorization decision. This headless service is the policy decision point that
+policy enforcement points can delegate to in order to check if a particular
+action is authorized.
+
+The two actors in this experiment are:
+
+* Headless authz service: This service is a facade over the existing declarative
+  policies found in the [`gitlab-org/gitlab`][2] codebase.
+* API (resource server in OAuth language): This service represents a slimmed
+  down version of the GitLab REST API that has been updated to delegate to the
+  authz service in order to execute authz enforcement.
+
+#### SAML, OIDC, OAuth
+
+This experiment illustrates how a separate authx service can provide both authn
+and authz in a standards compliant way. It utilizes SAML and OIDC as the
+mechanisms for authenticating a session and it relies on OAuth for making
+authorization decisions.
+
+2. OpenID Connect (authn) + OAuth (authz)
+  * idp (with login pages)
+  * gitlab
+
+The two actors in this experiment are:
+
+* Authx service: This service acts as an Identity Provider in a SAML based
+  transaction and the Authorization Server in a OIDC/OAuth workflow.
+* API: This service represents a slimmed down version of the GitLab REST API.
+
+#### API Gateway
+
+This experiment introduces a separate policy domain specific language that can
+be used to make authz decision as early in the request pipeline as possible. It
+uses a reverse proxy with integration into a policy DSL (such as casbin) to make
+authz decisions solely based on the contents of the HTTP request (headers +
+body). It is stateless and proxies requests to backend services.
+
+#### Sidecar Process
+
+This experiment attempts to build a sidecar process that connects to a gRPC
+endpoint defined in an earlier experiment to showcase how we can make authz
+decisions from the nginx process while utilizing a single policy decision point.
+This example runs nginx with a lua binding to connect via a unix socket to a
+client process the proxies requests to the gRPC endpoint. It is inspired by the
+Open Policy Agent style of deployment.
+
+[1]: https://gitlab.com/gitlab-org/gitlab/-/blob/e1f6db024561e35462ac8d9f54b8f9678f6ed6ee/app/models/ability.rb#L73
+[2]: https://gitlab.com/gitlab-org/gitlab/-/tree/master/app/policies