Add README, GitHub deploy action

Signed-off-by: Eric Searcy <[email protected]>

.github/workflows/license-header-check.yml → .github/workflows/license-header-check.yaml

@@ -15,11 +15,10 @@ jobs:
   license-header-check:
     name: License Header Check
     runs-on: ubuntu-latest
-    environment: dev
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       - name: Check License Headers
         run: |
           ./check-headers.sh

.github/workflows/publish.yaml

@@ -0,0 +1,23 @@
+# Copyright The Linux Foundation and each contributor.
+# SPDX-License-Identifier: MIT
+---
+name: Publish
+
+'on':
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  publish:
+    name: Publish
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-go@v4
+        with:
+          go-version: '1.20.x'
+      - uses: actions/checkout@v4
+      - uses: ko-build/[email protected]
+      - run: |
+          ko build --bare --platform linux/amd64,linux/arm64 -t latest -t ${{ github.sha }} --sbom spdx .

Dockerfile

@@ -1,3 +1,6 @@
+# Copyright The Linux Foundation and its contributors.
+# SPDX-License-Identifier: MIT
+
 FROM --platform=$BUILDPLATFORM golang:1.19-alpine AS builder
 
 # Set necessary environment variables needed for our image. Allow building to

README.md

@@ -0,0 +1,54 @@
+# auth0-cas-server-go
+
+## Overview
+
+This service was inspired by Auth0, through their example at https://github.com/auth0-samples/auth0-cas-server. It is a simple authentication redirector which wraps an OpenID Connect authentication flow to expose it as server implementing the Central Authentication Service (CAS) SSO protocol. The service leverages configuration stored within Auth0 client metadata, which it reads using a privileged connection to the Auth0 API, in order to emulate multiple different clients dynamically per login session.
+
+Notable differeces with this implementation:
+
+- Rewritten in Go, including OpenTelemetry instrumentation and multi-arch build outputs including SPDX SBOMs.
+- Supports several additional CAS protocol endpoints implementing multiple CAS versions.
+- Implements CAS single-logout.
+- Implements CAS "gateway mode" to test for authentication without prompting the user.
+- Supports both XML and JSON CAS response formats.
+- Allows for path wildcards and multiple, comma-separated CAS service definitions in `client_metadata.cas_service` configuration.
+
+## Linux Foundation specific changes
+
+The following hardcoded behavior is specific to the Linux Foundation's Auth0 environment:
+
+- LF-namespaced OIDC claims used for username and group attributes coming from IdP.
+- Custom CAS attributes: `uid`, `field_lf_*` and `profile_name_*` added to match our reference implementation.
+
+Porting these into a dynamic configuration system would be useful for generalizing this tool. For instance, a toml file could map upstream OIDC claims to both required CAS fields as well as optional additional CAS attributes, and provide per-attribute customization of the mb4-filtering feature.
+
+## Deploying and running the server
+
+You can pull the latest image from the GitHub Container Registry:
+
+```
+docker pull ghcr.io/linuxfoundation/auth0-cas-server-go:latest
+```
+
+Pinning your deployments to a release label (rather than ":latest") is recommended for production use.
+
+Please see `env-example` for a list of required and optional environment variables that can be used to configure the server. For local development, you can copy this file to `.env` and modify it to suit your needs.
+```
+
+## Auth0 client configuration
+
+To create a CAS-enabled Auth0 application, specify the follow settings:
+
+- Application Type: Regular Web Application
+- Allowed Callback URLs: `https://<your-cas-server>/cas/oidc_callback`
+- Allowed Logout URLs (optional): the CAS logout return URL of your application, if passed by the CAS client ("service" for v3 logout, or "url" for v2 logout).
+- Advanced -> Application Metadata: key "cas_service"; value will be one-or-more (comma-separated) URLs which must match the "service" attribute of the CAS login request. A `*` will match any subdomain or a single path component, while `**` matches anything (including `/`).
+- Advanced -> OAuth -> OIDC Conformant: Enabled
+
+## License
+
+Copyright The Linux Foundation and its contributors.
+
+This project's source code is licensed under the MIT License. A copy of the license is available in LICENSE.
+
+This project's documentation is licensed under the Creative Commons Attribution 4.0 International License (CC-BY-4.0). A copy of the license is available in LICENSE-docs.

env-example

@@ -0,0 +1,25 @@
+# Specify the "tenant" part of your Auth0 domain: {tenant}.auth0.com.
+AUTH0_TENANT=
+# Optionally, if your tenant has a custom domain configured, specify it here.
+#AUTH0_DOMAIN=example.auth0.com
+# The client ID and client secret of the application that you created in the
+# Auth0 dashboard for this service to connect as. It must be granted the scopes
+# "read:clients" and "read:client_keys" against the Auth0 v2 Management API.
+CLIENT_ID=
+CLIENT_SECRET=
+
+# Specify a random string to be used as the cookie secret. This allows the
+# service to securely store state in the client browser.
+COOKIE_SECRET=
+
+# For development reasons, if your service is not served over HTTPS, you must
+# enable insecure cookies.
+#INSECURE_COOKIE=1
+
+# Optional header to pull verified client IP from for logging (simple value only; no parsing of
+# X-Forwarded-For is supported.)
+#REMOTE_IP_HEADER=HTTP_X_FORWARDED_FOR
+
+# DD_ENV can be used with docker-compose to set the environment for the Docker
+# exporter of OpenTelemetry Collector.
+#DD_ENV=local

go.mod

@@ -3,7 +3,7 @@
 
 module github.com/linuxfoundation/auth0-cas-server-go
 
-go 1.19
+go 1.20
 
 require (
 	github.com/bmatcuk/doublestar/v4 v4.4.0