# Single sign-on

> Connect your institution's identity provider to Unifuse over OIDC or SAML, map identity-provider attributes to Unifuse roles, and what to configure on the identity-provider side.

Source: https://docs.unifuse.ai/administration/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](#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](/administration/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](/administration/audit-log/) as a *Login Failed*
event, and the sign-in page shows a message explained in
[Signing in](/getting-started/signing-in/#sign-in-messages).

## Related

- [Sign-in policy](/administration/sign-in-policy/) for allowed email domains
- [SCIM provisioning](/administration/scim-provisioning/) to create and deactivate users from the identity provider