Shibboleth IdP Integration Guide

This guide shows how to connect your Shibboleth Identity Provider to Mailzzy using SAML 2.0, so your team signs in to Mailzzy with their institutional account. Mailzzy acts as the service provider (SP) and your Shibboleth IdP as the identity provider (IdP). The steps apply to Shibboleth IdP 5.x and 4.x.

Once setup is complete, people in your email domain click Sign in with SSO on the Mailzzy sign-in page, enter their work email, and authenticate on your Shibboleth login page.

Before You Begin

Make sure you have the following:

• Enterprise SSO on your Mailzzy plan. If the Enterprise SSO tab shows "Enterprise SSO isn't included in your plan," contact support@mailzzy.com before continuing.

• A Mailzzy administrator account. The Enterprise SSO tab is only visible to administrators.

• Administrative access to your Shibboleth IdP configuration, typically the /opt/shibboleth-idp directory.

• An IdP that already authenticates your users (for example, against LDAP or Active Directory) and resolves an email attribute for them, usually mail.

• The email domains your team signs in with, such as example.edu. Mailzzy decides who is sent to SSO by matching the domain of the email address a user signs in with.

• Email addresses at your IdP that match the addresses your team uses in Mailzzy. Mailzzy identifies users by email.

Each Mailzzy account can have one SAML 2.0 connector and one OIDC connector, and only one of them can be active at a time.

Step 1: Reserve a SAML Connector in Mailzzy

1. In the top-right corner of Mailzzy, click the dropdown arrow next to your profile name and email, then select Security.
2. Open the Enterprise SSO tab and click Add Connector.
3. Under Protocol, choose SAML 2.0.
4. Enter a Connector name, such as shibboleth. The name can't be changed later.
5. In Email Domains, type each domain that should use this connector and press Enter.
6. Leave Require SSO for users on these domains turned off for now. You'll turn it on in Step 9.
7. Keep Send login hint turned on.
8. To create Mailzzy accounts automatically the first time new users sign in, turn on Automatically onboard new SSO users. Leave it off if you'll invite users yourself.
9. Click Reserve connector.

Mailzzy reserves the connector and shows its service provider values. Each value has a Copy button, and you can reopen them at any time from the connector's More actions menu (⋮) with SP Setup Info.

Step 2: Collect Your Shibboleth IdP Details

Your Shibboleth administrator collects these values for the Mailzzy administrator:

Mailzzy sends its sign-in requests with the HTTP-Redirect binding, so use the Redirect/SSO endpoint.

Mailzzy can also read these values from a metadata URL, such as https://your-idp-host/idp/shibboleth. Use that option only if the metadata is kept up to date (the file generated at install time isn't updated automatically when keys or endpoints change), the URL is reachable from the internet, and it's served with a publicly trusted HTTPS certificate. Otherwise, use manual entry.

Step 3: Enter Your IdP Details and Activate SSO

1. If the dialog from Step 1 is still open, click I've configured my IdP. With Shibboleth, you continue here before the IdP is configured, because the IdP needs the SP metadata this step publishes. If you closed the dialog, open the connector's More actions menu (⋮) and select Edit.
2. Under IdP Configuration, choose Manual entry.
3. Enter the IdP Entity ID / Issuer and IdP SSO URL from Step 2.
4. In IdP Signing Certificate (PEM), paste the whole certificate, including the BEGIN CERTIFICATE and END CERTIFICATE lines.
5. Click Activate SSO (or Save Changes if you opened Edit).

Mailzzy confirms "SSO is now live for this connector," and the connector's status changes to Live. Opening the SP Entity ID / Audience URI / Metadata URL in a browser now returns an XML document.

Step 4: Load the Mailzzy SP Metadata into Shibboleth

The Mailzzy SP metadata contains its entity ID, its ACS URL, and the certificates it uses to sign sign-in requests and decrypt assertions. Mailzzy signs every sign-in request, so Shibboleth needs this metadata, certificate included. A hand-written metadata entry without the certificate won't work.

The metadata isn't signed, so save a reviewed copy on the IdP rather than fetching it live:

1. Download the metadata to the IdP's metadata directory, replacing the URL with your SP Entity ID / Audience URI / Metadata URL. A Mailzzy administrator can also download the file from the connector's More actions menu (⋮) with Download metadata.xml.

curl -o /opt/shibboleth-idp/metadata/mailzzy-sp.xml \
  "PASTE-YOUR-SP-ENTITY-ID-HERE"

2. Open the file and check that its entityID matches the SP Entity ID exactly.
3. In conf/metadata-providers.xml, add a provider inside the root MetadataProvider element:

<MetadataProvider id="Mailzzy" xsi:type="FilesystemMetadataProvider"
                  metadataFile="%{idp.home}/metadata/mailzzy-sp.xml"/>

The Mailzzy signing key pair is valid for three years. Download the metadata again whenever the connector's certificate changes.

