@ubcshib/passport-ubcshib

A Passport.js strategy for integrating UBC's Shibboleth SAML 2.0 Identity Provider with Node.js applications. An extension of the passport-saml library, with thanks to University of Washington for publishing theirs from which we could work: https://www.passportjs.org/packages/passport-uwshib/

Features

• SAML 2.0 Support: Full SAML 2.0 authentication with UBC's Shibboleth IdP
• Multi-Environment: Automatic configuration for LOCAL (SimpleSAMLphp), STAGING, and PRODUCTION environments
• Local Development: Test with docker-simple-saml before deploying to staging/production
• Flexible Attributes: Per-application attribute selection with OID-to-friendly-name mapping
• Secure: Supports SAML request signing and response validation
• Single Logout (SLO): Optional support for single logout at the IdP
• Certificate Management: Automatic fetching of IdP certificates from metadata
• Environment-Based Configuration: Support for both environment variables and runtime configuration

Installation

npm install passport-ubcshib passport

Quick Start

1. Configure Passport

const passport = require('passport');
const { Strategy } = require('passport-ubcshib');
const fs = require('fs');

passport.use(
	new Strategy(
		{
			// Service Provider Identity (usually your app's URL)
			issuer: 'https://myapp.example.com/shibboleth',

			// Callback URL after authentication
			callbackUrl: 'https://myapp.example.com/auth/ubcshib/callback',

			// Path to your application's private key for signing SAML requests
			privateKeyPath: process.env.SAML_PRIVATE_KEY_PATH,

			// Specify which attributes your app needs
			// See ATTRIBUTES.md for full list of available attributes
			attributeConfig: ['ubcEduCwlPuid', 'mail', 'eduPersonAffiliation'],

			// Optional: Enable single logout
			enableSLO: true,
		},
		// Verify callback: called with user profile after successful authentication
		(profile, done) => {
			// profile.nameID - SAML nameID
			// profile.attributes - Mapped attributes based on attributeConfig

			User.findOrCreate(
				{ ubcId: profile.attributes.ubcEduCwlPuid },
				(err, user) => {
					return done(err, user);
				}
			);
		}
	)
);

// Serialize and deserialize user for session management
passport.serializeUser((user, done) => {
	done(null, user.id);
});

passport.deserializeUser((id, done) => {
	User.findById(id, (err, user) => {
		done(err, user);
	});
});

2. Set Up Routes

const express = require('express');
const passport = require('passport');
const { ensureAuthenticated, logout } = require('passport-ubcshib');

const app = express();

// Login route - redirects to UBC IdP
app.get('/auth/ubcshib', passport.authenticate('ubcshib'));

// Callback route - called by UBC IdP after authentication
app.post(
	'/auth/ubcshib/callback',
	passport.authenticate('ubcshib', { failureRedirect: '/login' }),
	(req, res) => {
		// Successful authentication
		res.redirect('/dashboard');
	}
);

// Protected route
app.get('/dashboard', ensureAuthenticated(), (req, res) => {
	res.send(`Welcome, ${req.user.name}`);
});

// Logout
app.get('/logout', logout('/'));

3. Configure Environment

Create a .env file:

# SAML Configuration
SAML_ENVIRONMENT=STAGING  # or PRODUCTION
SAML_PRIVATE_KEY_PATH=/path/to/your/private.key
SAML_ISSUER=https://myapp.example.com/shibboleth
SAML_CALLBACK_URL=https://myapp.example.com/auth/ubcshib/callback

# Attributes your app needs
# (optional - can also configure in code)

Configuration Options

Required Options

Option	Type	Description
issuer	string	Your Service Provider's entity ID (usually your app's base URL + /shibboleth)
callbackUrl	string	URL where the IdP redirects after authentication (must match registered URL with UBC IAM)

Optional Options

Option	Type	Default	Description
privateKeyPath	string	null	Path to your app's private key for signing SAML requests
attributeConfig	Array	[]	List of attribute names to request from IdP (see ATTRIBUTES.md)
entryPoint	string	Staging or Production SSO endpoint	Identity Provider's SSO endpoint
logoutUrl	string	Staging or Production logout endpoint	Identity Provider's logout endpoint
enableSLO	boolean	true	Enable single logout (SLO) on user logout
validateInResponseTo	boolean	true	Validate response InResponseTo against request ID
acceptedClockSkewMs	number	0	Allowed clock skew in milliseconds between servers
signatureAlgorithm	string	'sha256'	SAML signature algorithm (sha256, sha512, etc.)

Environment Variables

The following environment variables can be used to configure the strategy:

# Environment selection
SAML_ENVIRONMENT=STAGING  # STAGING or PRODUCTION

# For custom IdP configuration
SAML_ENTRY_POINT=https://authentication.ubc.ca/idp/profile/SAML2/Redirect/SSO
SAML_LOGOUT_URL=https://authentication.ubc.ca/idp/profile/Logout
SAML_METADATA_URL=https://authentication.ubc.ca/idp/shibboleth

# Private key location
SAML_PRIVATE_KEY_PATH=/etc/app/saml/private.key

# Service Provider config
SAML_ISSUER=https://myapp.example.com/shibboleth
SAML_CALLBACK_URL=https://myapp.example.com/auth/ubcshib/callback

# Enable/disable features
ENABLE_SLO=true

Environments

Staging

