Single Sign-On (SSO)

PrivacyForge supports enterprise SSO through SAML 2.0, OAuth 2.0, and OpenID Connect. This guide covers setup, configuration, and troubleshooting.

SSO is available on the Enterprise plan only.

Supported Protocols

SAML 2.0

XML-based protocol widely used in enterprise environments. Works with Okta, Azure AD, OneLogin, PingFederate, and ADFS.

OAuth 2.0

Token-based authorization framework. Supports PKCE for enhanced security. Works with custom OAuth providers.

OpenID Connect

Identity layer built on OAuth 2.0. Auto-discovers endpoints from issuer URL. Works with Google Workspace, Azure AD, Keycloak.

Setting Up SSO

Navigate to Settings → SSO in your PrivacyForge dashboard (Enterprise plan required).
Click "Add Provider" and select your protocol (SAML 2.0, OAuth 2.0, or OpenID Connect).
Configure your Identity Provider (IdP) using the SP metadata provided by PrivacyForge.
Enter the IdP details in the PrivacyForge configuration form.
Test the connection using the built-in test button.
Activate the provider and optionally set it as default.

SAML 2.0 Configuration

PrivacyForge SP Details

Provide these to your Identity Provider:

ACS URL: https://your-domain.com/api/auth/saml/acs/{orgId}

SP Metadata: https://your-domain.com/api/auth/saml/metadata/{orgId}

SP Entity ID: https://your-domain.com

Required from your IdP

Entity ID -- The IdP's unique identifier
SSO URL -- The IdP's login endpoint
X.509 Certificate -- Used to verify SAML assertions
SLO URL (optional) -- For single logout support

OAuth 2.0 / OIDC Configuration

Required from your IdP

Client ID -- Application identifier from your IdP
Client Secret -- Application secret from your IdP
Authorization URL -- Where users are redirected to authenticate
Token URL -- Endpoint to exchange authorization codes for tokens
UserInfo URL -- Endpoint to fetch user profile data
Scopes -- Typically openid email profile

For OpenID Connect, you only need the Issuer URL -- PrivacyForge will auto-discover all endpoints via the .well-known/openid-configuration document.

Redirect URI: https://your-domain.com/api/auth/oauth/callback/{orgId}

Attribute Mapping

Map your IdP's user attributes to PrivacyForge fields. Default mappings:

PrivacyForge Field	Common IdP Attribute
Email	email, mail, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
First Name	firstName, givenName, given_name
Last Name	lastName, surname, family_name
Role	role, groups, memberOf

IdP-Specific Guides

Okta

In Okta Admin, go to Applications → Create App Integration.
Select SAML 2.0 and click Next.
Set the Single Sign-On URL to your ACS URL.
Set the Audience URI to your SP Entity ID.
Configure attribute statements for email, firstName, lastName.
Complete the wizard and download the IdP metadata or certificate.
Enter the IdP details in PrivacyForge Settings → SSO.

Azure Active Directory (Entra ID)

In Azure Portal, go to Enterprise Applications → New Application.
Select Create your own application (Non-gallery).
Go to Single sign-on → SAML.
Set Entity ID and Reply URL to your SP values.
Download the Federation Metadata XML or certificate.
Copy the Login URL and Azure AD Identifier.
Enter these in PrivacyForge Settings → SSO.

Google Workspace

In Google Admin Console, go to Apps → Web and mobile apps.
Click Add App → Add custom SAML app.
Download the IdP metadata (or copy SSO URL and certificate).
Set ACS URL and Entity ID to your SP values.
Configure attribute mapping for email and name.
Turn on the app for your organizational unit.
Enter the IdP details in PrivacyForge Settings → SSO.

Troubleshooting

SAML assertion validation failed

Check that your IdP's certificate matches the one configured in PrivacyForge. Certificates may need to be renewed periodically.

User not provisioned

PrivacyForge uses Just-In-Time (JIT) provisioning. On first login, a user account is automatically created. Ensure the IdP sends an email attribute.

Clock skew error

SAML assertions are time-sensitive. Ensure your IdP server's clock is synchronized (NTP). PrivacyForge allows a 5-minute clock skew by default.

OAuth callback error

Verify the redirect URI in your IdP matches exactly: https://your-domain.com/api/auth/oauth/callback/{orgId}

SSO provider not found for email domain

Your organization's domain must be configured in PrivacyForge. Contact your administrator to verify the domain setting.

Need help? Contact Support

Back to Sign In