Admin Guide: Shibboleth

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: 
    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.