satosa pulls statistics

Quick reference

• Maintained by:
  the Identity Python project

• Where to get help:
  the Identity Python mailing list or the Identity Python Slack workspace (invitation)

Supported tags and respective Dockerfile links

(See "What's the difference between 'Shared' and 'Simple' tags?" in the FAQ.)

Simple Tags

• 8.6.0-trixie, 8.6-trixie, 8-trixie, trixie

• 8.6.0-alpine3.24, 8.6-alpine3.24, 8-alpine3.24, alpine3.24, 8.6.0-alpine, 8.6-alpine, 8-alpine, alpine

Shared Tags

• 8.6.0, 8.6, 8, latest:

  • 8.6.0-trixie

Quick reference (cont.)

• Where to file issues:
  https://github.com/IdentityPython/satosa-docker/issues

• Supported architectures: (more info)
  amd64, arm64v8

• Published image artifact details:
  repo-info repo's repos/satosa/ directory (history)
  (image metadata, transfer size, etc)

• Image updates:
  official-images repo's library/satosa label
  official-images repo's library/satosa file (history)

• Source of this description:
  docs repo's satosa/ directory (history)

What is SATOSA?

SATOSA is a configurable proxy for translating between different authentication protocols such as SAML2, OpenID Connect, and OAuth2.

Using This Image

The basic pattern for starting a satosa instance is:

docker run --name some-satosa -d satosa

To access the instance from the host without the container's IP, use port mappings:

docker run --name some-satosa -p 80:8080 -d satosa

The entrypoint script outputs SAML2 metadata to the container log at start time. This metadata refers to the instance's base URL, e.g., https://example.com. Browsers must be able to access the instance over HTTPS.

Configuration files

The satosa image stores its configuration in /etc/satosa. This configuration must persist among instances, particularly the SAML2 entity ID (derived from the proxy's base URL by default) and related keying material. Use volumes, bind mounts, or custom images to maintain this configuration.

Entrypoint script

The satosa image's entrypoint script runs Gunicorn by default if the first argument looks like a command-line flag. For example, the following will use a bind mount to provide an X.509 certificate and corresponding private key to the instance, and it will run Gunicorn with HTTPS enabled:

docker run --name some-satosa -p 443:8443 \
    -v /etc/letsencrypt/live/some-satosa/fullchain.pem:/etc/https.crt \
    -v /etc/letsencrypt/live/some-satosa/privkey.pem:/etc/https.key \
    -d satosa \
    -b0.0.0.0:8443 --certfile /etc/https.crt --keyfile /etc/https.key satosa.wsgi:app

If the first argument looks like a command instead of a flag, the entrypoint script will run that instead of Gunicorn. For example, the following will start an interactive, unprivileged shell inside the container:

docker run -it --name some-satosa satosa bash

Environment variables

The entrypoint script uses environment variables to generate the initial configuration, which requires customization. All of the environment variables are OPTIONAL.

Environment variables' values can be read from Docker secrets. Append _FILE to the variable name (e.g., STATE_ENCRYPTION_KEY_FILE), and set it to the pathname of the corresponding secret (e.g., /run/secrets/state_encryption_key).

BASE_URL

SATOSA MUST be hosted at the root of the website. This environment variable specifies the website's base URL, which defaults to http://example.com. If set, the base URL must be a method plus a hostname without any trailing slash or path components, e.g., https://idproxy.example.com, not https://idproxy.example.com/ nor https://idproxy.example.com/satosa.

STATE_ENCRYPTION_KEY

SATOSA uses encrypted cookies to track the progress of an authentication flow. This environment variable optionally sets the state cookies' encryption key. If set, the state encryption key must be an alphanumeric value, e.g., 12345SameAsMyLuggage. If not specified, a new random 32-character key will be generated.

SAML2_BACKEND_DISCO_SRV…