docker-shib-proxy
A SAML-authenticating HTTPS reverse proxy using Shibboleth
Introduction
This repository builds a Docker container image that acts as an HTTPS reverse proxy in front of a web application. The proxy authenticates a visitor using SAML, and passes the username and group memberships to the web application as HTTP headers:
-
X-Forwarded-User
: Contains theeppn
attribute value for the user -
X-Forwarded-Groups
: Contains theisMemberOf
attribute values for the user, separated by semicolons
IMPORTANT: To prevent visitors from spoofing the HTTP headers, you MUST ensure that your web application only allows incoming requests from the reverse proxy, or otherwise that it doesn't accept the headers above from any clients except the reverse proxy. A typical configuration would be to run the proxy as a sidecar container to your web application, such that all HTTP(S) requests must flow through the proxy.
Quick Start
To try the container in a test environment:
-
Change to the
tests
directory, and bring up theproxy
service and its dependencies fromdocker-compose.yml
:cd tests docker-compose up -d proxy
-
Update
/etc/hosts
to addidp.example.edu
andsptest.example.edu
as aliases forlocalhost
:# /etc/hosts 127.0.0.1 localhost idp.example.edu sp.example.edu
-
In a web browser, visit https://sptest.example.edu:8443. You should be redirected to the test IdP at https://idp.example.edu.
-
In the IdP login form, use
banderson
for the username, andpassword
for the password. -
After logging in, you should see a PHP information page. Under the "HTTP Headers Information" heading, yous should see the following headers set:
Header Value X-Forwarded-User banderson@example.edu X-Forwarded-Groups cn=developers,ou=Groups,dc=internet2,dc=edu;cn=users,ou=Groups,dc=internet2,dc=edu -
When finished, shut down the services from
docker-compose.yml
:docker-compose down
Configuration
The container expects several environment variables at runtime. See
tests/docker-compose.yml
for a working example. In a production environment,
these variables would be set by your orchestration system (for example, AWS
Elastic Container Service or Kubernetes), and sensitive information (such as
private keys) would be stored securely (for example, using AWS Systems Manager
Parameter Store, AWS Secrets Manager, or HashiCorp Vault).
Required Variables
(Note: To establish trust with the IdP, you must either specify
SAML_IDP_METADATA
, or specify SAML_IDP_METADATA_URL
and
SAML_IDP_SIGNING_CERT
.)
-
FRONT_HTTPS_PORT
: Set this to the canonical front-end HTTPS port, to ensure that URLs are constructed correctly. (This may be different fromHTTPS_PORT
, if the proxy is behind a load balancer or another HTTPS proxy.) -
FRONT_HOSTNAME
: Set this to the canonical, fully-qualified domain name for the proxy, for example "app.example.edu". (This may be different from the proxy's hostname, if the proxy is behind a load balancer or another HTTPS proxy.) -
HTTPS_PORT
: The port on which the proxy should listen for HTTPS connections -
SAML_ENCRYPTION_CERT
: A base-64 encoded SAML encryption certificate, beginning with "-----BEGIN CERTIFICATE-----" -
SAML_ENCRYPTION_KEY
: The base-64 encoded private key forSAML_ENCRYPTION_CERT
, beginning with "-----BEGIN PRIVATE KEY-----" -
SAML_ENTITYID
: The SAML entity ID for the proxy, for example "https://app-proxy.example.edu/shibboleth" -
SAML_IDP_ENTITYID
: The SAML entity ID for a trusted SAML identity provider or SAML proxy, for example "https://idp.example.edu/idp/shibboleth" -
SAML_IDP_METADATA
(Optional): SAML metadata forSAML_IDP_ENTITYID
; should include a single<EntityDescriptor>
element. Required ifSAML_IDP_METADATA_URL
is not set. -
SAML_IDP_METADATA_URL
(Optional): URL from which to retrieve the IdP metadata file. Required ifSAML_IDP_METADATA
is not set. -
SAML_IDP_SIGNING_CERT
(Optional): The base-64 encoded SAML signing certificate used to verify the IdP metadata signature, beginning with "-----BEGIN CERTIFICATE-----". Required ifSAML_IDP_METADATA_URL
is set. -
SAML_SIGNING_CERT
: A base-64 encoded SAML signing certificate beginning with "-----BEGIN CERTIFICATE-----" -
SAML_SIGNING_KEY
: The base-64 encoded private key forSAML_SIGNING_CERT
, beginning with "-----BEGIN PRIVATE KEY-----" -
TLS_CERT
: A base-64 encoded TLS server certificate used for HTTPS connections, beginning with "-----BEGIN CERTIFICATE-----" -
TLS_PRIVATE_KEY
: The base-64 encoded private key forTLS_CERT
, beginning with "-----BEGIN RSA PRIVATE KEY-----"
Optional Variables
-
HTTPD_ARGS
: Additional arguments to be passed tohttpd
bysupervisord
. If the proxy is behind a load balancer or another HTTP proxy, set this to "-DProxied" -
TIER_BEACON_OPT_OUT
: Opt out of reporting telemetry to Internet2 (from thetier/shibboleth_sp
base container image). Set to "true" or "false".