Skip to main content

​
SAML Authentication

Study Compass supports SAML 2.0 authentication for seamless university single sign-on (SSO) integration. This allows students and staff to authenticate using their institutional credentials.
This documentation covers the complete SAML integration process for universities implementing Study Compass authentication.

​
Overview

SAML architecture

Per-tenant SAML, subdomains, and how configuration is isolated per school.

Configuration options

Attribute mapping, IdP metadata, and tunables documented on this page.

Integration guide

Provisioning, callbacks, and rollout steps for university SSO.

Other sign-in methods

SAML coexists with email/password, Google, and Apple; see the authentication overview for how tokens and tenants align.

​
Quick Start

1

Request SAML Information

Contact your university’s IT department to obtain:
  • SAML metadata XML file or metadata URL
  • Identity Provider (IdP) configuration details
  • User attribute mapping information
2

Configure Study Compass

Use our interactive setup script to configure SAML:
3

Test Integration

Validate your configuration and test the authentication flow:
4

Activate & Monitor

Activate the configuration and monitor authentication success rates.

​
Architecture

Multi-Tenant Design

Study Compass uses a multi-tenant architecture where each university subdomain has its own:
  • Database connection - Isolated data storage
  • SAML configuration - University-specific IdP settings
  • User provisioning rules - Custom attribute mapping
  • Security policies - Institution-specific requirements
1

User Initiates Login

User clicks “Sign in with University” button
2

SAML Request

Study Compass generates SAML authentication request
3

IdP Authentication

User authenticates with university IdP
4

SAML Response

IdP sends signed SAML response with user attributes
5

User Creation/Update

Study Compass processes response and creates/updates user
6

JWT Token

User receives JWT token for API access
  • X509 certificate verification for all SAML messages
  • Support for multiple certificates and rotation
  • Certificate chain validation

​
API Reference

​
Authentication Endpoints

​
Configuration Management

​
Configuration Options

​
SAML Settings

​
Attribute Mapping

Configure how SAML attributes map to user fields:

​
User Provisioning

​
Integration Guide

​
Step 1: Gather University Information

Start by collecting the necessary SAML configuration details from your university’s IT department.
Required Information:

SAML Metadata

  • SAML metadata XML file
  • Metadata URL endpoint
  • Entity ID

IdP Configuration

  • SSO URL
  • SLO URL (optional)
  • X509 Certificate

User Attributes

  • Email attribute name
  • Name attribute names
  • Student ID attribute

Technical Details

  • Signature algorithms
  • NameID format
  • Security requirements

​
Step 2: Configure Study Compass

​
Step 3: Test the Integration

1

Validate Configuration

curl -X POST https://berkeley.study-compass.com/auth/saml/test \
  -H "Authorization: Bearer <admin-token>"
2

Check Metadata

curl -X GET https://berkeley.study-compass.com/auth/saml/metadata
3

Test Login Flow

# Get test login URL
curl -X GET https://berkeley.study-compass.com/auth/saml/test-login \
  -H "Authorization: Bearer <admin-token>"

​
Step 4: Activate and Monitor

Always test thoroughly before activating SAML authentication in production.

​
Troubleshooting

​
Common Issues

Error: Invalid X509 certificate formatSolution:
  • Ensure certificate is in PEM format
  • Check for proper BEGIN/END markers
  • Verify certificate is not expired
Error: Invalid URL formatSolution:
  • Ensure all URLs are accessible
  • Check for trailing slashes
  • Verify HTTPS vs HTTP
Error: Required attribute not foundSolution:
  • Verify SAML attribute names
  • Check case sensitivity
  • Ensure IdP sends required attributes

​
Debug Mode

Enable debug logging for detailed troubleshooting:

​
Security Best Practices

Certificate Management

  • Use proper certificates in production
  • Implement certificate rotation
  • Store private keys securely
  • Monitor certificate expiration

URL Security

  • Use HTTPS for all endpoints
  • Validate relay states
  • Implement proper session management
  • Use secure cookie settings

Attribute Security

  • Validate all SAML attributes
  • Sanitize user input
  • Implement proper authorization
  • Log security events

Monitoring

  • Monitor authentication success rates
  • Set up alerts for failures
  • Track configuration changes
  • Audit access logs regularly

Authentication overview

How SAML fits alongside password, Google, and Apple, and how JWTs are issued afterward.

Session management

Refresh sessions and multi-device behavior once users complete SAML login.

Multi-tenant identity & SSO

Global users, TenantMembership, and cookie-domain SSO across subdomains.

Backend best practices

Tenant DB routing, samlRoutes.js context, and middleware adjacent to auth.

API reference

Other HTTP surfaces clients use alongside SAML redirects and callbacks.

Testing

How to regression-test auth and tenant-specific SAML assumptions in CI.

​
Support

Escalation: Use internal Study Compass engineering channels for tenant SAML cutovers and IdP coordination. Include tenant subdomain, IdP metadata version, approximate failure time, and RelayState / error codes from the browser or IdP logs.
Production SAML changes affect live campus login. Route urgent incidents through the same on-call / engineering escalation used for Meridian authentication outages.