README.md

# 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 can authenticate a visitor using
SAML.

 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 the first thing to do is update `/etc/hosts` to add `idp.example.edu` and
   `sptest.example.edu` as aliases for `localhost`:
   ```
   # /etc/hosts
   127.0.0.1  localhost idp.example.edu sp.example.edu
   ```

Now, there are two ways to do testing:
- **Automated**

  Run 
  ```
  make test
  ```

- **Manual**

  1. Run
      ```
      docker compose up -d proxy
      ```

  2. In a web browser, visit https://sptest.example.edu. You should be
   redirected to the test IdP at https://idp.example.edu.

  3. In the IdP login form, use `user1` for the username, and
   `user1pass` for the password.

  4. After logging in, you should see a PHP information page. Under the
      "Headers" heading, you should see the following information, letting you know you successsfully authenticated using the proxy:

      | Header             | Value                          |
      |--------------------|--------------------------------|
      | Referer            | "http://idp.example.edu:8080/" |
      | X-Forwarded-Host   | "sptest.example.edu"           |

  5. You should also see on the PHP information page the following Headers and Values, letting you know you successsfully extracted the specified attributes from the SAML assertion in the response:

      | Header                   | Value                  |
      |--------------------------|------------------------|
      | Shib-Proxy-displayName   | "User One"             |
      | Shib-Proxy-eppn          | "user1@example.edu"    |
      | Shib-Proxy-mail          | "user1@example.edu"    |

  6. When finished, shut down the services from `docker compose.yml`:
      ```
      docker compose down
      ```


## Configuration

The container expects several environment variables at runtime. See
`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 from `HTTPS_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 for
  `SAML_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 for `SAML_IDP_ENTITYID`; should
  include a single `<EntityDescriptor>` element. Required if 
  `SAML_IDP_METADATA_URL` is not set.

* `SAML_IDP_METADATA_URL` (Optional): URL from which to retrieve the IdP
  metadata file. Required if `SAML_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 if `SAML_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 for
  `SAML_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 for `TLS_CERT`, beginning
  with "-----BEGIN RSA PRIVATE KEY-----"

### Optional Variables

* `HTTPD_ARGS`: Additional arguments to be passed to `httpd` by `supervisord`.
  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
  the `tier/shibboleth_sp` base container image). Set to "true" or "false".