Rampart provides a secure Single Sign-On (SSO) system that allows you to seamlessly authenticate users and businesses in your application in a SAML-like way.

​
Overview

The SSO integration process follows these 5 key steps:

  1. User navigates to your Rampart instance or you redirect them there
  2. Rampart redirects the user to your application’s SSO page if they don’t have an active session
  3. Your app creates and sends a signed JWT token with user/business data to Rampart’s API
  4. Rampart creates/logs in the account and provides you with a redirect URL and account token
  5. Your app redirects the user to the provided URL to complete the authentication

​
Step-by-Step Implementation

​
Step 1: User Navigates to Rampart

The user can either navigate directly to your Rampart instance or you can redirect them from your application:

// Redirect user to your Rampart instance
window.location.href = 'https://[your-rampart-domain].com';

​
Step 2: Handling Rampart’s Authentication Redirect

When a user visits your Rampart instance without an active session, Rampart redirects them to your SSO page.

​
Configuring Your SSO URL

Important: You must register your SSO URL in the Rampart Command Center:

  1. Log into your Rampart Command Center
  2. Navigate to the SSO URL Configuration section
  3. Enter the complete URL where you’ll handle SSO requests (e.g., https://your-app.com/rampart-sso)
  4. Click Save

​
Implementation Requirements

Your SSO page must:

  1. Receive redirects from Rampart
  2. Check if the user is authenticated in your system
  3. Generate and send the JWT token with user/business data to Rampart (details in Step 3)

​
Handling Common Scenarios

User is logged out of your application

// If user is not logged in
if (!isUserAuthenticated()) {
  // Save the original Rampart redirect information
  storeRedirectInfo(request.params);
  
  // Redirect to your login page with a return path
  window.location.href = `/login?returnTo=${encodeURIComponent('/rampart-sso')}`;
  return;
}

// After successful login, redirect back to SSO page to complete the flow

First-Time Connections

We discuss about the Rampart’s accountToken in Step 4.
// Check if this is the first time connecting to Rampart by looking for an existing account token
const hasExistingConnection = await checkForRampartAccountToken(business.id);

if (!hasExistingConnection) {
  // Show consent screen before proceeding
  showDataSharingConsentScreen()
    .then(userConsented => {
      if (userConsented) {
        // User has given consent, proceed with the SSO flow
        proceedWithSsoFlow();
      } else {
        // Handle the case where the user does not consent to sharing their data
      }
    });
} else {
  // Proceed directly with SSO flow for returning users
  proceedWithSsoFlow();
}

Redirecting to Rampart from your application

With your SSO page configured, you can now create direct links to Rampart from anywhere in your application. The authentication flow happens automatically:

  1. User clicks a link to your Rampart instance
  2. If they don’t have an active session, Rampart redirects to your SSO page
  3. Your SSO page handles authentication and completes the flow
  4. User arrives at their intended Rampart destination

Example implementation:

<!-- On a Staples vendor profile page -->
<button onclick="window.location.href = 'https://your-rampart-domain.com/vendor/staples'">
  Calculate my Potential Savings on Staples
</button>

​
Step 3: Create and Send JWT Payload

​
Required Data Structure

{
  user: {                  // User information
    id: string;            // Unique identifier for the user
    firstName: string;     // User's first name
    lastName: string;      // User's last name
    email: string;         // User's email address
    phone?: string;        // User's phone number (optional)
  },
  business: {              // Business information
    id: string;            // Unique identifier for the business
    name: string;          // Business name
    addressLine1: string;  // Primary address
    addressLine2?: string; // Secondary address (optional)
    city: string;          // City
    state: string;         // State/Province
    zip: string;           // Postal/ZIP code
    country: string;       // Country
    email: string;         // Business email
    phone?: string;        // Business phone (optional)
  }
}

​
Create JWT Token

// Create payload with merged user and business data
const payload = {
  user: {
    id: '123',
    firstName: 'John',
    lastName: 'Doe',
    email: 'john@example.com',
    phone: '555-123-4567'
  },
  business: {
    id: 'b-456',
    name: 'Acme Inc',
    addressLine1: '123 Main St',
    city: 'Anytown',
    state: 'CA',
    zip: '12345',
    country: 'US',
    email: 'info@acme.com',
    phone: '555-987-6543'
  }
};

// Sign token using your RAMPART_SIGNING_KEY
const signedToken = jwt.sign(payload, RAMPART_SIGNING_KEY, {
  algorithm: 'HS256'
});

​
Send to Rampart API

const response = await axios.post('https://api.rampartcorporation.com/developer/v1/sso', {
  token: signedToken
}, {
  headers: {
    Authorization: `Bearer ${RAMPART_API_KEY}`,
    'Content-Type': 'application/json'
  }
});

// Extract link and accountToken from response
const { link, accountToken } = response.data;

​
Step 4: Receive Redirect URL and Account Token

The Rampart API response contains:

{
  "link": "https://[your-rampart-domain].com/sso#...",
  "accountToken": "[accountToken]"
}

You should:

  • Store the accountToken securely with the user’s data for future API calls (e.g retrieving his notifications, savings analysis, etc)
  • Prepare to redirect the user to the provided link

​
Step 5: Redirect User to Complete Authentication

Store the accountToken with the company record in your database, not with individual users. Rampart’s API primarily operates at the company level rather than the user level.

// Store accountToken securely in your database or session
storeAccountToken(business.id, accountToken);

// Redirect user to the provided link
window.location.href = link;

​
Complete Example

import jwt from 'jsonwebtoken';
import axios from 'axios';

// Function to handle SSO integration
async function handleSSOIntegration(userData, businessData) {
  try {
    // 1. Create merged payload
    const payload = {
      user: {
        id: userData.id,
        firstName: userData.firstName,
        lastName: userData.lastName,
        email: userData.email,
        phone: userData.phone
      },
      business: {
        id: businessData.id,
        name: businessData.name,
        addressLine1: businessData.addressLine1,
        addressLine2: businessData.addressLine2,
        city: businessData.city,
        state: businessData.state,
        zip: businessData.zip,
        country: businessData.country,
        email: businessData.email,
        phone: businessData.phone
      }
    };

    // 2. Sign token
    const signedToken = jwt.sign(payload, RAMPART_SIGNING_KEY, {
      algorithm: 'HS256'
    });

    // 3. Call SSO endpoint
    const response = await axios.post('https://api.rampartcorporation.com/developer/v1/sso', {
      token: signedToken
    }, {
      headers: {
        Authorization: `Bearer ${RAMPART_API_KEY}`,
        'Content-Type': 'application/json'
      }
    });

    // 4. Store account token
    const { link, accountToken } = response.data;
    await storeAccountToken(businessData.id, accountToken);

    // 5. Redirect user
    window.location.href = link;
  } catch (error) {
    console.error('SSO integration failed:', error);
    // Handle error appropriately
  }
}