SSO / SAML

FullFabric supports enterprise single sign-on (SSO) via SAML 2.0. When enabled, users authenticate through their organization's identity provider (IdP) — such as OneLogin, Okta, or Azure AD — instead of entering a FullFabric password. This centralizes credential management and integrates FullFabric into the institution's existing identity infrastructure.

How SAML Authentication Works

FullFabric uses SP-initiated SAML, meaning the login flow starts from the FullFabric login page:

sequenceDiagram
    participant User
    participant FF as FullFabric (SP)
    participant IdP as Identity Provider

    User->>FF: Visit login page
    FF->>IdP: SAML AuthnRequest (redirect)
    IdP->>User: IdP login page
    User->>IdP: Enter credentials
    IdP->>FF: SAML Response (POST to /auth/saml/callback)
    FF->>FF: Validate response & extract attributes
    FF->>FF: Find or create profile
    FF->>User: Session created, redirect to platform

User visits the FullFabric login page and clicks "Institutional Login" (or is redirected automatically if SAML is the only auth method).
FullFabric sends a signed SAML Authentication Request to the IdP.
The user authenticates at the IdP (entering their institutional credentials).
The IdP sends a signed SAML Response back to FullFabric's callback URL.
FullFabric validates the response, extracts user attributes, and creates a session.

SAML-Only Mode

When SAML is the only enabled authentication method (no social login or native password), the login page skips the email entry step and redirects directly to the IdP. Logout also triggers a SAML Single Logout (SLO) request to the IdP.

Profile Matching

When a SAML response is received, FullFabric looks up the user by a configurable attribute (typically email). If a matching profile is found, a session is created. If no match is found and the IdP provides the required attributes, a new profile is automatically created and activated.

Institution Configuration

SAML is configured per institution through the settings interface. The following settings are required:

Setting	Description
`auth.saml.enable`	Enable or disable SAML authentication
`auth.saml.idp_sso_target_url`	IdP login URL (SAML 2.0 Endpoint)
`auth.saml.idp_slo_target_url`	IdP logout URL (Single Logout endpoint)
`auth.saml.idp_entity_id`	IdP entity identifier (Issuer URL)
`auth.saml.idp_cert`	IdP's X.509 certificate (for validating SAML responses)
`auth.saml.sp_cert`	FullFabric's SP certificate (public key)
`auth.saml.sp_private_key`	FullFabric's SP private key (for signing requests)
`auth.saml.user_key`	Profile field for user lookup (e.g., `"email"`)
`auth.saml.mappings`	Attribute mappings from IdP to profile fields

Optional Settings

Setting	Description
`auth.saml.skip_recipient_check`	Bypass SAML recipient validation (useful for testing)
`auth.saml.debugging`	Enable SAML response logging for troubleshooting

Attribute Mapping

SAML attribute mappings define how IdP attributes translate to FullFabric profile fields. Mappings are configured as source/target pairs:

Source (IdP attribute)	Target (FullFabric field)
`email`	`email`
`first_name`	`first_name`
`last_name`	`last_name`

Additional custom attributes can be mapped depending on the IdP configuration.

Certificate Management

Generating SP Certificates

FullFabric requires an SP certificate pair (public certificate + private key) for signing SAML requests and decrypting encrypted assertions.

To generate a certificate pair:

ssh-keygen -t rsa -b 4096
openssl req -out certificate.csr -key sp -new
openssl req -x509 -sha256 -days 3650 -key sp -in certificate.csr -out certificate.pem

The generated certificate (certificate.pem) goes into the auth.saml.sp_cert setting, and the private key into auth.saml.sp_private_key.

Encrypted Assertions

If the IdP supports encrypted assertions (recommended for production), paste the SP public certificate into the IdP's configuration. The IdP will encrypt assertions using this certificate, and FullFabric will decrypt them using the private key.

Schema Permissions

API Tokens