GitHubSupport

Integration Guide

SSO Version: 5.24.0

Overview

This guide walks you through integrating the SSO service into your application using OAuth 2.0. Follow these steps to enable secure authentication for your users.

⚠️ Important: This guide is for application developers integrating with the SSO service, not for deploying the SSO service itself.

Prerequisites

  • Node.js 18.x or higher (for backend token exchange)
  • A web application (React, Vue, vanilla JS, etc.)
  • HTTPS-enabled domain (required for production)
  • Email access to contact SSO admin

Step 1: Register Your Application

Before you can integrate, you must register your application with the SSO admin:

  1. Contact SSO admin: sso@doneisbetter.com
  2. Provide the following information:
    • Application Name: e.g., "MyApp Production"
    • Redirect URIs: e.g., https://myapp.com/api/auth/callback
    • Allowed Origins: e.g., https://myapp.com
    • Application Description: Brief description of your app
  3. Wait for approval (typically within 24 hours)
  4. Receive your client_id and client_secret
📝 Note: For local development, use http://localhost:PORT/api/auth/callback as your redirect URI. Localhost origins are automatically allowed.

Step 2: Install Dependencies

Install required packages for OAuth 2.0 token handling:

# For Node.js/Express backend
npm install jsonwebtoken

# Optional: For making HTTP requests
npm install node-fetch  # or axios

# For Next.js projects (already includes fetch)
npm install jsonwebtoken

Step 3: Configure Environment Variables

Create a .env file in your project root (backend only):

# .env (Backend - NEVER commit this file!)

# OAuth 2.0 Credentials (from SSO admin)
SSO_CLIENT_ID=your_client_id_here
SSO_CLIENT_SECRET=your_client_secret_here
SSO_REDIRECT_URI=https://yourapp.com/api/auth/callback

# SSO Service Configuration
SSO_BASE_URL=https://sso.doneisbetter.com

# Session Configuration
SESSION_SECRET=your_random_secret_here
NODE_ENV=production

# Development override (optional)
# SSO_REDIRECT_URI=http://localhost:3000/api/auth/callback

Generate Session Secret

# Generate a secure random secret
openssl rand -base64 32

Step 4: Implement OAuth 2.0 Flow

Follow the implementation guide for your framework:

Or implement manually by following the OAuth 2.0 Authentication Flow guide.

Step 5: Test Your Integration

Development Testing

  1. Start your application: npm run dev
  2. Navigate to your login page
  3. Click "Sign in with SSO"
  4. You should be redirected to https://sso.doneisbetter.com
  5. Login with test credentials (provided by SSO admin)
  6. Verify you're redirected back to your app
  7. Check that user info is displayed correctly

Verify Token Exchange

// Add logging to your OAuth callback handler
console.log('Authorization code received:', code);
console.log('Tokens received:', { access_token, id_token, refresh_token });

// Decode ID token to verify user info
const decoded = jwt.decode(id_token);
console.log('User info:', decoded);
console.log('Permission status:', decoded.permissionStatus);

Step 6: Request Production Access

Once testing is complete, request production access approval:

  1. Test your application thoroughly in development
  2. Login and verify OAuth flow works correctly
  3. Test token refresh and logout
  4. Contact SSO admin to register your production domain
  5. Update environment variables with production values
  6. Deploy your application
  7. Request SSO admin to grant you "approved" permission status

Common Integration Issues

Redirect URI Mismatch

Error: redirect_uri_mismatch

Solution: Ensure your SSO_REDIRECT_URI exactly matches what you registered with SSO admin (including protocol and path).

Origin Not Allowed

Error: CORS error in browser console

Solution: Contact SSO admin to register your origin. See CORS Configuration.

Invalid Client

Error: invalid_client

Solution: Verify your client_id and client_secret are correct.

Token Exchange Fails

Error: 401 from token endpoint

Solutions:

  • Ensure token exchange happens on backend (not frontend)
  • Verify client_secret is not exposed in browser
  • Check authorization code is used within 10 minutes
  • Confirm code hasn't been used already (single-use)

Next Steps

Support

Need help with integration?