OAuth 2.0 / SSO

TruthVouch supports enterprise Single Sign-On (SSO) via OAuth 2.0 and SAML 2.0. Enable SSO to:

• Centralize user authentication with your existing identity provider
• Enforce MFA and password policies from your organization
• Automatically provision and deprovision users (JIT - Just-In-Time)
• Reduce support burden for password resets

Supported Identity Providers

Provider	Protocol	Status
Okta	OAuth 2.0 + SAML 2.0	Fully Supported
Azure Active Directory	OAuth 2.0 + SAML 2.0	Fully Supported
Google Workspace	OAuth 2.0	Fully Supported
OneLogin	OAuth 2.0 + SAML 2.0	Fully Supported
Generic OIDC	OpenID Connect	Fully Supported
Generic SAML 2.0	SAML 2.0	Fully Supported

Quick Setup

1. Go to Settings

In the TruthVouch dashboard:

1. Click Settings → Security → Single Sign-On
2. Select your identity provider
3. Follow the provider-specific setup wizard

2. Configure in Your Identity Provider

Each provider requires you to:

• Set the Redirect URI: https://app.truthvouch.com/auth/callback
• Set the Logout URL: https://app.truthvouch.com/auth/logout
• Map your user attributes (see below)

3. Enable SSO

In TruthVouch:

1. Click Enable Single Sign-On
2. Paste the configuration from your identity provider
3. Click Test Connection
4. On success, click Activate

---

Provider-Specific Setup

Okta

In Okta Admin Console:

1. Create an OIDC app:

   • Go to Applications → Applications → Create App Integration
   • Choose OIDC - OpenID Connect → Web Application
   • Application name: “TruthVouch”
   • Base URIs: https://app.truthvouch.com
   • Login redirect URIs: https://app.truthvouch.com/auth/callback
   • Logout redirect URIs: https://app.truthvouch.com/auth/logout

2. Get credentials:

   • Copy the Client ID and Client Secret from the Application page
   • Copy your Okta Domain (e.g., company.okta.com)

3. Attribute mapping:

   • In the app, go to Okta API Scopes and request openid, email, profile
   • Verify that email is included in the ID token

In TruthVouch:

Settings → Security → Single Sign-On → Okta

Client ID:     (from Okta)
Client Secret: (from Okta)
Okta Domain:   company.okta.com
Scopes:        openid email profile

Azure AD

In Azure Portal:

1. Register an app:

   • Go to Azure AD → App registrations → New registration
   • Name: “TruthVouch”
   • Supported account types: “Accounts in this organizational directory only”
   • Redirect URI: https://app.truthvouch.com/auth/callback

2. Create a client secret:

   • Go to Certificates & secrets → Client secrets → New client secret
   • Copy the Client ID and Client Secret (secret value, not ID)
   • Note your Tenant ID (from Overview page)

3. Configure API permissions:

   • Go to API permissions → Add a permission → Microsoft Graph
   • Select: User.Read, email, profile

In TruthVouch:

Settings → Security → Single Sign-On → Azure AD

Client ID:       (from Azure)
Client Secret:   (from Azure)
Tenant ID:       (from Azure)
Authority URL:   https://login.microsoftonline.com/{tenantId}/v2.0

Google Workspace

In Google Cloud Console:

1. Create an OAuth consent screen:

   • Go to APIs & Services → OAuth consent screen
   • User type: “Internal” (if Google Workspace org)
   • Add scopes: openid, email, profile

2. Create OAuth 2.0 credentials:

   • Go to Credentials → Create Credentials → OAuth client ID
   • Application type: “Web application”
   • Authorized JavaScript origins: https://app.truthvouch.com
   • Authorized redirect URIs: https://app.truthvouch.com/auth/callback
   • Copy the Client ID and Client Secret

In TruthVouch:

Settings → Security → Single Sign-On → Google Workspace

Client ID:     (from Google Cloud)
Client Secret: (from Google Cloud)

OneLogin

In OneLogin Admin Console:

