Shibboleth SSO Configuration Guide

This Shibboleth SSO configuration guide shows your Inkfree administrator and your Shibboleth administrator how to connect a Shibboleth Identity Provider (IdP) to Inkfree for single sign-on over SAML 2.0. Inkfree is the service provider (SP) and your Shibboleth IdP authenticates your users. The steps were tested with Shibboleth IdP 5 and also apply to version 4.

Once it's set up, people on your email domain sign in to Inkfree with their work email and authenticate at your Shibboleth login page. For other identity providers, see the SSO configuration guide or the Okta SSO configuration guide.

Setup Checklist

Two people usually share this work. Each step below ends with a Done when line so you can confirm it before moving on.

Order matters: Inkfree publishes its SP metadata only after the connector has your IdP details (Step 3). If your Shibboleth administrator downloads the metadata before then, the URL returns a 401 error.

Before You Begin

• Enterprise SSO on your Inkfree plan. If Settings → Enterprise SSO shows a plan-upgrade notice instead of Add Connector, contact the support team first.
• An Inkfree administrator account, plus administrative access to your Shibboleth IdP's configuration directory ($IDP_HOME, usually /opt/shibboleth-idp).
• A working IdP. Your IdP must already authenticate your users (for example, through LDAP, Active Directory, or Kerberos) and resolve an email attribute for them, usually mail.
• The email domains that will sign in through this connection, such as example.edu. Inkfree routes SSO by matching the domain of the user's email address to a connector.

Each Inkfree account can have one SAML 2.0 connector and one OIDC connector, and only one of them can be live at a time. Activating one pauses the other.

Step 1: Reserve a SAML Connector in Inkfree

Who: Inkfree admin

1. In Inkfree, go to Settings → Enterprise SSO.
2. Click Add Connector. A three-step dialog opens: Name & domains, Configure your IdP, and Submit IdP details.
3. Choose SAML 2.0 as the protocol.
4. Enter a Connector name, such as shibboleth.
5. In Email Domains, type each domain and press Enter to add it.
6. Leave Enforce SSO turned off for now. You'll turn it on in Step 10, after testing.
7. Turn on Automatically onboard new SSO users if people who don't have an Inkfree account yet should get one the first time they sign in. Leave it off if you'll invite users yourself.
8. Click Reserve connector.

Inkfree now shows your SP values, each with a Copy button. You can reopen them later from the connector's ⋮ menu by selecting RP Setup Info.

Note: The <registrationId> part is unique to your connector. Always copy the exact values from your own Inkfree account.

Send the SP Entity ID / Metadata URL to your Shibboleth administrator. The configuration in Steps 4 to 6 uses it in three places.

Done when: the connector appears in the list as Setup incomplete and you have the SP Entity ID.

Step 2: Collect Your Shibboleth IdP Values

Who: Shibboleth admin

Inkfree needs three values from your IdP, plus a fourth if you use single logout:

Inkfree sends its sign-in requests with the HTTP-Redirect binding, so give it the Redirect/SSO endpoint.

Inkfree can also read these values from your IdP's metadata URL, such as https://<your-idp-host>/idp/shibboleth. Use that option only if the metadata is accurate, the URL is reachable from the internet, and it's served with a publicly trusted HTTPS certificate. The metadata file Shibboleth generates at install time isn't updated automatically when you change keys or endpoints, so if in doubt, use the three values above.

Done when: you have the entity ID, the SSO URL, and the signing certificate file.

Step 3: Complete the Connector in Inkfree

Who: Inkfree admin

1. In Settings → Enterprise SSO, open the connector's ⋮ menu and select Complete setup. If the dialog from Step 1 is still open, click Continue to IdP details instead.
2. Under IdP Configuration, choose Manual entry and fill in the values from Step 2. If your Shibboleth administrator confirmed a usable metadata URL, choose Metadata URL and paste it instead.
3. Paste the whole certificate, including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines.
4. Keep Send login hint turned on. It pre-fills the user's email address on your Shibboleth login page.
5. Click Activate SSO. The connector's status changes to Live.

Note: If another connector is already live on your account, Inkfree asks you to confirm, and activating this one pauses the other.

Done when: the connector shows Live, and opening the SP Entity ID / Metadata URL in a browser returns an XML document instead of an error.

Step 4: Load Inkfree's SP Metadata into Shibboleth

Who: Shibboleth admin

Inkfree's SP metadata contains its entity ID, its ACS URL, and the certificates it uses to sign requests and decrypt assertions. Your IdP needs it to trust Inkfree's sign-in requests. The metadata isn't signed, so save a reviewed copy on the IdP rather than fetching it live.

First, download the metadata into the IdP's metadata directory, using your own SP Entity ID:

curl -o /opt/shibboleth-idp/metadata/inkfree-sp.xml \
  "https://api.inkfree.app/core/saml2/service-provider-metadata/<registrationId>"

Check that the entityID in the downloaded file matches the SP Entity ID from Step 1 exactly. Then add a provider inside the root <MetadataProvider> element of conf/metadata-providers.xml:

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

Inkfree's signing key pair is valid for three years. Download the metadata again whenever Inkfree tells you the connector's certificate has changed.

