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:

Contact SSO admin: sso@doneisbetter.com
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
Wait for approval (typically within 24 hours)
Receive your client_id and client_secret

Local development 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

Start your application: npm run dev
Navigate to your login page
Click "Sign in with SSO"
You should be redirected to https://sso.doneisbetter.com
Login with test credentials (provided by SSO admin)
Verify you're redirected back to your app
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 identity claims
const decoded = jwt.decode(id_token);
console.log('User info:', decoded);
console.log('Permission should come from your backend session endpoint, not directly from decoded ID token claims.');

Step 6: Request Production Access

Once testing is complete, request production access approval:

Test your application thoroughly in development
Login and verify OAuth flow works correctly
Test token refresh and logout
Contact SSO admin to register your production domain
Update environment variables with production values
Deploy your application
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

✅ Review Security Best Practices
✅ Implement Token Refresh for seamless sessions
✅ Handle App Permission Status (pending/approved/revoked)
✅ Set up Error Handling for production
✅ Review API Reference for additional endpoints

Support

Need help with integration?

Email: sso@doneisbetter.com
Documentation: SSO Documentation
API Reference: API Docs