Step 5: Send the Email Address as the NameID

Mailzzy identifies users by email, but Shibboleth sends a random, one-time (transient) NameID by default. Change that for Mailzzy:

1. In conf/saml-nameid.xml, enable the email generator inside the shibboleth.SAML2NameIDGenerators list. It ships commented out. If your email attribute has a different ID in attribute-resolver.xml, use that ID instead of mail.

<bean parent="shibboleth.SAML2AttributeSourcedGenerator"
    p:omitQualifiers="true"
    p:format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
    p:attributeSourceIds="#{ {'mail'} }" />

2. In conf/relying-party.xml, add an override for Mailzzy inside the shibboleth.RelyingPartyOverrides list, using your SP Entity ID:

<bean id="Mailzzy" parent="RelyingPartyByName"
      c:relyingPartyIds="PASTE-YOUR-SP-ENTITY-ID-HERE">
    <property name="profileConfigurations">
        <list>
            <bean parent="SAML2.SSO"
                  p:nameIDFormatPrecedence="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress" />
        </list>
    </property>
</bean>

Step 6: Release Attributes to Mailzzy

The NameID generator can only use attributes that are released to Mailzzy, so mail must be released. In conf/attribute-filter.xml, add this policy inside the AttributeFilterPolicyGroup element, using your SP Entity ID. Include the name attributes only if your attribute resolver defines them:

<AttributeFilterPolicy id="Mailzzy">
    <PolicyRequirementRule xsi:type="Requester"
        value="PASTE-YOUR-SP-ENTITY-ID-HERE" />
    <AttributeRule attributeID="mail" permitAny="true" />
    <!-- Optional, to fill in names in Mailzzy: -->
    <AttributeRule attributeID="givenName" permitAny="true" />
    <AttributeRule attributeID="sn" permitAny="true" />
    <AttributeRule attributeID="displayName" permitAny="true" />
</AttributeFilterPolicy>

No attribute mapping is needed in Mailzzy. It already recognizes the attribute names Shibboleth sends by default:

New users are always created from these values. For people who already have an account, names are updated at sign-in only if you turn on the matching Sync on login option in the connector's More actions menu (⋮) under Attribute mapping.

Step 7: Reload Shibboleth and Check the Logs

Reload the services you changed, or restart the IdP's servlet container instead:

cd /opt/shibboleth-idp
bin/reload-service.sh -id shibboleth.MetadataResolverService
bin/reload-service.sh -id shibboleth.RelyingPartyResolverService
bin/reload-service.sh -id shibboleth.AttributeFilterService
bin/reload-service.sh -id shibboleth.NameIdentifierGenerationService

reload-service.sh contacts the IdP at http://localhost/idp by default. If your IdP listens only on HTTPS, add -u https://localhost/idp to each command; the script must also trust the IdP's HTTPS certificate.

Check logs/idp-process.log for errors and for a line confirming that the Mailzzy metadata loaded (it mentions FilesystemMetadataResolver Mailzzy and mailzzy-sp.xml).

To preview exactly what Mailzzy will receive for a user, run this on the IdP host (the admin pages are limited to localhost by default), with your SP Entity ID URL-encoded:

curl -k "https://localhost/idp/profile/admin/resolvertest?principal=USERNAME&requester=URL-ENCODED-SP-ENTITY-ID&saml2"

The output should show a NameID with the emailAddress format and the user's email address.

Step 8: Test Single Sign-On

1. Open a private browser window and go to the Mailzzy sign-in page.
2. Click Sign in with SSO, enter a work email in your domain, and click Continue to your organization's single sign-on.
3. Sign in on your Shibboleth login page with your Shibboleth username and password. Shibboleth doesn't pre-fill the username from the login hint by default, so users type it themselves.
4. You should land on the Mailzzy dashboard, signed in as that user.

You can also start a test from the connector's More actions menu (⋮) with Test SSO. If you turned on Automatically onboard new SSO users, also test with someone who doesn't have a Mailzzy account yet, and confirm their account is created on first sign-in.

Step 9: Require SSO for Your Domain

Once sign-in works, open the connector's More actions menu (⋮), select Edit, and turn on Require SSO for users on these domains. Password sign-in is then blocked for those domains.

Choose a Password-fallback user (break-glass account), an administrator who can still sign in with a password if your IdP is unavailable. It defaults to the person who set up SSO. Then click Save Changes.

Troubleshooting

Remove the Integration

1. In Mailzzy, open the connector's More actions menu (⋮) and select Delete.
2. On your IdP, remove the Mailzzy MetadataProvider, the relying-party override, and the attribute filter policy, then reload.

Deleting the connector stops SSO for its domains immediately. Users who never set a Mailzzy password will need to reset it to sign in.

Need Help?

If you get stuck, email support@mailzzy.com with your connector name, your Shibboleth IdP version, the approximate time of a failed sign-in, and any related lines from logs/idp-process.log. Never send private keys or passwords.