Commit 5e1054b
Changed files (1)
README.md
@@ -1,100 +1,77 @@
-# Authx - Spike
+# Authx - Proof of Concept
-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.
+This repository explores various authentication and authorization workflows by introducing a separate authn/authz service.
+It serves as a proof of concept to illustrate potential workflows, not a production ready implementation.
-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:
+To keep the implementation accessible, external dependencies have been minimized, ensuring a clear reference for understanding key concepts, including:
-* 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.
+* SAML based authentication including IdP chaining to external identity providers
+* OIDC based authentication
+* OAuth endpoints with links to relevant RFCs for proper usage guidance
-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.
+Below is a recording of a SAML based service provider initiated login, displaying raw SAML XML to illustrate each step of the workflow.
## Identity Provider (SAML IdP)
-This is a tiny SAML Identity Provider for testing out interactions with
-a SAML Service Provider
+A minimal SAML Identity Provider for testing interactions with a SAML Service Provider.
1. Start the server:
-
- $ ruby ./bin/idp
-
-1. Use `http://localhost:8282/metadata.xml` as your SAML IdP Metadata url.
+ ```sh
+ ruby ./bin/idp
+ ```
+2. Use `http://localhost:8282/metadata.xml` as your SAML IdP metadata URL.
## Service Provider (SAML SP)
-This is a tiny SAML Service Provider for testing out interactions with a SAML Identity Provider (IdP)
+A minimal SAML Service Provider for testing interactions with a SAML Identity Provider.
1. Start the server:
+ ```sh
+ ruby ./bin/sp
+ ```
+2. Use `http://localhost:8283/metadata.xml` as your SAML SP metadata URL.
- $ ruby ./bin/sp
-
-1. Use `http://localhost:8283/metadata.xml` as your SAML SP Metadata url.
-
+## Experiments
-### Experiments
+### Twirp + gRPC (AuthZ)
-#### 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.
-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.
+It demonstrates a headless authorization service that provides a low-latency decision point for other services to verify permissions.
-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.
+Actors in this experiment:
-The two actors in this experiment are:
+* 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.
-* 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
-#### SAML, OIDC, OAuth
+This experiment showcases how a separate authx service can handle both authentication and authorization using standard protocols:
-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.
+* SAML & OIDC for authentication
+* OAuth for authorization
-2. OpenID Connect (authn) + OAuth (authz)
- * idp (with login pages)
- * gitlab
+Actors in this experiment:
-The two actors in this experiment are:
+* Authx service: Acts as a SAML Identity Provider and an OAuth Authorization Server.
+* API: A slimmed-down GitLab REST API.
-* 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
-#### 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.
-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
-#### 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:
-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.
+* 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
[2]: https://gitlab.com/gitlab-org/gitlab/-/tree/master/app/policies
+[3]: https://casbin.org/
+[4]: https://www.openpolicyagent.org/