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

Multi-Tenant Architecture

Each university subdomain has its own SAML configuration, ensuring complete isolation and security.

Flexible Attribute Mapping

Configurable mapping between SAML attributes and user fields for seamless integration.

Automatic User Provisioning

Users are automatically created and updated from SAML attributes with configurable rules.

OAuth Coexistence

SAML works alongside existing Google OAuth authentication for maximum flexibility.

​
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

​
Support

Documentation

Contact

For urgent SAML integration issues, contact our support team with your university name and error details.