SSO / SAML

Full Fabric supports enterprise single sign-on (SSO) via SAML 2.0. When enabled, users authenticate through their organisation's identity provider (IdP) — such as OneLogin, Okta, or Microsoft Entra ID — instead of entering a Full Fabric password. This centralises credential management and integrates Full Fabric into the institution's existing identity infrastructure.

How SAML Authentication Works

Full Fabric uses SP-initiated SAML only — the login flow always starts from the Full Fabric login page. IdP-initiated flows (where the user starts from the identity provider's portal) are not supported.

sequenceDiagram
    participant User
    participant FF as Full Fabric (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 Full Fabric login page and clicks "Institutional Login" (or is redirected automatically if SAML is the only auth method).
Full Fabric 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 Full Fabric's callback URL.
Full Fabric 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, Full Fabric 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`	Full Fabric's SP certificate (public key)
`auth.saml.sp_private_key`	Full Fabric'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 Full Fabric profile fields. Mappings are configured as source/target pairs:

Source (IdP attribute)	Target (Full Fabric 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

Full Fabric 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 Full Fabric will decrypt them using the private key.

Signature Details

Full Fabric signs SAML AuthnRequests and Logout Responses using RSA-SHA1 with a SHA1 digest. The SP metadata is also signed. Both the sp_cert and sp_private_key settings are required for request signing.

Schema Permissions

API Tokens