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, use these Propper SP values:

Field	Value
SP Entity ID	urn:propper:sp:auth
ACS URL	https://auth.propper.ai/saml/acs
SLO URL	https://auth.propper.ai/saml/slo
NameID Format	urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

Download SP Metadata

You can download Propper's SP metadata XML from your SSO settings page, or directly from:

https://auth.propper.ai/saml/metadata

Many identity providers can auto-configure using this metadata URL.

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 following SP configuration in your IdP:

Basic Settings

Setting	Value
SP Entity ID / Audience	urn:propper:sp:auth
ACS URL / Reply URL	https://auth.propper.ai/saml/acs
Single Logout URL	https://auth.propper.ai/saml/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 without namespaces:

<saml:Attribute Name="email">
  <saml:AttributeValue>user@example.com</saml:AttributeValue>
</saml:Attribute>

info

Propper also accepts standard SAML attribute URIs. See Supported Attribute Formats below.

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 accepts attributes in multiple formats for compatibility:

Email

• email
• emailAddress
• mail
• http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
• urn:oid:0.9.2342.19200300.100.1.3

First Name

• firstName
• first_name
• givenName
• http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
• urn:oid:2.5.4.42

Last Name

• lastName
• last_name
• surname
• sn
• http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
• urn:oid:2.5.4.4

Display Name

• displayName
• display_name
• name
• cn
• http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
• urn:oid:2.5.4.3

Groups

• groups
• memberOf
• http://schemas.microsoft.com/ws/2008/06/identity/claims/groups

SAML Response Requirements

Required Elements

Your IdP's SAML response must include:

1. Valid Signature - Response and/or Assertion must be signed
2. Correct Audience - Must match urn:propper:sp:auth
3. Valid Timestamps - NotBefore and NotOnOrAfter must be current
4. InResponseTo - Must match the original AuthnRequest ID
5. NameID - User's email address

Example SAML Assertion Structure

<saml:Assertion>
  <saml:Issuer>https://your-idp.com</saml:Issuer>
  <saml:Subject>
    <saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">
      user@example.com
    </saml:NameID>
    <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
      <saml:SubjectConfirmationData
        InResponseTo="_abc123"
        Recipient="https://auth.propper.ai/saml/acs"
        NotOnOrAfter="2024-01-01T12:05:00Z"/>
    </saml:SubjectConfirmation>
  </saml:Subject>
  <saml:Conditions NotBefore="2024-01-01T12:00:00Z" NotOnOrAfter="2024-01-01T12:05:00Z">
    <saml:AudienceRestriction>
      <saml:Audience>urn:propper:sp:auth</saml:Audience>
    </saml:AudienceRestriction>
  </saml:Conditions>
  <saml:AttributeStatement>
    <saml:Attribute Name="email">
      <saml:AttributeValue>user@example.com</saml:AttributeValue>
    </saml:Attribute>
    <saml:Attribute Name="firstName">
      <saml:AttributeValue>John</saml:AttributeValue>
    </saml:Attribute>
    <saml:Attribute Name="lastName">
      <saml:AttributeValue>Doe</saml:AttributeValue>
    </saml:Attribute>
  </saml:AttributeStatement>
</saml:Assertion>

Troubleshooting

Error: Invalid Signature

• Verify the certificate in Propper matches your IdP's signing certificate
• Check that the IdP is signing the Response or Assertion (or both)
• Ensure the signature algorithm is SHA-256 or stronger

Error: Audience Mismatch

• The SAML response Audience must exactly match urn:propper:sp:auth
• Check your IdP's SP Entity ID / Audience configuration

Error: Recipient Mismatch

• The SubjectConfirmationData Recipient must be https://auth.propper.ai/saml/acs
• Verify the ACS URL in your IdP configuration

Error: Assertion Expired

• Check that your server's clock is synchronized (NTP)
• Propper allows 60 seconds of clock skew by default
• The NotOnOrAfter timestamp must be in the future

Error: Missing Required Attribute

• Ensure all required attributes (email, firstName, lastName) are mapped
• Verify the attribute names match exactly (case-sensitive)
• Check that the user has values for all required attributes in the IdP

Error: InResponseTo Missing or Invalid

• This usually indicates an IdP-initiated flow when SP-initiated was expected
• Configure your IdP to support SP-initiated SSO
• Or enable IdP-initiated SSO support in Propper (if available)

Users redirected to login page after authentication

• Check browser cookies are enabled
• Verify the user's email domain matches an SSO-configured domain
• Look for errors in the browser console

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
7. Monitor logs - Review authentication logs for anomalies