---

name: docs-sso-saml-setup
description: Use when an enterprise customer's IT administrator needs to configure Single Sign-On (SSO) for Louis using SAML 2.0 with their identity provider (Okta, Azure AD / Entra ID, Google Workspace, or Auth0). Covers the end-to-end setup flow, attribute mapping, tenant and group provisioning, testing, and rollout. Applicable across all jurisdictions for any Enterprise-tier deployment.
license: MIT
metadata:
id: docs.SSO-SAML-setup
category: docs
jurisdictions: [multi]
priority: P2
intent: [SSO, SAML, identity provider, enterprise auth, Okta, Azure AD]
related: [docs-security-overview, docs-team-roles-permissions, docs-tenant-isolation-explainer]
source: Louis — HAQQ Legal AI (github.com/sboghossian/mini-claude-for-legal)
version: "1.0"

SSO / SAML 2.0 Setup Guide

Prerequisites

• Louis Enterprise tier (SSO is an Enterprise feature; contact sales if on a lower plan).
• Administrative access to your Identity Provider (IdP).
• A domain verified in your Louis organization settings.
• (Optional) Security groups or AD groups that map to Louis roles.

Overview of the flow

User browser → Louis login page
  → Redirect to IdP (with SAML AuthnRequest)
  → IdP authenticates user
  → IdP posts SAML Response (assertion) back to Louis ACS URL
  → Louis validates signature, maps attributes, creates/updates session
  → User lands in Louis

Step 1 — Retrieve Louis service provider (SP) metadata

1. In Louis, go to Settings → Organization → Security → SSO.
2. Click Configure SSO.
3. Download or copy:
   • SP Entity ID (also called Audience URI): https://app.haqq.ai/saml/metadata
   • ACS (Assertion Consumer Service) URL: https://app.haqq.ai/saml/acs
   • SP Metadata XML (download and upload directly to your IdP if supported).

Step 2 — Configure your Identity Provider

Okta

1. In Okta Admin Console: Applications → Create App Integration → SAML 2.0.
2. Set Single sign-on URL to the ACS URL above.
3. Set Audience URI (SP Entity ID) to the SP Entity ID above.
4. Under Attribute Statements, add:
   • email → user.email
   • firstName → user.firstName
   • lastName → user.lastName
   • groups → user.groups (for role mapping — see Step 4)
5. Download the IdP metadata XML.
6. Assign the application to the relevant Okta groups.

Azure AD / Microsoft Entra ID

1. In Azure Portal: Enterprise Applications → New Application → Create your own → Integrate any other application.
2. Go to Single sign-on → SAML.
3. Set Identifier (Entity ID) to SP Entity ID; Reply URL (ACS URL) to ACS URL.
4. Under Attributes & Claims, map:
   • emailaddress → user.mail
   • givenname → user.givenname
   • surname → user.surname
   • groups → Group ObjectIDs (or display names if configured)
5. Download Federation Metadata XML.
6. Assign users or groups to the application.

Google Workspace

1. In Google Admin Console: Apps → Web and mobile apps → Add app → Add custom SAML app.
2. Download the IdP metadata at step 1 of Google's wizard.
3. Set ACS URL and Entity ID as above.
4. Under Attribute mapping:
   • email → Primary email
   • firstName → First name
   • lastName → Last name
5. Enable the app for the relevant OUs.

Auth0

1. In Auth0 Dashboard: Applications → Create Application → Regular Web Application.
2. Go to Addons → SAML2 Web App.
3. Set Application Callback URL to ACS URL.
4. In Settings (JSON), set audience to SP Entity ID.
5. Map attributes in the settings block:

   {
     "mappings": {
       "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
       "given_name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
       "family_name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"
     }
   }
   

6. Download IdP metadata or note the IdP SSO URL and certificate.

Step 3 — Upload IdP metadata to Louis

1. Back in Louis Settings → SSO, click Upload IdP Metadata and upload the XML file (or paste the metadata URL / individual fields).
2. Fields required if not using metadata XML:
   • IdP Entity ID
   • IdP SSO URL (redirect binding)
   • IdP certificate (PEM format, X.509)

Step 4 — Map groups to Louis roles

Louis supports automatic role assignment based on SAML group attributes:

SAML group name (example)	Louis role
louis-admins	Admin
louis-lawyers	Lawyer
louis-paralegals	Paralegal
louis-viewers	Viewer
louis-billing	Billing Admin

Configure the mapping in Settings → SSO → Role Mapping. If a user belongs to multiple groups, the highest-privilege role wins. Users with no matched group receive the default role (configurable; default: Viewer).

Step 5 — Test before rollout

1. Click Test SSO in Louis settings — this opens a new browser tab and initiates a SAML flow using a test user account.
2. Verify:
   • Login completes without error.
   • User's name and email are populated correctly.
   • Role is assigned as expected.
3. Check the SAML assertion in the test panel to diagnose attribute-mapping issues.

Common errors:

• InvalidAudience: SP Entity ID mismatch — verify copy-paste accuracy, no trailing slash.
• Signature validation failed: Certificate expired or wrong cert uploaded.
• User not provisioned: User exists in IdP but not assigned to the application.

Step 6 — Roll out

1. Enable SSO Enforcement (optional): forces all users with your domain to authenticate via SSO; password login disabled for those users.
2. Communicate the change to users — they will be redirected to your IdP on next login.
3. Set a grace period (recommended 48 hours) during which both SSO and password login are accepted.
4. After grace period, enable enforcement.

JIT (Just-In-Time) provisioning

Louis supports JIT provisioning: the first time a user authenticates via SSO, an account is automatically created using the SAML attributes. No manual user invitation needed. If SCIM provisioning is required (automated de-provisioning), contact support for SCIM configuration.

Troubleshooting

Symptom	Likely cause	Fix
Redirect loop	ACS URL misconfigured in IdP	Verify ACS URL exactly
Wrong role assigned	Group attribute missing from assertion	Add group attribute in IdP app config
Clock skew error	Server time drift > 5 min	Sync NTP on IdP server
Certificate error	Expired IdP cert	Re-download and upload fresh cert

Related skills

• [[docs-security-overview]]
• [[docs-team-roles-permissions]]
• [[docs-tenant-isolation-explainer]]