Sign in Create account
Documentation

Single sign-on with your institution

Feature guides

SAML for universities and teams that run their own identity provider: what to give your IdP, what it must send back, testing the connection, and rotating certificates.

admin

A university that runs Shibboleth, Entra ID, Okta or any other SAML 2.0
identity provider can let its members sign in there and come straight back.
Nobody keeps a second password, leavers lose access the day the institution
removes them, and the institution’s own sign-in rules apply, including its
second factor.

Set it up from your organization page, under Single sign-on. You need to be
an administrator of the organization, and the organization must be a
department, team or university rather than a personal one.

Give your identity provider

The panel lists four values. Your IdP administrator needs the first three.

Value What it is
Metadata https://www.dfrds.com/sso/<slug>/metadata.xml. Most IdPs import this and fill in the rest themselves.
Entity ID The same URL. The assertion’s audience must name it.
Assertion consumer (ACS) https://www.dfrds.com/sso/<slug>/callback, HTTP-POST binding.
Member entry https://www.dfrds.com/sso/<slug>. Put it on your intranet; it starts a sign-in.

<slug> is your organization’s handle, shown on the panel. It does not
change when the organization is renamed, so the IdP configuration survives
a rename.

What the assertion must carry

The subject’s email address, and ideally a first and last name:

We read Default attribute name Used for
Email email The account. Membership is keyed on it, and an existing account with this address is linked rather than duplicated.
First name first_name The profile, on first sign-in only.
Last name last_name The profile, on first sign-in only.

If your IdP releases attributes under other names (Shibboleth uses OIDs such
as urn:oid:0.9.2342.19200300.100.1.3 for mail), type those names in the
panel. A NameID in email format serves as the address when no email
attribute is released; an assertion with neither is refused, and the person
sees a message naming the attribute mapping.

The response or the assertion must be signed with the certificate you paste
into the panel. Unsigned documents, assertions restricted to a different
audience, assertions whose validity window has passed (30 seconds of clock
drift is tolerated), and responses that do not answer a request this browser
started are all refused. Sign-in is SP-initiated only: a response that your
IdP sends unprompted is refused for that last reason.

Fill in the panel

  1. IdP entity ID and IdP sign-in URL: from your IdP’s metadata. The
    sign-in URL is the HTTP-Redirect single sign-on endpoint and must be
    https.
  2. IdP signing certificate: the PEM block, -----BEGIN CERTIFICATE-----
    to -----END CERTIFICATE-----. The panel shows its expiry once saved.
  3. NameID format: email address for most institutions. Persistent
    identifiers work too, as long as an email attribute is released.
  4. Attributes: the names above, or your own.
  5. Enabled: tick it. Nothing signs anyone in until the connection is
    also verified.

Save, then choose Test connection.

Test connection

The test is a real round trip. We check what can be checked without
leaving (the certificate parses and has not expired, the URLs make sense),
then send your browser to the IdP with a request marked as a test. When the
IdP answers and the assertion verifies, the configuration is marked
verified, the panel shows the date, and the audit log records which address
the IdP signed in. Nobody is signed in by the test, whoever it named.

Until a test has passed, the member entry and the Sign in with your
institution field on the sign-in page refuse with a message saying the
organization has not finished setting up. Any later change to the entity
ID, the sign-in URL, the certificates or the NameID format clears the
verification, so run the test again after such a change. Changing the
attribute names does not.

Signing in

Members open the member entry, or type their institution’s email domain
into Sign in with your institution on the sign-in page, which finds the
organization by the verified email domain
and sends them on.

On the first sign-in an account is created with the asserted address and
name, confirmed (the IdP vouched for the address), added to the organization
as a member, and asked to accept the terms of service. If an account with
that address already exists, it is linked to the identity and added to the
organization instead. If every seat is in use, nothing is created: the
person is told, the organization’s administrators are emailed, and the
sign-in is recorded as failed in the audit log until a seat is free.

Later sign-ins match the identity your IdP asserts, so a change of address
at the IdP does not create a second account. Successful sign-ins appear in
the audit log
as Signed in, via saml.

Rotating the certificate

Paste the incoming certificate into Next certificate before your IdP
switches to it. Both certificates verify signatures from then on, so the IdP
can switch on its own schedule. Once it has, move the new certificate into
the main field and clear the next one. Each of those saves clears the
verification, so run Test connection after each; the test takes a minute
and proves the certificate that is now in use.

Related guides