Single sign-on

Unifuse signs users in only through the institution’s identity provider. This page covers connecting that provider. Any provider that speaks OpenID Connect (OIDC) or SAML 2.0 works, including Google Workspace, Microsoft Entra ID, Okta and Shibboleth.

Before you start

• You need the manage institution permission (Admin by default).
• In your identity provider, you need to be able to register an application and read its details.
• Open Administration → Single Sign-On.

What to register in your identity provider

Register Unifuse as an application using your institution’s Unifuse address (the address your users sign in at) as the base. Values below are relative to that address.

OIDC

• Redirect (callback) URI: /api/auth/sso/oidc/callback
• Grant type: authorization code. Unifuse asks for the standard profile and email scopes and requires a verified email address.

SAML

• Service-provider metadata: /api/auth/sso/saml/metadata. Most providers can import this directly.
• Assertion consumer service (callback) URL: /api/auth/sso/saml/callback
• Release at least an email address and a display name. Unifuse reads the common attribute names and their OIDs (mail, displayName or cn, givenName and sn, ou or department), so a standard attribute release usually needs no mapping.

Add a provider

1. Choose the Protocol: OIDC or SAML.
2. For OIDC, enter the Client ID, Client Secret and the Discovery URL (the provider’s .well-known/openid-configuration address).
3. For SAML, enter the IdP Entity ID, IdP SSO URL and the IdP X.509 certificate in PEM form.
4. Optionally set a Role source attribute (for example eduPersonAffiliation) and a Role map JSON such as {"faculty": "Advisor", "staff": "Viewer"}. See Mapping roles.
5. Select Add provider.

The list below the form shows each provider’s protocol, whether it is active, its discovery URL or entity ID, and its role map. Remove deletes a provider.

Caution

Sign-in uses the first active provider. Keep one provider active per institution. To change providers, add the new one, test it, then remove the old one.

Mapping roles

If a role source attribute and role map are set, a user’s role is taken from the map the first time they sign in. Values that are not in the map, or users without the attribute, get the institution’s default role.

The mapping only applies when the user has no role yet. Roles that administrators set by hand in Users are never overwritten by a later sign-in.

Testing

Sign in from a private browser window with an account at your institution. If sign-in fails, the reason is recorded in the audit log as a Login Failed event, and the sign-in page shows a message explained in Signing in.

Related

• Sign-in policy for allowed email domains
• SCIM provisioning to create and deactivate users from the identity provider