Custom SAML 2.0 SSO Setup

Configure SAML-based Single Sign-On with any SAML 2.0 compliant identity provider.

This guide covers general SAML 2.0 configuration. For provider-specific guides, see:

• Microsoft Entra ID (Azure AD)
• Google Workspace

Prerequisites

• Admin access to your SAML 2.0 identity provider
• Propper organization admin access
• Your IdP must support SAML 2.0 with HTTP-POST bindings

Propper Service Provider Metadata

When configuring your identity provider, copy the Service Provider values from Settings > Security > SSO in Propper. The authenticated settings page shows the correct Entity ID, ACS URL, optional logout URL, and NameID format for your environment.

Download SP Metadata

You can download Propper's SP metadata XML from your SSO settings page. Many identity providers can auto-configure from that metadata file.

Step 1: Create a SAML Application in Your IdP

In your identity provider's admin console:

1. Create a new SAML 2.0 application
2. Name it "Propper" or your preferred name
3. Configure it as a Service Provider (SP) initiated application

Step 2: Configure SAML Settings

Enter the SP configuration shown in your Propper SSO settings:

Basic Settings

Setting	Value
SP Entity ID / Audience	Copy from Propper
ACS URL / Reply URL	Copy from Propper
Single Logout URL	Copy from Propper if you enable SLO
NameID Format	Email Address
Binding	HTTP-POST

Signature Settings (Recommended)

Setting	Recommended Value
Sign SAML Response	Yes
Sign SAML Assertion	Yes
Signature Algorithm	RSA-SHA256
Digest Algorithm	SHA256

warning

SHA-1 is deprecated and not recommended. Always use SHA-256 or stronger.

Step 3: Configure Attribute Statements

Map your IdP user attributes to the following Propper attributes:

Required Attributes

IdP Attribute	Propper Attribute	Description
User's email	email	Primary identifier
User's first name	firstName	Display name
User's last name	lastName	Display name

Optional Attributes

IdP Attribute	Propper Attribute	Description
User's groups	groups	For role mapping
Display name	displayName	Full name

Attribute Format

Attributes should be sent as simple string values. Use the attribute names configured in Propper if your organization changes the defaults.

Step 4: Export IdP Metadata

From your identity provider, export or copy:

1. IdP Entity ID - The unique identifier for your IdP
2. SSO URL - The URL where Propper sends authentication requests
3. X.509 Certificate - The public certificate for signature verification

Most IdPs provide a metadata URL or downloadable metadata XML file containing all these values.

Step 5: Configure Propper

1. Log in to Propper as an organization admin
2. Go to Settings > Security > SSO
3. Click Configure SSO or Edit Configuration
4. Select Custom SAML 2.0

Option A: Import via Metadata URL

If your IdP provides a metadata URL:

1. Enter the Metadata URL
2. Click Import
3. Propper will automatically populate the IdP Entity ID, SSO URL, and Certificate

Option B: Import via Metadata XML

If your IdP provides a downloadable metadata XML file:

1. Click Upload Metadata
2. Select your metadata XML file
3. Propper will automatically populate the configuration

Option C: Manual Configuration

Enter the values manually:

Propper Field	Description
Display Name	Friendly name for this SSO connection
IdP Entity ID	Your IdP's Entity ID / Issuer
SSO URL	Your IdP's SAML login endpoint
SLO URL	Your IdP's logout endpoint (optional)
Certificate	Your IdP's X.509 signing certificate (PEM format)

Certificate Format

The certificate should be in PEM format:

-----BEGIN CERTIFICATE-----
MIIDXTCCAkWgAwIBAgIJAJC1HiIAZAiUMA0Gcz...
...base64 encoded certificate data...
-----END CERTIFICATE-----

5. Click Save Configuration

Step 6: Test the Connection

1. In Propper SSO settings, click Test Connection
2. A new window will open with your IdP's login page
3. Sign in with a test user
4. If successful, you'll be redirected back to Propper

tip

Test in an incognito/private browser window to simulate a real user login.

Advanced Configuration

Just-In-Time (JIT) Provisioning

Enable automatic user creation on first SSO login:

1. Enable Just-In-Time Provisioning
2. Set Default Role - The role assigned to new users
3. Optionally set Allowed Domains - Restrict which email domains can be provisioned

Group-Based Role Mapping

Map IdP groups to Propper roles:

1. Enable JIT Provisioning
2. Configure Group Attribute - The SAML attribute containing group names (e.g., groups)
3. Add Role Mappings:
   • IdP Group Name → Propper Role

Example mappings:

IdP Group	Propper Role
propper-admins	Admin
propper-users	Member
propper-viewers	Viewer

4. Enable Sync Roles on Login to update roles on each login based on current group membership

SSO Enforcement

Require SSO for all users with a verified domain:

1. Verify your email domain in Propper
2. Enable SSO Enforcement for the domain
3. Add Admin Bypass Emails - Admins who can still use password login

warning

Always configure bypass emails before enabling enforcement to prevent admin lockout.

Signature Requirements

Configure security settings in Propper:

Setting	Description	Default
Require Signed Assertions	IdP must sign the SAML assertion	Enabled
Require Signed Response	IdP must sign the entire SAML response	Disabled
Sign Authentication Requests	Propper signs requests to IdP	Enabled

Supported Attribute Formats

Propper supports configurable SAML attribute mappings. Use the default names in this guide for a standard setup, or update the mapping in Propper if your IdP sends different claim names.

SAML Response Requirements

Your IdP's SAML response must be signed, current, and issued for the Service Provider values shown in Propper. Use the in-product test connection flow to verify the configuration before enabling enforcement.

Troubleshooting

If setup fails, compare the IdP configuration against the current values shown in Propper SSO settings, then run Test Connection again. Common causes are stale certificates, changed metadata, missing user attributes, disabled IdP app assignments, or an unverified email domain.

Security Recommendations

1. Use SHA-256 or stronger - Avoid SHA-1 for signatures
2. Enable assertion signing - Always require signed assertions
3. Rotate certificates - Update certificates before expiration
4. Restrict by domain - Use allowed domains for JIT provisioning
5. Configure bypass list - Always have admin fallback access
6. Test thoroughly - Verify SSO works before enabling enforcement