Readme and example nginx configuration

2 files changed, 131 insertions, 133 deletions

diff --git a/README.md b/README.md
index 89aea33..f717eb8 100644
--- a/README.md
+++ b/README.md
@@ -1,173 +1,135 @@
-# Shibboleth IDP version 3 project
+# Shibboleth IDP version 3 docker
 
-# RTFM
+This is a dockerized version of shibboleth 3.x. It runs on the `jetty:9-alpine` base image, and has been preconfigured to use the SWAMID saml-2.0 metadata feed.
 
-From
-https://wiki.shibboleth.net/confluence/display/IDP30/Configuration
 
-To configure a new IdP from scratch, you will need to address these areas first:
-* Metadata
-* Authentication
-* Attribute Resolver
-* Attribute Filter
+## Configuration
 
-If you need to dig into more advanced SAML configuration needs, or need to interoperate with commercial cloud services, you will usually need to tackle these areas:
-* SAML NameID Generation
-* Profiles and Per-RelyingParty Behavior
-* Unsolicited (IdP-initiated) SAML
+The way this docker image is structured is to try and make it simple to change certain aspects, such as additional local SP additions, FTICKS configuration, changing certificates and metadata.
 
-and more
+Environment variables:
 
-File installer.properties
-Properties written out by the installer and used during upgrades. Scripts may create this ahead of time and feed it in to the installer in order to have a silent install. Deployers are not expected to modify this directly.
+- `IDP_HOSTNAME` e.g.  idp.nordu.net
+- `IDP_SCOPE` e.g. `nordu.net`
+- `IDP_ENCRYPTION_OPTIONAL` if set to `true` enables support for ServiceProvicers that do not supply an encryption key.
+- `FTICKS_FEDERATION` e.g. `swamid` if set enables fticks logging.
+- `FTICKS_SALT` a random salt used to anonymise user id, if not supplied the user id will not be included in logging.
+- `FTICKS_HOST` if a fticks loggin server should be used you need to set this
+- `FTICKS_PORT` if a fticks loggin server should be used you need to set this
+- `IDP_PERSISTENTID_SALT` a random salt used if you need to release `eduPersonTargetdID`.
+- `IDP_DEBUG` if enabled will set the loglevel to `DEBUT`, which logs the decrypted messages.
 
-# planning
-https://shibboleth.net/pipermail/users/2016-July/030260.html
-http://shibboleth.1660669.n2.nabble.com/SAML-message-intended-destination-endpoint-did-not-match-the-recipient-endpoint-td7626468.html
+If you mount a directory in `/opt/data` you can overwrite certain things.
 
-We setup a new IdP on the 3.x branch. New hostname, new certificates, new
-URL bindings, etc; but responding as the same entityID as the old IdP on
-the 2.x version.
-...
+- `/opt/data/idp-metadata.xml` if this file is present it will replace the autogenerated metadata. You probably want to do this.
+- `/opt/data/credentials/`
+  - `idp-signing.key` and `idp-signing.crt` will replace the autogrenerated signing cert.
+  - `idp-encryption.key` and `idp-encryption.crt` will replace the autogenarated encryption certs.
+- `/opt/data/messages/*` allows you to add a `message.properties` file for localisation.
+- `/opt/data/sp-metadata/*.xml` you can add metadata for private SPs, they will automatically get the same attributes released as a SWAMID service.
 
+### Template messages
 
+Here is an example of the `messages.properties` file from NORDUnet.
 
-
-# Testing
-
-The NORDUnet configuration requires that you can reach `ldap.nordu.net`, so make sure you can reach that. E.g. I need to be on VPN to access it.
-
-Add the following to your `/etc/hosts` file:
-
-```
-127.0.0.1 idp.nordu.dev sp.nordu.dev
 ```
+idp.title=Your IdP title
+idp.footer=Your footer information here
+idp.logo=/images/nordunet.png
+idp.logo.alt-text=Your alt text
+idp.url.password.change=http://example.com
+idp.home=NORDUnet Home
+idp.url.home=https://www.nordu.net
+idp.aup=Acceptable Use Policy
+idp.url.aup=https://www.nordu.net/content/acceptable-use-policy
+idp.privacy=Privacy Statement
+idp.url.privacy=https://www.nordu.net/content/data-security-and-encryption
 
-Then you can use docker compose to build and start the containers. 
-
-```
-docker-compose -f compose-dev.yml up --build
+# Used in index.jsp
+root.title=Your IdP title
+root.footer=Your footer information here
 ```
 
-When everything has started you need to add the SP metadata to the IdP, this can be done by running:
+## Logging
 
-```
-curl -k https://sp.nordu.dev/Shibboleth.sso/Metadata -o data/idp/metadata/sp-metadata.xml
-dokcer-compose -f compose-dev.yml restart shibboleth-docker
-```
+If you mount a directory to `/opt/data` all the IDP logs will be written to `/opt/data/logs`.
 
-Now you should be able to navigate to `https://sp.nordu.dev/secure/` where you should be prompted to log in.
+As mentioned in the configuration section you can enable FTICKS logging by adding an environment variable.
 
