Merge pull request #2 from jinnatar/push-knqpoqnvzpnw

jinnatar · web-flow · commit 503b7982df62 · 2025-02-20T10:26:05.000+02:00
Updates to get a release out
diff --git a/.github/workflows/publish-image.yml b/.github/workflows/publish-image.yml
@@ -1,7 +1,10 @@
 ---
 name: Docker image
 
-on: push
+on:
+  pull_request:
+  release:
+    types: [published]
 
 env:
   REGISTRY: ghcr.io
@@ -18,17 +21,22 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
 
-      - name: Get the release channel
-        id: get_channel
+      - name: Infer image tags
+        id: get_tags
         shell: bash
         run: |
-          if [[ "$GITHUB_REF" == 'refs/heads/main' ]]; then
-            echo "channel=latest" >> $GITHUB_OUTPUT
-            echo "version=main_${GITHUB_SHA::6}" >> $GITHUB_OUTPUT
-          elif [[ "$GITHUB_REF" == "refs/heads/"* ]]; then
-            echo "version=${GITHUB_REF/refs\/heads\//}_${GITHUB_SHA::6}" >> $GITHUB_OUTPUT
-          elif [[ "$GITHUB_REF" == "refs/tags/"* ]]; then
-            echo "channel=${GITHUB_REF/refs\/tags\//}" >> $GITHUB_OUTPUT
+          if [[ "$GITHUB_EVENT_NAME" == "release" ]]; then
+            # We believe tags from releases
+            echo "version=${GITHUB_REF_NAME}" >> $GITHUB_OUTPUT
+            # But also give a more stable git relevant tag
+            echo "hash=main_${GITHUB_SHA::6}" >> $GITHUB_OUTPUT
+            if [[ "$GITHUB_REF" != "refs/tags/"*"-pre"* ]]; then
+              # Only tag latest for non-prereleases
+              echo "channel=latest" >> $GITHUB_OUTPUT
+            fi
+          elif [[ "$GITHUB_REF" == "refs/pull/"* ]]; then
+            # Tag PRs only by PR number & branch to pollute registry less on force pushes
+            echo "version=pr${GITHUB_REF_NAME/\/merge}_${GITHUB_HEAD_REF}" >> $GITHUB_OUTPUT
           fi
 
       - name: Extract metadata (tags, labels) for Docker
@@ -37,8 +45,9 @@ jobs:
         with:
           images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
           tags: |
-            type=raw,value=${{ steps.get_channel.outputs.channel }}
-            type=raw,value=${{ steps.get_channel.outputs.version }}
+            type=raw,value=${{ steps.get_tags.outputs.hash }}
+            type=raw,value=${{ steps.get_tags.outputs.channel }}
+            type=raw,value=${{ steps.get_tags.outputs.version }}
 
       - name: Log in to the Container registry
         uses: docker/login-action@v2
diff --git a/Dockerfile b/Dockerfile
@@ -1,6 +1,13 @@
 FROM python:3.12-alpine
 
-# runtime dependencies
+ENV SATOSA_VERSION="8.5.1"
+
+# While SATOSA now has a release with modern OIDC support, it's dependency idpyoidc has not yet
+# made a release that allows ES256. Ergo, we pull that dep in from the branch that most
+# closely matches where they usually cut releases from.
+# More context: https://github.com/IdentityPython/idpy-oidc/issues/114
+ENV IDPYOIDC_REF="git+https://github.com/IdentityPython/idpy-oidc@issuer_metadata"
+
 # Run as uid:gid 999:999 to avoid conferring default UID 1000 permissions to key material
 RUN set -eux; \
 	delgroup ping ; \
@@ -11,29 +18,27 @@ RUN set -eux; \
 		jq \
 		libxml2-utils \
 		xmlsec \
