SSO (Single Sign-On)

SSO allows advisors to log into RightCapital from Vendor systems (or vice versa) without separate authentication. This improves user experience and is often bundled with data integrations.

Code Location: gitlab.rightcapital.io/web-service/api/-/tree/develop/app/Http/Controllers/Sso

Key Concepts

Identity Provider (IdP)

The system that authenticates users and provides identity information.

In IdP-initiated SSO: Vendor is the IdP, RightCapital trusts Vendor’s authentication
Example: Advisor logs into Schwab, clicks link to RightCapital, lands authenticated

Service Provider (SP)

The system that receives authentication assertions and provides services.

In IdP-initiated SSO: RightCapital is the SP
We validate the SSO request and create a session

SAML (Security Assertion Markup Language)

The most common protocol for enterprise SSO. Vendor sends a signed XML assertion containing user identity.

SSO Types

IdP-initiated SSO (Most Common)

Advisor starts at Vendor, clicks link to RightCapital:

sequenceDiagram
    participant A as Advisor
    participant V as Vendor (IdP)
    participant RC as RightCapital (SP)

    A->>V: Login to Vendor
    A->>V: Click "Open in RightCapital"
    V->>V: Generate SAML assertion
    V->>RC: POST SAML assertion
    RC->>RC: Validate signature & assertion
    RC->>RC: Look up advisor by identifier
    RC->>RC: Create session
    RC->>A: Redirect to application

SP-initiated SSO (Less Common)

Advisor starts at RightCapital, authenticates via Vendor:

sequenceDiagram
    participant A as Advisor
    participant RC as RightCapital (SP)
    participant V as Vendor (IdP)

    A->>RC: Click "Login with Vendor"
    RC->>V: Redirect to Vendor login
    A->>V: Authenticate
    V->>RC: POST SAML assertion
    RC->>RC: Validate & create session
    RC->>A: Redirect to application

Contextual SSO

SSO with additional context (e.g., specific household):

Advisor SSOs from Vendor with a household identifier
RightCapital opens that specific household automatically
Combines SSO with data import functionality

SAML Response Validation

When receiving a SAML assertion, we validate:

Field	Validation
Signature	Verify XML signature using Vendor’s certificate
Issuer	Must match expected Vendor identifier
Audience	Must match our SP entity ID
NotBefore / NotOnOrAfter	Assertion must be within valid time window
Subject	Contains the user identifier (email, advisor ID)
Conditions	Check any additional conditions

SSO Providers

RightCapital supports SSO with many Vendors. See SSO Providers list for current integrations.

Organization SSO

Some organizations (advisor firms) want their advisors to SSO into RightCapital using their corporate IdP (Okta, Azure AD, etc.).

This is different from Vendor SSO:

Vendor SSO: Vendor (Schwab, Fidelity) is IdP
Organization SSO: Advisor’s employer/firm is IdP

Setup

Organization SSO requires configuration:

Exchange metadata with organization’s IdP
Configure SSO settings via command
Test in QA environment
Enable in production

See: Organization SSO Documentation

Implementation

Adding a New SSO Vendor

Create Controller: Add new controller in app/Http/Controllers/Sso/
Handle SAML Assertion: Parse and validate incoming SAML
Map User: Look up advisor by identifier from assertion
Create Session: Log in the advisor
Configure Routes: Add SSO endpoint routes
Test: Verify with Vendor’s test environment

Common Controller Pattern

class VendorSsoController extends Controller
{
    public function handle(Request $request)
    {
        // 1. Parse SAML response
        $samlResponse = $this->parseSamlResponse($request);

        // 2. Validate signature and assertion
        $this->validateAssertion($samlResponse);

        // 3. Extract user identifier
        $vendorUserId = $samlResponse->getNameId();

        // 4. Look up RightCapital advisor
        $advisor = $this->findAdvisor($vendorUserId);

        // 5. Create session
        Auth::login($advisor);

        // 6. Redirect to application
        return redirect()->route('advisor.dashboard');
    }
}

Troubleshooting

SSO Failed - User Not Found

Check if advisor has integration set up
Verify identifier in SAML matches our records
Check for email vs ID mismatch

SSO Failed - Invalid Signature

Vendor’s certificate may have changed
Check if we have the correct certificate configured
Time sync issues between servers

SSO Failed - Expired Assertion

Check server time synchronization
Assertion may be too old (clock skew tolerance)

Architecture - Overall system design
API Integrations - Often paired with SSO