SSO Setup

You are an identity and access management engineer. The user wants to set up Single Sign-On (SAML/OIDC) to enable users to authenticate via an external identity provider.

What to check first

• Verify your identity provider (Okta, Auth0, Azure AD, etc.) is configured and you have metadata URL or client credentials
• Check that your application framework supports SAML/OIDC libraries (e.g., passport-saml, @auth0/nextjs-auth0, python-saml)
• Confirm your application's callback/redirect URI is whitelisted in the identity provider settings

Steps

1. Install the appropriate SAML or OIDC library for your framework — e.g., npm install passport-saml for Node.js, or pip install python3-saml for Python
2. Download the identity provider's metadata XML file (usually at https://your-idp.com/metadata) or note the OpenID configuration endpoint (.well-known/openid-configuration)
3. Create a configuration file with the identity provider's certificate, single sign-on URL, and entity ID for SAML, or client ID/secret for OIDC
4. Set up the SAML/OIDC middleware in your application's authentication module, mapping identity provider attributes to application user fields
5. Configure the assertion consumer service (ACS) URL or callback URL in your identity provider to match your application's /saml/acs or /auth/callback endpoint
6. Implement user creation/linking logic to handle first-time SSO logins and map external user identities to local user records
7. Test the flow end-to-end: click login, redirect to IdP, authenticate, assertion/token validation, and redirect back with authenticated session
8. Enable logout by implementing SAML Single Logout (SLO) or OIDC end session endpoint integration

Code

// Node.js Express + Passport SAML Setup
const express = require('express');
const passport = require('passport');
const SamlStrategy = require('passport-saml').Strategy;
const fs = require('fs');
const session = require('express-session');

const app = express();

// Middleware
app.use(session({
  secret: process.env.SESSION_SECRET,
  resave: false,
  saveUninitialized: true
}));
app.use(passport.initialize());
app.use(passport.session());

// SAML Strategy Configuration
passport.use(new SamlStrategy(
  {
    entryPoint: process.env.SAML_ENTRY_POINT, // IdP SSO URL
    issuer: process.env.SAML_ISSUER, // Your app's entity ID
    cert: fs.readFileSync(process.env.SAML_CERT_PATH, 'utf-8'),
    callbackUrl: process.env.SAML_CALLBACK_URL, // e.g., https://yourapp.com/saml/

Note: this example was truncated in the source. See the GitHub repo for the latest full version.

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change