-		git \
-	; \
-	pip install --no-cache-dir \
-		yq \
-	;
+    git  # Only needed until we have a non-git idpyoidc ref
 
 
-# Install SATOSA from git latest since the latest release 8.4.0 lacks idpy_oidc_backend which is required for PKCE
-# Also install ES256 compatible idpyoidc from fork while not fixed upstream: https://github.com/IdentityPython/idpy-oidc/issues/110
-RUN set -eux; \
-	pip install --no-cache-dir \
-		'satosa[idpy_oidc_backend] @ git+https://github.com/IdentityPython/SATOSA' \
-		'idpyoidc @ git+https://github.com/jinnatar/idpy-oidc@sign-algo-verify' \
-	; \
-	mkdir /etc/satosa; \
-	chown -R satosa:satosa /etc/satosa
+RUN pip install --no-cache-dir \
+yq \
+"satosa[idpy_oidc_backend]==${SATOSA_VERSION}" \
+"idpyoidc @ ${IDPYOIDC_REF}"
 
+RUN	mkdir /etc/satosa && chown -R satosa:satosa /etc/satosa
 WORKDIR /etc/satosa
 
 # Preload bespoke ENV configurable config
 COPY *.yaml /etc/satosa
+# Preload dummy XML metadata
+COPY dummy-metadata.xml /etc/satosa
+
+# Add an entrypoint so we can use ENV for gunicorn args
+ENV LOG_LEVEL="INFO"
+ENV LISTEN_ADDR="0.0.0.0:80"
+COPY entrypoint.sh /entrypoint.sh
+ENTRYPOINT ["/entrypoint.sh"]
 
-ENTRYPOINT ["gunicorn"]
 EXPOSE 80
 USER satosa:satosa
-CMD ["-b0.0.0.0:80","satosa.wsgi:app"]
diff --git a/README.md b/README.md
@@ -1,24 +1,28 @@
 # SATOSA based SAML to Kanidm OIDC proxy
 
 i.e. How to connect legacy web apps that only support SAML to be backed by Kanidm OIDC. While the configs in this repo can be educational for rolling your own SATOSA setup, an opinionated ENV configurable container image is also provided.
+This example on purpose only supports a 1:1 proxy config where a single SAML supporting web service auths via a single OIDC endpoint. To limit blast radius, just deploy multiple if you have multiple SAML-only services.
 
