Single Sign-On (SSO)

NodeLoom supports SAML 2.0 and OpenID Connect for enterprise single sign-on. SSO lets your team authenticate through your existing identity provider, centralizing access control and simplifying user management.

Overview

Single sign-on allows your team members to log in to NodeLoom using their existing corporate credentials. Instead of managing separate passwords for NodeLoom, users authenticate through your identity provider (IdP) such as Okta, Azure AD, or Google Workspace.

NodeLoom supports two industry-standard SSO protocols. Both implementations include cryptographic signature verification, assertion replay protection, audience validation, and automatic key rotation handling to ensure authentication integrity.

Prerequisites

Before configuring SSO, ensure the following requirements are met:

SAML 2.0 Setup

Follow these steps to configure SAML 2.0 SSO between NodeLoom and your identity provider.

{
  "entityId": "https://idp.example.com/saml/metadata",
  "ssoUrl": "https://idp.example.com/saml/sso",
  "certificate": "-----BEGIN CERTIFICATE-----\nMIIC...base64...\n-----END CERTIFICATE-----",
  "signRequests": true,
  "forceAuthn": false
}

OpenID Connect Setup

Follow these steps to configure OpenID Connect SSO between NodeLoom and your identity provider.

https://your-domain.com/api/sso/oidc/{teamId}/callback

{
  "issuerUrl": "https://idp.example.com",
  "clientId": "0oa1b2c3d4e5f6g7h8i9",
  "clientSecret": "your-client-secret",
  "scopes": ["openid", "profile", "email"]
}

Domain Verification

Before enforcing SSO, you must verify ownership of the email domain(s) associated with your team. Domain verification prevents unauthorized teams from claiming your domain and ensures that enforcement only applies to legitimate accounts.

NodeLoom supports three verification methods:

DNS TXT Record

Add a TXT record to your domain's DNS zone. This is the recommended method for most organizations.

Record Type: TXT
Host: @
Value: nodeloom-verification={token}

DNS CNAME Record

Add a CNAME record if your DNS provider does not support TXT records on the root domain.

Record Type: CNAME
Host: {token}
Value: nodeloom-verify.com

HTML Meta Tag

If you cannot modify DNS records, add a meta tag to the homepage of your domain.

<meta name="nodeloom-verification" content="{token}" />

Enforcing SSO

Enforcing SSO means that all team members with an email matching a verified domain must authenticate through the identity provider. Password-based login, magic links, and social logins are blocked for those users.

To enforce SSO, complete the following steps in order:

User Provisioning

When a user authenticates through SSO for the first time, NodeLoom automatically provisions a new account for them. This eliminates the need for manual invitations or account creation.

Existing users who already have NodeLoom accounts are linked to the SSO identity automatically when they first log in through SSO, provided their email address matches. Their existing role and settings are preserved.

Session Management

SSO sessions in NodeLoom are managed separately from IdP sessions. When a user authenticates through SSO, NodeLoom creates a local session that controls access to the application.

{
  "sessionDurationHours": 8,
  "singleLogoutEnabled": true,
  "idleTimeoutMinutes": 30,
  "maxConcurrentSessions": 5
}

Attribute Mapping

NodeLoom maps identity provider attributes to user profile fields. The following table shows the default mappings for both SAML and OIDC protocols.

You can override the default mappings with custom attribute names in Settings → SSO → Attribute Mapping. This is useful when your IdP uses non-standard attribute names.

Common IdP Attribute Names

API Endpoints

The following endpoints are available for managing SSO programmatically. Admin-authenticated endpoints require the Admin role. Public endpoints are used during the SSO authentication flow.

Admin Endpoints

Public Endpoints

These endpoints are used during the SSO authentication flow and do not require authentication.