s390x/satosa

By s390x

Updated 8 months ago

SATOSA translates between authentication protocols such as SAML2, OpenID Connect, and OAuth2.

Image
API Management

3.7K

Note: this is the "per-architecture" repository for the s390x builds of the satosa official image -- for more information, see "Architectures other than amd64?" in the official images documentation and "An image's source changed in Git, now what?" in the official images FAQ.

Quick reference

Supported tags and respective Dockerfile links

WARNING: THIS IMAGE IS NOT SUPPORTED ON THE s390x ARCHITECTURE

s390x/satosa build status badge

Quick reference (cont.)

What is SATOSA?

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

logo

How to use this image

To start a SATOSA instance

The basic pattern for starting a satosa instance is:

docker run --name some-satosa -d s390x/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 s390x/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.

How to extend this image

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 s390x/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 s390x/satosa bash

Environment variables

The entrypoint script uses environment variables to generate the initial configuration, which sets SATOSA up as a SAML2 proxy between the free SAMLtest.ID test service provider and test identity provider. All of the environment variables are optional.

The 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 optionally 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

When part of a SAML2 multilateral federation, SATOSA will ask the user to choose an identity provider using a SAML discovery service. This environment variable optionally sets the discovery service URL, which defaults to SeamlessAccess.

SAML2_BACKEND_CERT and SAML2_BACKEND_KEY

SATOSA's SAML2 backend acts like a service provider (relying party), requesting authentication by and attributes from the user's identity provider. It uses public key cryptography to sign authentication requests and decrypt responses. These optional environment variables hold the backend's paired public and private keys in the PEM format. If not specified, a new 2048-bit RSA key-pair will be generated using the hostname part of BASE_URL.

SAML2_FRONTEND_CERT and SAML2_FRONTEND_KEY

SATOSA's SAML2 frontend acts like an identity provider (credential service provider), processing authentication requests from and returning user attributes to trusted websites. It uses public key cryptography to sign authentication responses. These optional environment variables hold the frontend's paired public and private keys, also in the PEM format. If not specified, a new 2048-bit RSA key-pair will be generated using the hostname part of BASE_URL.

License

View license information for the software contained in this image.

As with all Docker images, these likely also contain other software which may be under other licenses (such as Bash, etc from the base distribution, along with any direct or indirect dependencies of the primary software being contained).

Some additional license information which was able to be auto-detected might be found in the repo-info repository's satosa/ directory.

As for any pre-built image usage, it is the image user's responsibility to ensure that any use of this image complies with any relevant licenses for all software contained within.

Docker Pull Command

docker pull s390x/satosa