+If needed you can enable debug logging with an environment variable.
 
-# Resources
-Links from Jesper Rosenkilde
 
-https://shibboleth.net/products/identity-provider.html
-https://github.com/UNINETT/mod_auth_mellon
+## Deploying in production
 
+You might want to change some of the things in `idp/templates` e.g. add a logo in `idp/templates/edit-webapp/images`.
 
-# Running a docker
+1. Clone the repository
+2. Build using `docker build -t shibboleth-docker .`
+3. Create a `data` dir that is owned by uid 100 gid 101, on ubuntu it seems to be `libuuid`
+4. Gennerate new signing and encryption keys `openssl req -x509 -sha256 -nodes -days 7300 -newkey rsa:4096 -keyout idp-encryption.key -out idp-encryption.crt` and put them in `data/credentials/`
+5. Make a proper idp-metadata.xml and put it in `data/`. You can copy the autogenerated one from docker using `docker cp ID:/opt/shibboleth-idp/metadata/idp-metadata.xml .` Remember to change the public keys to match the ones gennerated in step 4.
+6. Create `data/messages/messages.properties`
 
-## Build
 ```
-docker build -t $(basename $(pwd)) .
+docker run --rm -d -ti --name ndn-idp -v /opt/shibboleth-docker/data:/opt/data -e "IDP_HOSTNAME=idp.nordu.net" -e "IDP_SCOPE=nordu.net" -e "JAVA_OPTIONS=-Xmx1500m" -e "FTICKS_FEDERATION=swamid" -e "IDP_ENCRYPTION_OPTIONAL=true" shibboleth-docker
 ```
 
-## Run
-```
-docker run -p80:80 -p 443:443 --rm -ti $(basename $(pwd))
-```
+In NORDUnet we run our IdP behind nginx.
 
-## Interactive shell
-```
-hlk@bujin:shibboleth-docker$ docker ps
-CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                                                NAMES
-b2b93c309396        shibboleth-docker   "/docker-entrypoin..."   8 minutes ago       Up 8 minutes        0.0.0.0:80->80/tcp, 0.0.0.0:443->443/tcp, 8080/tcp   eager_borg
-```
+## Testing
 
-## Getting shell
+The NORDUnet configuration requires that you can reach `ldap.nordu.net`, so make sure you can reach that. E.g. I need to be on VPN to access it.
+
+Add the following to your `/etc/hosts` file:
 
 ```
-hlk@bujin:shibboleth-docker$ docker exec -ti b2b93c309396 bash
-bash-4.3# id
-uid=0(root) gid=0(root) groups=0(root),1(bin),2(daemon),3(sys),4(adm),6(disk),10(wheel),11(floppy),20(dialout),26(tape),27(video)
-bash-4.3# hostname
-b2b93c309396
+127.0.0.1 idp.nordu.dev sp.nordu.dev
 ```
 
-## Copy files out from container
-
-
-docker cp `docker ps | cut -f 1 -d ' ' | grep -v "CONTAINER"`:/opt/shibboleth-idp/conf /Users/hlk/projects/shibboleth-docker/conf-from-container
+Then you can use docker compose to build and start the containers.
 
 ```
-docker cp c172ac9afb1b:/opt/shibboleth-idp/conf /Users/hlk/projects/shibboleth-docker/conf-from-container
+docker-compose -f compose-dev.yml up --build
 ```
 
+When everything has started you need to add the SP metadata to the IdP, this can be done by running:
 
+```
+curl -k https://sp.nordu.dev/Shibboleth.sso/Metadata -o data/idp/metadata/sp-metadata.xml
+dokcer-compose -f compose-dev.yml restart shibboleth-docker
+```
 
