From 5e1054b3d4632383cc6422f341c789f30aa31dcb Mon Sep 17 00:00:00 2001 From: mo khan Date: Tue, 4 Mar 2025 17:11:18 -0700 Subject: docs: summarize the contents of the README --- README.md | 107 ++++++++++++++++++++++++-------------------------------------- 1 file changed, 42 insertions(+), 65 deletions(-) diff --git a/README.md b/README.md index d73f5cec..99138ffe 100644 --- a/README.md +++ b/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. ![SAML Login](./screencast.webm) ## 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/ -- cgit v1.2.3