mod_access_url

Share protected pages, images and feeds using signed URLs with the signing user's view permissions. Recipients do not need to log in as that user. Typical uses include private calendar feeds, HTML certificate rendering and sharing a survey with people who do not have an account.

Setup and administration

Install the zotonic_mod_access_url application and enable mod_access_url for the site. The module adds a Share link to this page widget to the admin edit sidebar. An authenticated user who can view the resource can generate and copy a link, choosing a duration or an indefinite link.

There are no module configuration keys. Signing secrets are created on demand as mod_access_url identities associated with the signing user.

Generate a signed URL

Add z_access_url to a dispatch URL generated in an authenticated context:

{% url page id=id z_access_url absolute_url %}

To make the link valid for one hour:

{% url page id=id z_access_url z_access_url_valid_for=3600 absolute_url %}

z_access_url_valid_for accepts an integer duration in seconds or a binary date expression understood by z_datetime:to_datetime/1, such as +day or +week. Omitting it creates a link without an expiry. The generated query contains the absolute expiry timestamp; do not pass that timestamp back as an integer duration.

The same arguments can be passed to z_dispatcher:url_for/3, or set on a context when generating resource page URLs. m_access_url:generate_url/2,3 provides a convenience API for absolute resource URLs. See m_access_url for model calls.

An integer z_access_url selects another signing user only when the caller can edit that user's resource. Signing explicitly for user 1 requires the caller to be user 1. Without a signing user, the URL is returned unsigned.

Permissions and respondent identity

A valid link supplies an additional context for resource and property view checks. It does not replace the visitor's logged-in identity or grant edit, update or delete permissions. Invalid, expired and unknown tokens leave normal request permissions in effect.

For surveys using the standard submission handler, an anonymous recipient's answers remain anonymous in the user_id column and may be associated with a browser session. A logged-in recipient's answers belong to that recipient, not the signer. Survey settings and custom submission handlers still apply; a signed link is not a general authorization to perform writes.

The module runs at priority 10 so its view grants can be evaluated before an ACL module returns a denial. Custom ACL integrations must preserve that ordering.

Images, browser sessions and expiry

Image URLs generated through the image dispatch while rendering a validated access URL are signed using the validated signing user. They retain the parent link's exact expiry, including the absence of an expiry. This allows renderers without the visitor's login cookies to fetch protected images.

Resources granted view access can also be registered for the visitor's session for four hours. These grants allow subsequent requests, such as survey pages, to access those resources without resending the original signature. Grants are kept in a site-specific ETS table on the current node and are lost when that table is recreated. The four-hour grant period is independent of the signed URL's expiry and can outlast it.

The _html_body.tpl contribution uses m.access_url.reload_needed to reload a signed page after the Cotonic session cookie becomes available. Custom page layouts should include the standard Zotonic body contributions for this behavior. Image signatures themselves do not require a browser session.

Signature compatibility and diagnostics

Verification accepts current Base64URL signatures and earlier Base64 signatures. Links without an expiry can also use the historical Erlang-term signatures, including the old use_absolute_url variant. Compatibility checks reconstruct server-side data; they never deserialize a term supplied by the requester.

Failure logs distinguish expired, invalid_expiry, malformed_signature, signature_mismatch and unknown_user_token. Successful verification logs the signature format at debug level. These logs omit tokens, signatures and secrets. Added application parameters, including tracking parameters, invalidate a link.

Sharing and scope

Anyone holding a valid link can use it. Share links only with intended recipients and avoid exposing them in public pages or logs. The signature binds the dispatch and application arguments; language and internal access-URL arguments are handled separately. It does not turn arbitrary links on the page into signed links. Validated responses receive a noindex header.

The public register_resource/2 helper records a session grant without checking ACLs itself. Use it only after authorizing access; is_resource_registered/2 checks whether that session grant is still valid.