Shibboleth Integration - wiso-forschungslabor/hroot-documentation GitHub Wiki

This page describes the optional SAML authentication via Shibboleth (DFN-AAI / eduGAIN) using omniauth-saml, and how the system handles enrollment/matriculation verification for students.

Shibboleth is a Single Sign-On (SSO) web authentication system based on the SAML (Security Assertion Markup Language) standard. It is widely used in academic federations (like DFN-AAI in Germany or eduGAIN internationally). By integrating Shibboleth, universities can configure hroot to allow students and staff to log in using their official university credentials. This eliminates the need for them to create separate passwords and provides an direct way to verify their university status.

---

Shibboleth is enabled via deployment environment variables and configured in the administration interface:

1. Backend Activation via .env file:
   • Set SHIBBOLETH_ENABLED=true to enable the SAML authentication backend.
   • Note: Loading the OmniAuth SAML authentication strategy occurs during application boot and requires a server restart.
2. Branding & Styling via UI:
   • Go to Site Settings -> Design & Layout (/admin/options/design under System & Plugins).
   • In the Logo & Shibboleth section, configure the Institution Name (e.g. UHH, Uni Hamburg) and customize the Shibboleth login button colors (background & text).
3. Pool Verification & Auto-Assignment via UI:
   • Go to Site Settings -> Participant Pools (/admin/options/pools under Participants & Master Data).
   • Edit a pool to configure:
     • Shibboleth-Nutzer automatisch diesem Pool hinzufügen (auto_assign_shibboleth): Automatically enrols Shibboleth users in this pool upon login.
     • Matrikelbescheinigung/Studiennachweis erforderlich (requires_matriculation): Enforces valid matriculation proof for sessions in this pool.
     • Verifizierungs-Modus (verification_mode): Set to shibboleth, document_upload, or shibboleth_or_document.

---

The application reads configurations from the .env file. Adjust these settings inside your .env:

