Docs Sso Saml Setup

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:

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

Related skills

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