• Entry Point: https://authentication.stg.id.ubc.ca/idp/profile/SAML2/Redirect/SSO
• Logout URL: https://authentication.stg.id.ubc.ca/idp/profile/Logout
• Metadata: https://authentication.stg.id.ubc.ca/idp/shibboleth

Production

• Entry Point: https://authentication.ubc.ca/idp/profile/SAML2/Redirect/SSO
• Logout URL: https://authentication.ubc.ca/idp/profile/Logout
• Metadata: https://authentication.ubc.ca/idp/shibboleth

Set the environment via:

SAML_ENVIRONMENT=PRODUCTION node app.js

Attribute Mapping

The strategy automatically maps SAML OID attribute names to friendly names. See ATTRIBUTES.md for the complete reference.

Common attributes:

• ubcEduCwlPuid - UBC Computing User ID
• mail - Email address
• eduPersonAffiliation - Affiliation (student, faculty, staff, etc.)

Adding New Attributes

Need to add support for a new attribute? See ADDING_ATTRIBUTES.md for a step-by-step guide on how to add new OID mappings to the library.

After successful authentication, mapped attributes are available as:

req.user.attributes = {
	ubcEduCwlPuid: '12345678',
	mail: '[email protected]',
	eduPersonAffiliation: ['student', 'member'],
};

Helper Middleware

ensureAuthenticated(options)

Middleware to protect routes. Redirects unauthenticated users to login.

const { ensureAuthenticated } = require('@ubcshib/passport-ubcshib');

app.get('/protected', ensureAuthenticated(), (req, res) => {
	res.send('Only authenticated users see this');
});

// Custom login URL
app.get(
	'/protected',
	ensureAuthenticated({ loginUrl: '/auth/ubcshib' }),
	(req, res) => {
		res.send('Only authenticated users see this');
	}
);

logout(returnUrl)

Middleware to handle logout. Clears session and optionally redirects to IdP logout if SLO is enabled.

const { logout } = require('@ubcshib/passport-ubcshib');

app.get('/logout', logout('/goodbye'));

conditionalAuth(checkFn)

Middleware to conditionally protect routes based on a function.

const { conditionalAuth } = require('@ubcshib/passport-ubcshib');

app.get(
	'/maybe-protected',
	conditionalAuth((req) => req.query.admin === 'true'),
	(req, res) => {
		res.send('Protected if admin query param is true');
	}
);

Profile Structure

After successful authentication, the user profile will have:

profile = {
	nameID: '[email protected]', // SAML nameID (usually email)
	nameIDFormat: '...', // SAML format identifier
	attributes: {
		// Mapped attributes (from attributeConfig)
		ubcEduCwlPuid: '12345678',
		mail: '[email protected]',
		eduPersonAffiliation: ['student'],
	},
};

Certificate Management

The strategy automatically fetches the IdP's public certificate from the metadata endpoint. No configuration is needed for certificate handling in most cases.

If you need to provide a certificate manually:

new Strategy(
	{
		// ... other options
		cert: fs.readFileSync('/path/to/idp-cert.pem', 'utf8'),
	},
	verifyCallback
);

Testing with Staging Environment

1. Request metadata from UBC IAM:

   • Provide them with your Service Provider's metadata
   • They will configure your app in their staging environment
   • They will provide you with Entity ID confirmation

2. Test in Staging:

   SAML_ENVIRONMENT=STAGING SAML_PRIVATE_KEY_PATH=/path/to/key node app.js

3. Validate attributes:

   • Visit https://authentication.stg.id.ubc.ca/idp/shibboleth to see available attributes
   • Add to attributeConfig in your code

Production Deployment

1. Work with UBC IAM to:

   • Register your production URLs (issuer, callbackUrl)
   • Confirm entity ID and metadata
   • Verify attributes are configured correctly

2. Deploy with production settings:

   SAML_ENVIRONMENT=PRODUCTION node app.js

Troubleshooting

"Failed to load private key"

• Ensure SAML_PRIVATE_KEY_PATH points to an existing file
• Check file permissions (app must be able to read it)
• Verify the file contains a valid PEM-formatted private key

"No X509Certificate found in IdP metadata"

• Check that the IdP metadata URL is accessible
• Verify you're using the correct environment
• Try accessing the metadata URL in a browser

SAML validation fails

• Verify your private key matches what UBC IAM has on file
• Check that your Service Provider's entityID (issuer) matches what's registered with UBC
• Ensure callbackUrl exactly matches what's registered with UBC IAM
• Check server clocks are synchronized (NTP)

Attributes not returned

• Verify attributes are listed in your attributeConfig
• Check that UBC IAM has authorized release of those attributes to your app
• Use the attributeConfig to only request attributes your app truly needs

Documentation

This package includes comprehensive documentation for different use cases:

• LOCAL_SETUP.md - Quick start guide for local development with SimpleSAMLphp using docker-simple-saml
• INTEGRATION-GUIDE.md - Complete integration guide for staging and production deployment
• ATTRIBUTES.md - Reference guide for all available SAML attributes
• ADDING_ATTRIBUTES.md - Guide for adding new attributes to the library
• GETTING_STARTED.md - High-level overview and key concepts
• TESTING.md - Testing strategies and debugging techniques
• DEVELOPMENT.md - For library maintainers and contributors

Contributing

For issues, questions, or contributions, please contact the UBC IAM team.

License

GPL v3

References

• Passport.js Documentation
• Passport-SAML Documentation
• SAML 2.0 Standard
• Shibboleth Documentation