-> [!CAUTION]
-> This is an early version that only supports a 1:1 proxy config where a single SAML supporting web service auths via a single OIDC endpoint.
-> The intent is to morph into a "v2" that allows a dynamic mapping of multiple systems to multiple OIDC endpoints via a single SAML proxy. The simpler version will be preserved for educational purposes but is intended to become "legacy".
+> [!NOTE]
+> If you want to just skip to the part where we use this with Kanidm, you could jump straight to the practical example: [Ceph SSO via Kanidm](#practical-example-ceph-sso-via-kanidm)
 
 ## TODO items on the roadmap
-1. Add log level configuration via ENV. It's now hardcoded to debug.
-2. Rewrite env config & the SATOSA configs for dynamic routing so that multiple apps can be routed to different OIDC clients. In the meanwhile you can configure multiple apps to use the same proxy, but then you can't control via claim maps on the Kanidm side who is eligible for what app.
-3. Get rid of the idpyoidc PR fork use once they no longer force RS256.
+1. Get rid of the idpyoidc git build once there's a release that contains ES256 support.
+2. Get rid of any manual jiggery with idpyoidc once SATOSA requires a sufficiently high version to support ES256.
 
 ## The container
 
 The container built at `ghcr.io/jinnatar/satosa-saml-proxy:latest` is a proof of concept using the SATOSA configs in the repo. The guides below will assume you are using it, but nothing prevents you from using the same configs and ENV config with any other supported SATOSA installation method. I am using the container myself in my environment and have a vested interest in keeping it going and tested.
 
-The caveats with the container and/or trying to go without it:
-- The currently released version of SATOSA, 8.4.0 is over a year old and does not include their new and improved OIDC module. The better module is required for PKCE support, which is why the container is built from their git HEAD instead of a release.
-- The main dependency for their new OIDC module is idpy-oidc. Unfortunately it has an issue that prevents using ES256 for signing. The container has a patch that instead enforces ES256, but it's unsuitable to upstream as a proper fix. This patching will be removed once https://github.com/IdentityPython/idpy-oidc/issues/110 is resolved. You could use `ES256.patch` to replicate this bubblegum fix outside the container.
-- The containers are not version tagged, since there is no upstream version of SATOSA that fulfills the requirements. They are however tagged to specific commits for your convenience if you do not wish to follow `:latest`.
+### The caveats with the container and/or trying to go without it:
+- While recent releases of SATOSA support PKCE, they depend on the Python library `idpyoidc` for this. Unfortunately it has an issue that prevents using `ES256` for signing with released versions. The container thus uses [a branch from git](https://github.com/IdentityPython/idpy-oidc/tree/issuer_metadata) that contains the fix for this. Once a full release is made with said fix that will be used specifically. Once SATOSA requires a high enough release of `idpyoidc` that contains a fix, we can stop with this nonsense altogether.
+- The containers are now version tagged as per SATOSA upstream versions. However, due to the above nonsense those tags will be updated later when better build provenance is available.
+
+### Container config options
+The container contains minimal config options via environment variables for ease of use.
+- `LOG_LEVEL`: defaults to `INFO`. You may want to raise this to `DEBUG` for troubleshooting, but be aware logs will then leak tokens. Affects gunicorn and all SATOSA modules (if using the env based default config).
+- `LISTEN_ADDR`: defaults to `0.0.0.0:80`. You may need to alter this depending on your container orchestration and proxying needs.
+- Any other gunicorn flags can be passed as arguments.
 
 ## Step by step guides for usage
 
@@ -35,14 +39,35 @@ SAML is a bit *involved* so we need to prep a persistent certificate and provide
 1. Once you have your metadata XML file, make it available to your container, for example via a volume. The dummy data is already available.
 2. Configure the ENV variables that will tweak the provided SATOSA configs. You can edit the provided `example.env` file and feed it to Docker via the `--env-file` flag. Make sure to **not** quote values if using that flag. Explanations below:
    ```shell
-   ENCRYPTION_KEY=0xDEADBEEF  # Key used to encrypt state in transit. Could generate with `openssl rand -base64 32`  
-   OIDC_CLIENT_ID=your-client-id  # The OIDC client id in Kanidm is the name of the integration, for example `ceph`  
+   # Enables debug logging for troubleshooting.
+   # Change this to "INFO" when everything works!
+   LOG_LEVEL=DEBUG  # Enables debug logging for troubleshooting. Change this to "INFO" when everything works!
+
+   # Key used to encrypt state in transit. Use a key of your own choosing!
+   # For example, generate one with `openssl rand -base64 32`  
+   ENCRYPTION_KEY=0xDEADBEEF
+   # The OIDC client id in Kanidm is the name of the integration, for example `ceph`.
+   OIDC_CLIENT_ID=your-client-id
    OIDC_CLIENT_SECRET=your-oidc-client-secret  
-   OIDC_ISSUER_URL=https://idm.example.com/oauth2/openid/your-client-id  # Full URL to the discovery endpoint  
-   OIDC_NAME=unique_oidc_name  # A unique id used for this OIDC backend in SATOSA. Uniqueness becomes relevant if you configure multiple on the same proxy.  
-   PROXY_BASE_URL=https://saml.example.com  # Where your proxy lives. **must** be https, must be the root of a host, must match the CN in your cert from step 1.  
-   SAML_METADATA="dummy-metadata.xml"  # A path to your app SAML metadata file. The working directory of the provided image is `/etc/satosa` so the relative path example here would expect the file to be on the container at `/etc/satosa/dummy-metadata.xml`. If you can't get this until the proxy is running and you've registered it in the app, use dummy-metadata.xml as a workaround to boot the proxy without it.  
-   SAML_NAME=unique_saml_name  # A unique id used for this SAML frontend in SATOSA. Uniqueness becomes relevant if you configure multiple on the same proxy.
+   
+   # Full URL to the discovery endpoint  
+   OIDC_ISSUER_URL=https://idm.example.com/oauth2/openid/your-client-id
+
+   # A unique id used for the OIDC side in SATOSA, used in the callback URL: `https://ceph.example.com/unique_oidc_name`
+   OIDC_NAME=unique_oidc_name
+   # A unique id used for the SAML side in SATOSA, used in URLs.
+   SAML_NAME=unique_saml_name
+   
+   # Where your proxy lives. **must** be https, must be the root of a host with no subdir,
+   # must match the CN in your cert from step 1, must be unique per app you're integrating.
+   PROXY_BASE_URL=https://saml.example.com
+   
+   # A path to your app SAML metadata file.
+   # The working directory of the provided image is `/etc/satosa`,
+   # so the relative path example here would expect the file to be on the container at `/etc/satosa/dummy-metadata.xml`.
+   # If you can't get this until the proxy is running and you've registered it in the app, use dummy-metadata.xml as a workaround to boot the proxy without it.  
+   SAML_METADATA=dummy-metadata.xml
+   
    ```
 3. Launch the proxy. This depends on your container orchestration, but a simple testing example is provided below. **This is not enough, you need to get https working which is outside the scope of this guide.
    ```shell
@@ -62,22 +87,42 @@ SAML is a bit *involved* so we need to prep a persistent certificate and provide
 ### Practical example: Ceph SSO via Kanidm
 1. Pre-create your users in Ceph to give them the correct authz. In this example we'll use short usernames for simplicity so that needs to match.
 1. Create your Kanidm OIDC configuration the usual way, no need to disable PKCE!
+   ```shell
+   # **Important** give the upstream Ceph landing page URL here:
+   kanidm system oauth2 create ceph Ceph https://ceph.example.com
+
+   # **Important** give the proxy callback URL here. The full value depends on $OIDC_NAME:
+   kanidm system oauth2 add-redirect-url ceph https://ceph-saml.example.com/oidc_ceph
+
+   # Use short usernames for convenience
+   kanidm system oauth2 prefer-short-username ceph
+
+   # Create the scope map, don't forget to create the group and add your Ceph admins to it.
+   kanidm system oauth2 update-scope-map ceph ceph_admins openid profile email  
+
+   # Get your client_secret for use later on:
+   kanidm system oauth2 show-basic-secret ceph
    ```
-   kanidm system oauth2 create ceph Ceph https://saml.example.com  # **Important**, give the proxy URL here.
-   kanidm system oauth2 prefer-short-username ceph # Use short usernames for convenience
-   kanidm system oauth2 update-scope-map ceph ceph_admins openid profile email  # Create the scope map, don't forget to create the group and add your Ceph admins to it.
-   kanidm system oauth2 show-basic-secret ceph  # Get your client_secret for use later on.
+1. Create your SAML2 certs and set their permissions, remember to set the correct `SN`:
+   ```shell
+      openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 \
+           -keyout saml.key -out saml.crt -subj "/SN=ceph-saml.example.com/"
+      chown :999 saml.key
+      chmod g+r saml.key
    ```
-1. Create your SAML2 certs and set their permissions as per the generic steps above, nothing special here.
 1. We can't get Ceph to spit out it's metadata XML before the proxy is functioning so we skip ahead.
 1. Config your ENV variables into a new env file, `ceph.env`. If you don't change the ENCRYPTION_KEY value you deserve everything you get as a result.
    ```shell
-   ENCRYPTION_KEY=+OSDGTYdWxesiUwcMEzaGzwCx81YHhzOFgsitMn9A/c=
+   # Enables debug logging for troubleshooting. Change this to "INFO" when everything works!
+   LOG_LEVEL=DEBUG
+   # Generate this for example with: `openssl rand -base64 32`
+   ENCRYPTION_KEY=
    OIDC_CLIENT_ID=ceph
-   OIDC_CLIENT_SECRET=# You got this above from kanidm
+   # The client secret you got in a previous step: 
+   OIDC_CLIENT_SECRET=
    OIDC_ISSUER_URL=https://idm.example.com/oauth2/openid/ceph
    OIDC_NAME=oidc_ceph
-   PROXY_BASE_URL=https://saml.example.com
+   PROXY_BASE_URL=https://ceph-saml.example.com
    SAML_METADATA=dummy-metadata.xml
    SAML_NAME=saml_ceph
    ```
@@ -90,7 +135,10 @@ SAML is a bit *involved* so we need to prep a persistent certificate and provide
    ```
 1. Register the proxy with Ceph, giving it the Ceph URL, SAML metadata endpoint and an attribute field name to expect for the username.
    ```shell
-   ceph dashboard sso setup saml2 https://ceph.example.com https://saml.example.com/saml_ceph/metadata.xml urn:oid:0.9.2342.19200300.100.1.1
+   ceph dashboard sso setup saml2 \
+    https://ceph.example.com \
+    https://ceph-saml.example.com/saml_ceph/metadata.xml \
+    urn:oid:0.9.2342.19200300.100.1.1
    ```
 1. Assuming registration was succesful, we can now get the Ceph side SAML metadata:
    ```shell
@@ -105,4 +153,4 @@ SAML is a bit *involved* so we need to prep a persistent certificate and provide
     ghcr.io/jinnatar/satosa-saml-proxy:latest
     ```
 
-1. Restart the proxy and go test Ceph SSO!
+1. Restart the proxy and go test Ceph SSO! Once it's all working, amend your env one more time to set `LOG_LEVEL=INFO`!
diff --git a/entrypoint.sh b/entrypoint.sh
@@ -0,0 +1,12 @@
+#!/bin/sh
+
+set -eu
+
+# This entrypoint exists to set gunicorn flags from ENV.
+# Any arguments are interpreted as gunicorn flags to allow fine tuning, say for adding TLS.
+
+# SATOSA is particular about log levels being uppercase, gunicorn doesn't care
+LOG_LEVEL="$(echo "$LOG_LEVEL" | tr [:lower:] [:upper:])"
+export LOG_LEVEL
+
+exec gunicorn --log-level="$LOG_LEVEL" --bind="$LISTEN_ADDR"  "$@" "satosa.wsgi:app"
diff --git a/example.env b/example.env
@@ -1,3 +1,5 @@
+LOG_LEVEL=debug
+LISTEN_ADDR=0.0.0.0:80
 ENCRYPTION_KEY=0xDEADBEEF
 OIDC_CLIENT_ID=your-client-id
 OIDC_CLIENT_SECRET=your-oidc-client-secret
diff --git a/proxy_conf.yaml b/proxy_conf.yaml
@@ -25,20 +25,20 @@ LOGGING:
     stdout:
       class: logging.StreamHandler
       stream: "ext://sys.stdout"
-      level: DEBUG
+      level: !ENV LOG_LEVEL
       formatter: simple
   loggers:
     satosa:
-      level: DEBUG
+      level: !ENV LOG_LEVEL
     saml2:
-      level: DEBUG
+      level: !ENV LOG_LEVEL
     oidcendpoint:
-      level: DEBUG
+      level: !ENV LOG_LEVEL
     pyop:
-      level: DEBUG
+      level: !ENV LOG_LEVEL
     oic:
-      level: DEBUG
+      level: !ENV LOG_LEVEL
   root:
-    level: DEBUG
+    level: !ENV LOG_LEVEL
     handlers:
       - stdout

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+LOG_LEVEL=debug`
	`2`	`+LISTEN_ADDR=0.0.0.0:80`
`1`	`3`	`ENCRYPTION_KEY=0xDEADBEEF`
`2`	`4`	`OIDC_CLIENT_ID=your-client-id`
`3`	`5`	`OIDC_CLIENT_SECRET=your-oidc-client-secret`