SSO Setup Guide

Complete guide to configuring Single Sign-On (SSO) with SAML 2.0 and OpenID Connect (OIDC) for your organization.

Overview
Prerequisites
SAML 2.0 Configuration
OpenID Connect (OIDC) Configuration
User Provisioning
Testing SSO Configuration
Troubleshooting
Popular Identity Providers

Overview

Single Sign-On (SSO) allows your users to access PlanningForge using their existing corporate credentials, eliminating the need for separate passwords and improving security. PlanningForge supports both SAML 2.0 and OpenID Connect (OIDC) protocols.

SAML 2.0

Enterprise-grade authentication standard
Works with Active Directory, Okta, OneLogin
XML-based configuration
Supports encrypted assertions

OpenID Connect (OIDC)

Modern OAuth 2.0-based standard
Works with Google, Microsoft, Auth0
JSON-based configuration
Simpler setup and debugging

Enterprise Feature

SSO configuration is available on Professional and Enterprise plans. Contact our sales team if you need to upgrade your plan.

Screenshot: SSO configuration overview in organization settings

Prerequisites

Before You Begin

Organization Owner or Administrator access to PlanningForge
Administrative access to your identity provider (IdP)
Professional or Enterprise PlanningForge subscription
Domain verification completed in organization settings

Information You'll Need

For SAML Configuration:

Identity Provider Entity ID
SSO URL (Single Sign-On URL)
SLO URL (Single Logout URL) - optional
X.509 Certificate from your IdP
Attribute mappings for email, name, etc.

For OIDC Configuration:

Issuer URL
Client ID
Client Secret
Scopes to request
Claim mappings for user attributes

Important Note

Always test SSO configuration in a staging environment first. Have a backup administrator account that doesn't rely on SSO in case of configuration issues.

SAML 2.0 Configuration

Step 1: Configure PlanningForge as Service Provider

PlanningForge SAML Settings

Entity ID / Audience URI:

https://your-org.planningforge.com/saml/metadata

Assertion Consumer Service URL:

https://your-org.planningforge.com/saml/acs

Single Logout URL:

https://your-org.planningforge.com/saml/sls

Replace "your-org" with your actual organization subdomain.

Screenshot: SAML configuration form in PlanningForge

Step 2: Configure Your Identity Provider

Log into your identity provider admin console
Create a new SAML application for PlanningForge
Use the PlanningForge URLs from Step 1 above
Configure the following attribute mappings:

SAML Attribute	IdP Field	Required
email	User's email address	Required
firstName	User's first name	Optional
lastName	User's last name	Optional
groups	User's group memberships	Optional

Step 3: Enter IdP Details in PlanningForge

Navigate to Organization Settings → Authentication → SAML
Fill in the following fields from your IdP:

Identity Provider Entity ID

Usually looks like: https://app.onelogin.com/saml/metadata/123456

Single Sign-On URL

The URL where users will be redirected to authenticate

X.509 Certificate

Copy and paste the full certificate including BEGIN/END lines

Configure attribute mappings to match your IdP settings
Save the configuration
Test the SSO flow before enabling for all users

Screenshot: Completed SAML configuration form

OpenID Connect (OIDC) Configuration

Step 1: Register PlanningForge with Your OIDC Provider

Application Registration Details

Application Type:

Web Application

Redirect URI:

https://your-org.planningforge.com/auth/oidc/callback

Post Logout Redirect URI:

https://your-org.planningforge.com/logout

Required Scopes:

openid profile email

Screenshot: OIDC provider application registration

Step 2: Configure OIDC in PlanningForge

Go to Organization Settings → Authentication → OIDC
Enable OIDC authentication
Fill in the configuration details:

Provider Name

Friendly name shown to users (e.g., "Company SSO")

Issuer URL

Your OIDC provider's issuer URL (e.g., https://login.microsoftonline.com/tenant-id/v2.0)

Client ID

The application ID from your OIDC provider

Client Secret

The client secret from your OIDC provider

Configure claim mappings (optional)
Save and test the configuration

Step 3: Claim Mappings

Configure how user attributes from your OIDC provider map to PlanningForge user fields:

PlanningForge Field	Default Claim	Alternative Claims
email	email	preferred_username, upn
first_name	given_name	first_name, fname
last_name	family_name	last_name, lname, surname
groups	groups	roles, memberOf

Screenshot: OIDC configuration form with claim mappings

User Provisioning

Configure how users are automatically created and managed when they authenticate via SSO.

Just-in-Time (JIT) Provisioning

