Permalink
Cannot retrieve contributors at this time
Name already in use
A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
docker-shib-proxy/README.md
Go to fileThis commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
133 lines (95 sloc)
5.27 KB
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
# 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 the `eppn` attribute value for the | |
user | |
* `X-Forwarded-Groups`: Contains the `isMemberOf` 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: | |
1. Change to the `tests` directory, and bring up the `proxy` service and its | |
dependencies from `docker-compose.yml`: | |
``` | |
cd tests | |
docker-compose up -d proxy | |
``` | |
2. 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 | |
``` | |
3. In a web browser, visit https://sptest.example.edu:8443. You should be | |
redirected to the test IdP at https://idp.example.edu. | |
4. In the IdP login form, use `banderson` for the username, and | |
`password` for the password. | |
5. 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 | | |
6. 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 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". |