This Ansible role spins up a Docker container, meant to be run in Docker Swarm mode, that runs a Shibboleth daemon and Apache service with Supervisor.
Create a requirements.yml, within your ansible/roles dir, and add the repo:
roles:
- src: https://gitlab.library.upenn.edu/devops/ansible/shibboleth_sp.git
scm: git
Install the new role by running (update the path accordingly):
ansible-galaxy install -p ansible/roles -r ansible/roles/requirements.yml
It is best to not commit the role to your repo therefore ignore the role by adding it to your .gitignore (update the path accordingly): ansible/roles/shibboleth_sp
Copy the shibboleth dict default/main.yml and add it to your inventory (either directly in your vars.yml file or keep it separate by creating a new file and placing the definitions there). Update the values with data relevant to your application - ensuring sensitive information is stored within Ansible vault. You can customize any of the configs and templates to suit your needs.
Since this service is intended to sit in front of an existing application it will often be necessary to have both applications running on the same network. As such it will be necessary to first create the docker network using the available task (tasks/create_docker_network.yml) before starting your application and the shibboleth service. For example:
- hosts: swarm_managers
become: yes
tasks:
- include: "roles/shibboleth_sp/tasks/create_docker_network.yml"
...
- hosts: swarm_managers
become: yes
roles:
- my_application
- shibboleth_sp
| File | Description |
|---|---|
| apache/shib2.conf.j2 | Basic configuration for default VirtualHost with Shibboleth provider - ServerName and ServerAdmin to be provided via ansible variable stored in vault |
| shibboleth/attribute_map.xml.j2 | Sample Shibboleth attribute mappings |
| shibboleth/metadata.xml.j2 | Supplies Shibboleth metadata - value to be provided via ansible variable stored in vault |
| shibboleth/shibboleth2.xml.j2 | Sample Shibboleth configuration - SP/IDP entityId's to be provided via ansible variable stored in vault |
| shibboleth/sp_encrypt_cert.pem.j2 | Supplies Encryption Cert - value to be provided via ansible variable stored in vault |
| shibboleth/sp_encrypt_key.pem.j2 | Supplies Encryption Key - value to be provided via ansible variable stored in vault |
| shibboleth/sp_signing_cert.pem.j2 | Supplies Signing Cert - value to be provided via ansible variable stored in vault |
| shibboleth/sp_signing_key.pem.j2 | Supplies Signing Key - value to be provided via ansible variable stored in vault |
This role has been created to allow you to override any of the included templates with your own templates. To do so you need to
- create a
templatesdir at the same level as your playbook - add a new file to override the base file in the newly created
templatesdir - update the appropriate path under
shibboleth.templatesorshibboleth.configsvar you are changing
For example to override the shib2.conf.j2 template you would create a file at the same level as your playbook located at templates/shibboleth/apache/shib2.conf.j2. Then in your local shibboleth.yml file you would set the new path:
shibboleth:
...
templates:
configs:
shib2:
path "shibboleth/apache/shib2.conf.j2"
...
To generate the encrypt key run the command (replacing the entityId and hostname accordingly):
shib-keygen -f -h example.edu -e entityID -y 10 -n sp_encrypt
To generate the signing key run the command (replacing the entityId and hostname accordingly):
shib-keygen -f -h example.edu -e entityID -y 10 -n sp_signing
The values of the keys and certs generated should then be added to the corresponding key:value pair in the Ansible vault for your project.
Generate
Once the keys have been generated and the role is active/running you can get the service provider metadata by navigating to https://example.edu/Shibboleth.sso/Metadata. This will then need to be added to the Identity Provider.
| Key | Default Value | Description | Should be Encrypted |
|---|---|---|---|
| shibboleth.image.name | shibboleth_dev | Shibboleth Docker Image Name | No |
| shibboleth.image.tag | latest | Shibboleth Docker Image Tag | No |
| shibboleth.is_development | true | Whether to set to dev mode (will build the image rather than pull from the registry) | No |
| shibboleth.swarm_node_constraint | shibboleth | Node to constrain the docker container to | No |
| shibboleth.templates.configs.shib2.path | apache/shib2.conf.j2 | Config File Path | No |
| shibboleth['templates']['configs']['shib2']['values']['admin_email'] | info@example.com | Email address used for Apache ServerAdmin | Yes |
| shibboleth['templates']['configs']['shib2']['values']['fqdn'] | www.example.com | Domain of site (ensure protocol is not included) | No - but may be necessary if using in vault |
| shibboleth.templates.configs.shib2.version | 1 | Docker Config Version | No |
| shibboleth.templates.secrets.attribute_map.path | shibboleth/attribute_map.xml.j2 | Template File Path | No |
| shibboleth.templates.secrets.attribute_map.version | 1 | Docker Secret Version | No |
| shibboleth.templates.secrets.metadata.path | shibboleth/metadata.xml.j2 | Template File Path | No |
| shibboleth['templates']['secrets']['metadata']['value'] | test | Shibboleth IdP metadata - provided by the provider | Yes |
| shibboleth.templates.secrets.metadata.version | 1 | Docker Secret Version | No |
| shibboleth.templates.secrets.shibboleth2.path | shibboleth/shibboleth2.xml.j2 | Template File Path | No |
| shibboleth['templates']['secrets']['shibboleth2']['values']['sp_entityID'] | 1234 | Shibboleth SP EntityID - format = https:// + fqdn + /shibboleth | Yes |
| shibboleth['templates']['secrets']['shibboleth2']['values']['idp_entityID'] | 1234 | Shibboleth IdP EntityID - provided by the provider | Yes |
| shibboleth.templates.secrets.shibboleth2.version | 1 | Docker Secret Version | No |
| shibboleth.templates.secrets.sp_encrypt_cert.path | shibboleth/sp_encrypt_cert.pem.j2 | Template File Path | No |
| shibboleth['templates'][secrets]['sp_encrypt_cert']['values']['sp_cert_pem'] | 1234 | Shibboleth Encryption Cert | Yes |
| shibboleth.templates.secrets.sp_encrypt_cert.version | 1 | Docker Secret Version | No |
| shibboleth.templates.secrets.sp_encrypt_key.path | shibboleth/sp_encrypt_key.pem.j2 | Template File Path | No |
| shibboleth['templates']['secrets']['sp_encrypt_key']['values']['sp_key_pem'] | 1234 | Shibboleth Encryption Key | Yes |
| shibboleth.templates.secrets.sp_encrypt_key.version | 1 | Docker Secret Version | No |
| shibboleth.templates.secrets.sp_signing_cert.path | shibboleth/sp_signing_cert.pem.j2 | Template File Path | No |
| shibboleth['templates']['secrets']['sp_signing_cert']['values']['sp_cert_pem'] | 1234 | Shibboleth Signing Cert | Yes |
| shibboleth.templates.secrets.sp_signing_cert.version | 1 | Docker Secret Version | No |
| shibboleth.templates.secrets.sp_signing_key.path | shibboleth/sp_signing_key.pem.j2 | Template File Path | No |
| shibboleth['templates']['secrets']['sp_signing_key'][values]['sp_key_pem'] | 1234 | Shibboleth Signing Key | Yes |
| shibboleth.templates.secrets.sp_signing_key.version | 1 | Docker Secret Version | No |
The Docker image for this Shibboleth service provider uses Ubuntu as a base image. Apache is used as the front end; Supervisor is used to manage the Shibboleth daemon and Apache service. There are several configuration files that must be mounted into the container as Docker configs/secrets in order to function properly (see the docker-compose.yml file and Configs and Templates).