-# Changes in v2 to v3
-
-Summary of changes
-https://wiki.shibboleth.net/confluence/display/IDP30/ConfigurationFileSummary
-
-# Less changes
-
-Attribute resolver
-https://wiki.shibboleth.net/confluence/display/IDP30/AttributeResolverConfiguration
-V2 Compatibility
-The overall content and structure is identical to V2.  Sematically, the V3 IdP is nearly 100% compatible with V2 attribute configuration.  All regressions should be reported via our issue tracker.
-Some key exceptions are noted below.
-
-
-
-
-# Changes to be made
-
-https://wiki.shibboleth.net/confluence/display/IDP30/AuthenticationConfiguration
-
-If the V2 UsernamePassword login handler was used, the V3 equivalent is the Password flow with the JAAS back-end; a similar JAAS configuration can typically be used, but the most common case (LDAP) is an exception because the underlying LDAP library has changed. By convention this configuration is placed in authn/jaas.config and the legacy-matching "ShibUserPassAuth" login configuration name is used (though this can be changed). The UI for password-based login is no longer strictly JSP-based as in V2, but is now a Web Flow view: this can use Velocity, JSP, or potentially other view technologies. The default login.vm view provided uses Velocity. Using an older login.jsp file will require some changes, although the V2 JSP taglibs for metadata-driven UI information should still work. We recommend modernizing to the use of Velocity, as this is much simpler in most cases.
-...
-So in short, activate flows with the idp.authn.flows property, transfer JAAS or web.xml and container configuration over, and you should have basic compatibility working, apart from the actual login UI for JAAS-based authentication.
-
-This is used in Nordunet config handler.xml
-
-
-
-
-Source: https://wiki.shibboleth.net/confluence/display/IDP30/MetadataConfiguration
-
-During the V2 to V3 upgrade process, the original V2 relying-party.xml file is copied to metadata-providers.xml, to serve as the metadata configuration for the new version. It's strongly advisable after upgrading to update that file by stripping it of the older content and promote the <MetadataProvider> element in it to the root of the file. In the interim all other content in the file except for <MetadataProvider> elements (and any referenced <security:TrustEngine> elements) is ignored.
-The following non-relevant trust engine types often found in a legacy relying-party.xml file are ignored if seen and cannot be used for metadata verification:
-Chaining
-MetadataExplicitKey
-MetadataPKIXX509Credential
-MetadataExplicitKeySignature
-MetadataPKIXSignature
-StaticPKIXX509Credential
-
-
-# Other Links
-
-https://spaces.internet2.edu/pages/viewpage.action?pageId=49841792#LinuxIdentityProviderIdPv3(Centos7
-"1. Customize the IdP's Login Page"
-
-http://www.jeesty.com/shibboleth
-Description of how Shibd works with Apache
-
-
-https://github.com/nginx-shib/nginx-http-shibboleth
-Maybe a working Nginx with Shibb?
-
-https://shibboleth.net/products/metadata-aggregator.html
-Metadata Aggregator provides a command line tool and REST-based web service to support publishers and consumers of metadata.
-- kan måske lette noget arbejde med at vedligeholde filer?
-
-
-
-https://wiki.shibboleth.net/confluence/display/IDP30/Installation+Directory+and+Configuration+Files
-describes the Installation Directory and Configuration Files
+Now you should be able to navigate to `https://sp.nordu.dev/secure/` where you should be prompted to log in.
 
+### Emulating production
+
+You can lie to your own machine and use your local development docker `idp.nordu.net`.
+
+- Add `127.0.0.1 idp.nordu.net` to your `/etc/hosts` file.
+- Create the following data layout
+  ```
+  data
+  ├── certs
+  │   ├── idp_nordu_net-bundle.pem
+  │   └── idp_nordu_net.key
+  ├── env
+  ├── idp-data
+  │   ├── credentials
+  │   │   ├── idp-encryption.crt
+  │   │   ├── idp-encryption.key
+  │   │   ├── idp-signing.crt
+  │   │   └── idp-signing.key
+  │   └── messages
+  │       └── messages.properties
+  └── nginx
+      └── idp.conf
+  ```
+- You can use selfsigned certs for the certs in the certs folder. But all credentials certs need to be from produdction.
+- `env` can be empty
+- Run `docker-compose -f compose-prod.yml up --build`
 
-https://github.com/malavolti/HOWTO-Install-and-Configure-Shibboleth-Identity-Provider/blob/master/HOWTO%20Install%20and%20Configure%20a%20Shibboleth%20v3.2.1%20on%20Ubuntu%20Linux%20LTS%2014.04%20with%20Tomcat%208%20only.md
-a sample config - steps to configure 3.2
+# Resources
+- https://shibboleth.net/products/identity-provider.html
+- https://wiki.shibboleth.net/confluence/display/IDP30/Installation+Directory+and+Configuration+Files
+- http://www.jeesty.com/shibboleth Description of how Shibd works with Apache
+- https://github.com/UNINETT/mod_auth_mellon
diff --git a/nginx-example/idp.conf b/nginx-example/idp.conf
new file mode 100644
index 0000000..692a8fe
--- /dev/null
+++ b/nginx-example/idp.conf
@@ -0,0 +1,36 @@
+upstream idp {
+  server shibboleth-docker:8080;
+}
+
+server {
+  listen 80;
+  server_name IDP_HOSTNAME;
+  location / {
+    return 302 https://$host$request_uri;
+  }
+}
+
+server {
+  listen 443 ssl;
+  server_name IDP_HOSTNAME;
+  
+  ssl on;
+  ssl_certificate /opt/certs/idp-bundle.pem;
+  ssl_certificate_key /opt/certs/idp.key;
+  ssl_session_timeout 1d;
+  ssl_session_cache shared:SSL:50m;
+  ssl_session_tickets off;
+
+  ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
+  ssl_ciphers 'ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-RSA-AES256-SHA256:DHE-RSA-AES256-SHA:ECDHE-ECDSA-DES-CBC3-SHA:ECDHE-RSA-DES-CBC3-SHA:EDH-RSA-DES-CBC3-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:DES-CBC3-SHA:!DSS';
+  ssl_prefer_server_ciphers on;
+
+	location / {
+		proxy_pass http://idp;
+		proxy_set_header Host $host;
+		proxy_set_header X-Forwarded-for $remote_addr;
+		proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_set_header X-Forwarded-Port  $server_port;
+    add_header X-Frame-Options "SAMEORIGIN";
+  }
+}