• SHIBBOLETH_ENABLED=false - Enable SAML/Shibboleth login and strategy on boot.
• ENROLLMENT_VERIFICATION_ENABLED=true - Global switch requiring students to have a valid matriculation proof.
• SHIBBOLETH_DISCOVERY_MODE=embedded - Discovery mode (direct, embedded, or redirect). See details below.
• SHIBBOLETH_DS_URL - Discovery service URL (used when SHIBBOLETH_DISCOVERY_MODE=redirect).
• SHIBBOLETH_SP_ENTITY_ID - Your Service Provider (SP) entity ID (e.g. https://hroot.your-uni.edu/shibboleth).
• SHIBBOLETH_IDP_ENTITY_ID - The Identity Provider (IdP) entity ID of your home university.
• SHIBBOLETH_PREFERRED_IDP_NAME - Display name of your primary institution (e.g., Universität Hamburg).
• SHIBBOLETH_IDP_SSO_TARGET_URL - Target redirection URL of your IdP SSO endpoint.
• SHIBBOLETH_IDP_SLO_TARGET_URL - Target redirection URL of your IdP Single Logout (SLO) endpoint (optional).
• SHIBBOLETH_CERT_PATH / SHIBBOLETH_KEY_PATH - Paths to the Service Provider certificates used for request signing and decryption.
• SHIBBOLETH_IDP_CERT_PATH / SHIBBOLETH_IDP_METADATA_URL - Certificate or metadata XML URL for verifying the IdP.
• OMNIAUTH_FULL_HOST - The full domain URL (including protocol) matching your registered SP metadata.

---

---

Hroot supports both single-institution deployments (e.g. dedicated to a single university) and multi-institution federation setups (e.g. DFN-AAI, eduGAIN).

Button labels and titles automatically adapt depending on whether a preferred home institution is configured:

1. Specific Institution Mode (Default for Single University Setups):

   • Configuration: Set SHIBBOLETH_PREFERRED_IDP_NAME="UHH" (or in UI under Site Settings -> Design -> Shibboleth).
   • Button Labels: Buttons and headlines use the specific institution name (e.g., "Login / Registrierung via UHH", "Felder via UHH befüllen", "Via UHH verifizieren").
   • Behavior: Clicking the primary button immediately directs to the home institution's IdP. In redirect mode, a secondary link "Andere Hochschule / eduGAIN wählen" is displayed below.

2. Generic Discovery / Federation Mode (For Cross-Institutional / WAYF-Only Setups):

   • Configuration: Leave SHIBBOLETH_PREFERRED_IDP_NAME unset / empty, and set SHIBBOLETH_DISCOVERY_MODE=redirect.
   • Button Labels: Buttons automatically switch to a generic, neutral label (e.g., "Login / Registrierung via Hochschul-Account (Shibboleth)" in German, "Login / Registration via University Account (SSO)" in English).
   • Behavior: Clicking the primary button routes the user directly to the central DFN WAYF / Discovery Service (SHIBBOLETH_DS_URL) where they can select from all participating institutions. No duplicate secondary link is shown.

---

Hroot supports three discovery service modes to control how users choose their Identity Provider (IdP):

• Use Case: Your hroot instance is strictly dedicated to a single university or organisation.
• Behavior: No institution selection step. Clicking "Login via " immediately redirects to the configured SHIBBOLETH_IDP_SSO_TARGET_URL.
• Required Configuration:

  SHIBBOLETH_DISCOVERY_MODE=direct
  SHIBBOLETH_PREFERRED_IDP_NAME="Uni Köln"
  SHIBBOLETH_IDP_ENTITY_ID=https://idp.example.com/shibboleth
  SHIBBOLETH_IDP_SSO_TARGET_URL=https://idp.example.com/idp/profile/SAML2/Redirect/SSO
  SHIBBOLETH_IDP_CERT_PATH=/rails/certs/idp-cert.pem # or SHIBBOLETH_IDP_METADATA_URL

• Use Case: Your institution participates in DFN-AAI or eduGAIN, and you want participants from other partner universities to be able to log in without leaving the page.
• Behavior: Embeds an interactive institution search widget directly on the hroot login page. Users can search and select any university in the federation. Your configured home institution is prominently displayed at the top for one-click access.
• Required Configuration:

  SHIBBOLETH_DISCOVERY_MODE=embedded
  SHIBBOLETH_IDP_ENTITY_ID=https://login.uni-hamburg.de/idp/shibboleth
  SHIBBOLETH_PREFERRED_IDP_NAME="UHH"

• Use Case: Classic federation setup delegating the institution selection to a centralized discovery service (DFN WAYF).
• Behavior:
  • If SHIBBOLETH_PREFERRED_IDP_NAME is set: Main button logs into home university; sub-link leads to WAYF for external universities.
  • If SHIBBOLETH_PREFERRED_IDP_NAME is empty: Main button shows generic label and leads directly to the WAYF selector.
• Required Configuration:

  SHIBBOLETH_DISCOVERY_MODE=redirect
  # DFN Production Federation:
  SHIBBOLETH_DS_URL=https://wayf.aai.dfn.de/DFN-AAI/wayf
  # Or DFN Test Federation:
  # SHIBBOLETH_DS_URL=https://wayf.aai.dfn.de/DFN-AAI-Test/wayf

---

When student verification is active, hroot restricts students from registering for experiment sessions unless they have valid, unexpired enrollment proof. The system determines verification via two layers: pool-specific rules and legacy global overrides.

The enrollment verification flow relies on two distinct settings:

• Requires Matriculation (requires_matriculation): Configured per pool, this flag specifies whether members of that pool are required to have a valid matriculation status (tracked via matrikel_date). If active, the system checks whether the user's matrikel_date is in the future.
• Verification Mode (verification_mode): Determines the method of verifying this matriculation status. Shibboleth functions as an automatic verification method.
  • Without Shibboleth (Manual Upload): The user uploads a file, which requires manual approval from an administrator to extend their matrikel_date (usually to the end of the current semester).
  • With Shibboleth (Automatic): Logging in via Shibboleth instantly extends the user's matrikel_date automatically to the end of the current semester (if shibboleth_matrikel_auto_update is enabled in configuration), allowing the user to bypass manual admin approval and register immediately.

If the student belongs to one or more participant pools, the pool's specific configuration determines how they are verified (configured under Site Settings -> Participant Pools -> Edit Pool -> Verification Mode):

• shibboleth: The student is required to log in via Shibboleth. If they did not authenticate using SAML, they are blocked from registering and prompted to log in via Shibboleth.
• document_upload: The student must upload a proof of enrollment document (e.g., Certificate of Enrollment / Immatrikulationsbescheinigung).
• shibboleth_or_document: The student can satisfy verification by either logging in via Shibboleth OR uploading a verification document.

For students who do not have a verified matriculation status (either because their university doesn't use Shibboleth, they registered manually, or their matriculation proof has expired):

1. Redirection to Upload Page: When trying to sign up for an active session, they are prevented from registering and redirected to the /enroll/matrikel_verification page.
2. Document Upload: They must upload a verification file (such as a photo or PDF of their student ID card or current semester certificate).
3. Pending Registration Permitted: Upon uploading the document, their account's verification_status changes to pending. While in pending status, they are temporarily allowed to sign up for sessions so they do not miss slot deadlines.
4. Automatic Alerts: When they sign up with a pending status, the system automatically sends them an email (using the Missing Matriculation Proof mail template configured in Site Settings) reminding them that their proof must be verified by the admin before the experiment session starts.
5. Admin Approval: An administrator can view all pending verification files in the Users menu, check the upload, and click Verify or Reject. Approving sets their matrikel_date expiration (usually the end of the current semester) and marks them as verified.

---

The attributes returned by your IdP may vary. The app supports dynamic attribute mapping from environment variables (.env):

• SHIBBOLETH_MAP_FIRSTNAME - map first name attribute (e.g. urn:oid:2.5.4.42 or givenName)
• SHIBBOLETH_MAP_LASTNAME - map last name attribute (e.g. urn:oid:2.5.4.4 or sn)
• SHIBBOLETH_MAP_EMAIL - map email attribute (e.g. urn:oid:0.9.2342.19200300.100.1.3 or mail)
• SHIBBOLETH_MAP_CUSTOM_MATRIKEL - map matriculation number (e.g. urn:oid:1.3.6.1.4.1.25178.1.2.14 or schacPersonalUniqueCode)
• SHIBBOLETH_MAP_CUSTOM_COURSE_OF_STUDIES - map subject/course (e.g. urn:oid:1.3.6.1.4.1.22177.400.1.1.3.5 or dfnEduPersonFieldOfStudyString)
• SHIBBOLETH_MAP_AFFILIATION - map affiliation attribute (defaults to urn:oid:1.3.6.1.4.1.5923.1.1.1.1 or eduPersonAffiliation)
• SHIBBOLETH_AFFILIATIONS_VERIFIED - comma-separated list of affiliations considered verified/valid (defaults to student)

1. Providing SP Metadata XML: Host metadata XML under a public HTTPS URL (https://<domain>/users/auth/saml/metadata) or deliver XML directly to IdP admins.
2. Metadata Requirements:
   • EntityID: Unique identifier of your SP (e.g. https://hroot.example.org/shibboleth)
   • ACS URL: E.g., https://<host>/users/auth/saml/callback (HTTP-POST)
   • KeyDescriptor: Public certificate of your SP for signature verification.
   • AttributeConsumingService: List of requested attributes.

When a participant authenticates via Shibboleth:

1. Existing Account Linking: If the email matches an existing account, the user is prompted to link their account to Shibboleth.
2. Account Creation: If no account exists, a new hroot account is created automatically using details retrieved from the Shibboleth metadata (first name, last name, email).

1. Verify Routes: Verify that the Shibboleth routes are loaded by running:

   bin/rails routes | grep saml

2. Check Strategy Registration: To confirm that the OmniAuth strategy successfully loaded on boot, run:

   bin/rails runner "puts Rails.configuration.x.shibboleth_enabled; puts defined?(OmniAuth) ? OmniAuth.strategies.inspect : 'OmniAuth not loaded'"

3. Check Logs: If redirects fail or the signature verification fails, check the logs in log/production.log or log/development.log and make sure your OMNIAUTH_FULL_HOST and SP certificates match the metadata uploaded to the DFN/eduGAIN registry.