Deep Linking with Shibboleth

Part of the Deep Linking series. This page covers the Shibboleth (SAML) authentication path. If you have not read the main deep-linking overview yet, start there first — it explains what deep linking is, how it works at a high level, and where each authentication method stands.

How It Works

Shibboleth is a SAML-based federated identity solution. Unlike OpenAthens (a managed cloud service), Shibboleth is open-source and self-hosted by institutions. From a deep-linking perspective, Shibboleth follows the standard SAML mechanism: the RelayState field.

When a SAML authentication flow begins, the Service Provider can include an opaque RelayState value in the authentication request. The Identity Provider carries this value through the flow untouched and includes it in the response. The SP then reads RelayState on the way back and uses it to determine where to send the user.

In our case, the Shibboleth SP running on our server (shibboleth.statista.com) handles this natively — storing the requested URL as RelayState at the start of the flow and using it to redirect the user after a successful assertion.

For background on our Shibboleth setup, see Shibboleth Overview.

The Full Flow

sequenceDiagram
    actor User
    participant SP as Shibboleth SP<br/>(shibboleth.statista.com)
    participant DS as Discovery Service<br/>(optional)
    participant IdP as Institution IdP<br/>(SAML)
    participant Target as Target Resource Page

    User->>SP: Clicks deep link (e.g. discovery system)
    SP->>SP: Extract target URL, store as RelayState
    SP->>DS: Redirect to Discovery Service (if needed)
    DS->>SP: Institution selected → redirect back
    SP->>IdP: SAML AuthnRequest (with RelayState = target URL)
    IdP-->>User: Login prompt
    User->>IdP: Credentials
    IdP-->>SP: SAML Assertion + RelayState (POST)
    SP->>SP: Validate assertion, establish session
    SP->>User: 302 → target URL (from RelayState) ✓
    User->>Target: Lands on the specific page

WAYFless URLs

Shibboleth supports WAYFless login — links that skip the institution discovery page and target a specific IdP directly. The URL pattern is:

https://shibboleth.statista.com/Shibboleth.sso/Login?entityID={idp_entity_id}&target={target_url}

Parameter	Meaning
`entityID`	The SAML entityID of the user's institution IdP
`target`	The URL the user should land on after authentication

When the Shibboleth SP processes this request, it initiates an AuthnRequest directed at the specified IdP, and the target value is carried as RelayState through the SAML exchange.

Discovery systems, link resolvers, and library portals can construct these WAYFless URLs using the institution's entityID (available from the federation metadata, e.g. eduGAIN) and the URL of the specific resource page.

What the Shibboleth SP Handles Automatically

Our Shibboleth SP handles the RelayState mechanics automatically — there is no custom code in our application layer responsible for storing or reading the target URL. The SP software manages:

Extracting the target parameter from the WAYFless URL.
Embedding it in the SAML AuthnRequest as RelayState.
Reading it from the IdP's POST response after assertion validation.
Redirecting the user to that URL to complete the journey.

What the application (index.php on the Shibboleth server) does is redirect the user to the correct Statista platform (e.g. de.statista.com) based on browser locale. The target URL's path is preserved through this redirect.

Registering Deep-Link URL Patterns

If you need discovery systems or link resolvers to generate WAYFless deep links automatically, you can register a link syntax pattern in the OpenAthens SP dashboard for the SAML federation side. The pattern uses two placeholders:

Placeholder	Replaced with
`{entity}`	The federation entityID of the user's institution
`{target}`	The URL of the specific resource page

Example registered pattern:

https://shibboleth.statista.com/Shibboleth.sso/Login?entityID={entity}&target={target}

This allows discovery systems that know the user's institution to construct fully resolved deep links automatically, without any user interaction beyond clicking.

Common Pitfalls

RelayState length limits. Some IdPs and SAML libraries impose a maximum length on RelayState. If your target URLs are long (e.g. URLs with many query parameters), they may be silently truncated, causing the redirect to fail. Consider shortening target URLs before embedding them, or encoding a short reference key that your application can look up.

The entityID is not URL-encoded. Federation entityIDs look like URLs themselves (e.g. https://idp.bigstate.edu/shibboleth). When embedded as a query parameter, they must be URL-encoded. Forgetting this causes the SP to misparse the URL.

The user is sent to a discovery page despite a WAYFless URL. Some Shibboleth configurations override the entityID parameter and always route through a discovery service. Check the SP configuration on the server to ensure WAYFless bypass is enabled for your use case.

Vendor URLs that break. Deep links are only as stable as the URLs they point to. Vendor platforms occasionally restructure their URL schemes, silently breaking stored links. This requires operational monitoring, not an engineering fix.