Done when: inkfree-sp.xml is in the metadata directory and the provider is in metadata-providers.xml.

Step 5: Send the User's Email as the SAML NameID

Who: Shibboleth admin

Inkfree identifies users by email address. Shibboleth sends a random, one-time (transient) NameID by default, so change that for Inkfree.

First, in conf/saml-nameid.xml, enable the email generator inside the shibboleth.SAML2NameIDGenerators list. It ships commented out:

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

Replace mail if your email attribute has a different ID in attribute-resolver.xml.

Then, in conf/relying-party.xml, add an override for Inkfree inside <util:list id="shibboleth.RelyingPartyOverrides">, using your SP Entity ID:

<bean id="Inkfree" parent="RelyingPartyByName"
      c:relyingPartyIds="https://api.inkfree.app/core/saml2/service-provider-metadata/<registrationId>">
    <property name="profileConfigurations">
        <list>
            <bean parent="SAML2.SSO"
                  p:nameIDFormatPrecedence="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress" />
        </list>
    </property>
</bean>

Done when: the email generator is active and the override names Inkfree's exact SP Entity ID.

Step 6: Release Attributes to Inkfree

Who: Shibboleth admin

The NameID generator from Step 5 can only use attributes that are released to Inkfree, so mail must be released. Add this policy inside <AttributeFilterPolicyGroup> in conf/attribute-filter.xml, using your SP Entity ID:

<AttributeFilterPolicy id="Inkfree">
    <PolicyRequirementRule xsi:type="Requester"
        value="https://api.inkfree.app/core/saml2/service-provider-metadata/<registrationId>" />
    <AttributeRule attributeID="mail" permitAny="true" />
    <!-- Optional, for names in Inkfree (see Step 8): -->
    <AttributeRule attributeID="givenName" permitAny="true" />
    <AttributeRule attributeID="sn" permitAny="true" />
    <AttributeRule attributeID="displayName" permitAny="true" />
</AttributeFilterPolicy>

Include only attributes your attribute resolver actually defines. Inkfree doesn't need anything beyond the email address.

Done when: the policy is in place with Inkfree's exact SP Entity ID.

Step 7: Reload Shibboleth and Check the Logs

Who: Shibboleth admin

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

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

Check logs/idp-process.log for errors, and for a line confirming the Inkfree metadata loaded:

FilesystemMetadataResolver Inkfree: New metadata successfully loaded for '.../metadata/inkfree-sp.xml'

To preview exactly what Inkfree will receive for a user, run this on the IdP host. The admin pages are limited to localhost by default:

curl -k "https://localhost/idp/profile/admin/resolvertest?principal=<username>&requester=<URL-encoded SP Entity ID>&saml2"

The output should show a NameID with Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress" and the user's email address.

Done when: the IdP reloaded without errors and the preview shows the email NameID.

Step 8: Map Name Attributes in Inkfree (Optional)

Who: Inkfree admin

Inkfree always takes the email address from the SAML response, from an email attribute first and otherwise from the NameID, so sign-in needs no mapping. To fill in first and last names, open the connector's ⋮ menu, select Attribute mapping, and map Shibboleth's attribute names. Shibboleth sends them as URNs by default:

To have Inkfree read the email address from an attribute rather than the NameID, expand Advanced on the connector and set Email Attribute to urn:oid:0.9.2342.19200300.100.1.3, the URN for mail.

Step 9: Test Sign-In

Who: Both

1. Open a private or incognito browser window and go to the Inkfree sign-in page.
2. Click Sign in with enterprise single sign-on, enter a work email on one of your connector's domains, and click Continue to your organization's single sign-on.
3. Sign in on your Shibboleth login page.
4. Confirm you land in Inkfree, signed in as that user.

You can also start a test from the connector's ⋮ menu by selecting Test SSO.

If you turned on Automatically onboard new SSO users, also test with someone who doesn't have an Inkfree account yet, and confirm their account is created the first time they sign in.

Done when: a test user signs in from start to finish.

Step 10: Enforce SSO for Your Domain (Optional)

Who: Inkfree admin

Once testing succeeds, open the connector's ⋮ menu, select Edit, and turn on Enforce SSO to block password sign-in for your domains. Choose a Password-fallback user, the one administrator who can still sign in with a password if your IdP is ever unavailable, then click Save Changes.

Tip: The password-fallback user can bypass SSO, so protect that account with two-factor authentication.

Troubleshooting Shibboleth Sign-In

Remove the Shibboleth Integration

1. Delete the connector in Inkfree from its ⋮ menu by selecting Delete.
2. Remove the Inkfree MetadataProvider, the relying-party override, and the attribute filter policy from your IdP, then reload it.

Note: Deleting the connector turns off SSO for its domains immediately. Users who never set an Inkfree password will need to reset it before they can sign in again.

Need Help With Shibboleth SSO?

If you get stuck, contact the support team or email support@inkfree.app with your connector name, your Shibboleth IdP version, and the approximate time of a failed sign-in. Include the matching lines from idp-process.log if you can, but never send private keys, client secrets, or passwords.