1. Create an app:

   • Go to Applications → Add App
   • Search for “OpenID Connect” (web)
   • Give it a name: “TruthVouch”

2. Configure:

   • Redirect URI: https://app.truthvouch.com/auth/callback
   • Save the app
   • Go to the app’s Configuration tab
   • Copy Client ID and Client Secret
   • Copy your OneLogin Domain (e.g., company.onelogin.com)

In TruthVouch:

Settings → Security → Single Sign-On → OneLogin

Client ID:       (from OneLogin)
Client Secret:   (from OneLogin)
OneLogin Domain: company.onelogin.com

---

Just-In-Time (JIT) Provisioning

Enable automatic user provisioning on first SSO login:

Settings → Security → SSO → Just-In-Time Provisioning

When enabled:

1. User logs in via SSO for the first time
2. TruthVouch automatically creates a user account with:
   • Email from SSO provider
   • Role: “developer” (default, configurable)
   • Organization: Determined by email domain or custom mapping
3. User is logged in immediately — no admin approval needed

JIT Role Assignment

Configure how new users are assigned roles on first login:

• Default Role: “developer” (view alerts, run scans)
• Admin Domain Mapping: @company.com → admin
• Viewer Domain Mapping: @partner.com → viewer

---

User Attribute Mapping

When configuring SSO, map your identity provider’s user attributes to TruthVouch claims:

{
  "email": "user@company.com",        // Required
  "given_name": "John",               // Optional
  "family_name": "Doe",               // Optional
  "picture": "https://...",           // Optional (avatar)
  "organization": "Engineering",      // Optional (used for grouping)
  "department": "Backend",            // Optional
  "roles": ["developer"],             // Optional (from custom claim)
  "groups": ["developers", "oncall"]  // Optional
}

Most identity providers automatically include these claims. Verify in your provider’s documentation.

---

Testing Your SSO Setup

Test Flow

1. Logout of TruthVouch (or use incognito window)
2. On the login page, click “Sign in with [Provider]”
3. Authenticate with your identity provider
4. You should be redirected to the TruthVouch dashboard
5. Verify your email and role in Settings → Profile

Troubleshooting

“Invalid redirect URI”

• Verify the Redirect URI in your identity provider matches exactly: https://app.truthvouch.com/auth/callback

“User not found”

• Ensure the user exists in your identity provider
• For JIT provisioning, ensure JIT is enabled in TruthVouch

“Invalid client secret”

• Regenerate the client secret in your identity provider
• Copy the entire secret value (not the ID)

“Incorrect attribute mapping”

• Check that email is being passed in the email claim (not mail or emailAddress)
• Test with a simple OpenID Connect debugger: https://oidcdebugger.com/

---

Enabling SSO for Your Team

After testing:

1. Disable password login (optional):

   • Settings → Security → Disable password authentication
   • This forces all users to use SSO

2. Notify your team:

   • Send login URL: https://app.truthvouch.com/login
   • Users see “Sign in with [Provider]” option

3. Migrate existing users:

   • If JIT is enabled, existing users log in via SSO automatically
   • Their accounts are linked to SSO identity
   • You can manually deprovision unused local accounts

---

SAML 2.0 Setup (Advanced)

For organizations using SAML 2.0 exclusively:

In TruthVouch:

• Settings → Security → SSO → SAML 2.0
• Download the SP Metadata XML

In Your Identity Provider:

• Import the SP Metadata XML
• Verify the Entity ID and ACS URL match

Attribute assertions (example):

<Attribute Name="email">
  <AttributeValue>user@company.com</AttributeValue>
</Attribute>
<Attribute Name="firstName">
  <AttributeValue>John</AttributeValue>
</Attribute>
<Attribute Name="lastName">
  <AttributeValue>Doe</AttributeValue>
</Attribute>

---

Tenant Isolation

All users authenticated via SSO are automatically filtered by their organization ID from the JWT token. API calls only return data for the authenticated user’s organization.

---

Next Steps

• SCIM User Provisioning →
• API Keys →
• JWT Tokens →
• User Management →