Users are automatically created when they first sign in via SSO
User attributes (name, email) are populated from SSO claims
Users are assigned default organization role (typically "Member")
Can be disabled to require manual user creation

Group-Based Role Assignment

Map SAML/OIDC groups to PlanningForge roles
Automatically assign users to teams based on group membership
Set up rules for Administrator and Owner roles
Users can belong to multiple groups and teams

Example Group Mappings:

planning-admins → Organization Administrator
dev-team → Development Team Member
product-team → Product Team Member

User Deprovisioning

Configure what happens when users are removed from IdP
Options: Disable account, remove from teams, or delete account
Preserve session data and planning history
Send notifications to administrators

Screenshot: User provisioning configuration options

Testing SSO Configuration

Testing Best Practices

Always test SSO configuration with a test user before enabling it for your entire organization. Keep a backup admin account that doesn't rely on SSO.

Testing Steps

Configuration Test
- Use the "Test Configuration" button in SSO settings
- Verify connection to identity provider
- Check certificate validity and expiration
User Authentication Test
- Create a test user in your identity provider
- Attempt to log in via SSO with test credentials
- Verify user attributes are correctly mapped
Group Assignment Test
- Add test user to different groups in IdP
- Verify correct role and team assignments in PlanningForge
- Test removal from groups and automatic deprovisioning
Session Management Test
- Test single logout functionality
- Verify session timeout behavior
- Check that user can access appropriate resources

Rollout Strategy

Pilot Group: Start with a small group of technical users
Department Rollout: Gradually enable for each department
Full Organization: Enable for all users after successful testing
Enforce SSO: Optionally disable password authentication for security

Tip: Use the "Mixed Mode" setting to allow both SSO and password authentication during the transition period.

Screenshot: SSO testing interface and results

Troubleshooting

Common SAML Issues

Certificate Errors

Verify certificate includes BEGIN/END CERTIFICATE lines
Check certificate hasn't expired
Ensure no extra spaces or characters in certificate
Verify certificate matches the one in IdP

Authentication Failures

Check Entity ID matches exactly (case-sensitive)
Verify ACS URL is configured correctly in IdP
Ensure user has permission to access the application
Check attribute mappings are correct

User Creation Issues

Verify email attribute is being sent in assertion
Check if JIT provisioning is enabled
Ensure user's email domain is allowed
Verify organization has available user licenses

Common OIDC Issues

Discovery Failures

Verify issuer URL is accessible and returns valid metadata
Check if issuer URL includes .well-known/openid_configuration
Ensure firewall allows outbound HTTPS to issuer
Verify issuer URL doesn't have trailing slash

Token Exchange Errors

Verify client ID and secret are correct
Check redirect URI matches exactly in provider
Ensure required scopes are configured
Verify client authentication method is correct

Claim Mapping Issues

Check which claims are actually being returned
Verify claim names match exactly (case-sensitive)
Ensure required scopes request necessary claims
Check if claims need custom mapping in provider

Debugging Tools

SSO Debug Mode: Enable detailed logging in organization settings
Browser Developer Tools: Check network requests and responses
SAML Tracer: Browser extension for viewing SAML messages
Online SAML Tools: Decode and validate SAML assertions
IdP Logs: Check your identity provider's authentication logs

SSO Access Issues

If SSO is broken and you can't access PlanningForge, contact your organization owner or support team for assistance. Ensure you always have a backup administrator account that doesn't rely on SSO.

Popular Identity Providers

Microsoft Azure AD / Entra ID

SAML: Use Enterprise Applications gallery
OIDC: Register as Web Application
Issuer: https://login.microsoftonline.com/{tenant-id}/v2.0
Groups: Include group claims in token

Okta

SAML: Create SAML 2.0 Web App
OIDC: Create Web Application
Attribute Statements: Map user attributes
Groups: Configure group attribute filter

Google Workspace

SAML: Add custom SAML app
OIDC: Use Google Cloud Console
Domain: Configure for your workspace domain
Attributes: Basic profile and email

OneLogin

SAML: Use SAML Test Connector
OIDC: Create OpenId Connect app
Parameters: Map user parameters
Roles: Configure role mappings

Auth0

SAML: Create SAML2 Web App
OIDC: Regular Web Application
Rules: Add custom claims via rules
Connections: Connect to enterprise directory

Active Directory Federation Services (ADFS)

SAML: Add Relying Party Trust
Claims: Configure claim issuance policy
Endpoints: Enable SAML 2.0 endpoints
Groups: Send group membership as claims