system/deployment/Shibboleth.md

+
+Some of our ReSeeD instances use Shibboleth for login. This has the following requirements:
+- The ReSeeD instance must use a valid TLS certificate.
+- Both the ReSeeD instance and the IDP / IDP federation (for example: AAI) that is to be used must have been configured to trust each other.
+  At RUB, the IDP / IDP federation are handled by the IAS team within IT.SERVICES. They require the following data:
+  - `entityID` of our ReSeeD instance (`SAML_SP_ID` in the `.env` file)
+  - The (new) TLS certificate (`SAML_SP_CERTIFICATE` in the `.env` file)
+  - The ReSeeD instance's metadata XML URL (for example `https://reseed.example.net/users/auth/saml/metadata`)
+  - The list of attributes that the ReSeeD instance should be allowed to request. For example, our production instance uses:
+    - `urn:oasis:names:tc:SAML:attribute:pairwise-id`
+    - `urn:mace:dir:attribute-def:displayName` / `urn:oid:2.16.840.1.113730.3.1.241`
+    - `urn:mace:dir:attribute-def:mail` / `urn:oid:0.9.2342.19200300.100.1.3`
+    - `urn:mace:dir:attribute-def:eduPersonAffiliation` / `urn:oid:1.3.6.1.4.1.5923.1.1.1.1`
+- The following variables within the ReSeeD instance's `.env` file must have been configured:
+  ```shell
+  APPLICATION_URL="https://reseed.example.net"
+  USE_SAML=true
+  SAML_SP_ID=${APPLICATION_URL}
+  SAML_IDP_SERVICE_URL="https://idp.example.net/idp/shibboleth"
+  SAML_IDP_SSO_SERVICE_URL="https://idp.example.net/idp/profile/SAML2/Redirect/SSO"
+  SAML_IDP_CERT="-----BEGIN CERTIFICATE-----ONLY_IDP_LEAF_CERT_WITHOUT_CHAIN_FROM_SAML_IDP_SSO_SERVICE_URL_AND_MUST_NOT_CONTAIN_LINE_BREAKS-----END CERTIFICATE-----"
+  SAML_SP_CERTIFICATE="-----BEGIN CERTIFICATE-----ONLY_LEAF_CERT_WITHOUT_CHAIN_AND_MUST_NOT_CONTAIN_LINE_BREAKS-----END CERTIFICATE-----"
+  SAML_SP_CERTIFICATE_KEY="-----BEGIN PRIVATE KEY-----ONLY_PRIVATE_KEY_AND_MUST_NOT_CONTAIN_LINE_BREAKS-----END PRIVATE KEY-----"
+  SAML_ATTRIBUTE_UID="urn:oasis:names:tc:SAML:attribute:pairwise-id"
+  # "urn:mace:dir:attribute-def:displayName" = "urn:oid:2.16.840.1.113730.3.1.241"
+  SAML_ATTRIBUTE_NAME="urn:oid:2.16.840.1.113730.3.1.241"
+  # "urn:mace:dir:attribute-def:mail" = "urn:oid:0.9.2342.19200300.100.1.3"
+  SAML_ATTRIBUTE_EMAIL="urn:oid:0.9.2342.19200300.100.1.3"
+  # "urn:mace:dir:attribute-def:eduPersonAffiliation" = "urn:oid:1.3.6.1.4.1.5923.1.1.1.1"
+  SAML_ATTRIBUTE_ROLE="urn:oid:1.3.6.1.4.1.5923.1.1.1.1"
+  # If Authorization is restricted, only users with affiliation=staff are allowed access
+  SAML_RESTRICT_AUTHORIZATION=true
+  ```
+- The webserver must use the same certificate/private key as specified in the `SAML_SP_CERTIFICATE` and `SAML_SP_CERTIFICATE_KEY` variables and as configured on the IDP / IDP federation.
+- The system's real time clock must be in sync with the IDP's RTC. In practice, this essentially boils down to "NTP must be used".
+
+In theory, we *could* use Let's Encrypt certificates, but because the TLS certificate must be manually configured on the IDP side, we use GEANT certificates, because those are valid for a whole year instead of only 90 days.
+
+
+## Certificate renewal
+ReSeeD can currently only use a single certificate for Shibboleth, but the Shibboleth IDPs with which our ReSeeD instances interact support multiple certificates per SP. Therefore, when renewing the certificate, the ideal process is as follows:
+1. Request/Obtain a new certificate, and prepare an updated `.env` file and an updated nginx config to use that new certificate, but do not use/enable both updated configs just yet. Do this a few days before the old ReSeeD/SP certificate expires, because in some Shibboleth federations, it may take 24h for a new certificate to propagate throughout all member IDPs in the federation.
+2. Ask your local IDP admin to add the new certificate to their IDP/the IDP federation. For this, you will usually have to provide them with the following information:
+   - the certificate itself (only the leaf certificate in PEM format, without trust chain and without private key),
+   - the `entityID` of your ReSeeD instance (this is the `SAML_SP_ID` variable from the `.env` file),
+   - the IDP that you use (this is the `SAML_IDP_SERVICE_URL` variable from the `.env` file).
+3. After they have added the new cert to the IDP / IDP federation, wait 24h before actually switching the nginx config and the `.env` file to the new certificate, because in some Shibboleth federations, it can take up to 24h until all member IDPs have fetched the current metadata (which includes the SP certificate that the ReSeeD instances uses).
+4. Test everything, then inform your local IDP admin that the old certificate can now be removed from the IDP/Shibboleth federation.