How to Configure SAML SSO

This guide walks you through configuring SAML-based Single Sign-On (SSO) for your SecureAI instance. SAML SSO lets your users log in with their existing corporate credentials instead of managing separate passwords.

Prerequisites

Before you begin, make sure you have:

• Admin access to your SecureAI instance.
• Admin access to your identity provider (Okta, Azure AD, Auth0, or another SAML 2.0-compatible IdP).
• Your SecureAI instance URL (e.g., https://your-org.secureai.example.com).

Step 1: Gather SecureAI SAML Details

From your SecureAI admin panel, navigate to Admin Panel > Settings > Authentication > SAML.

Note the following values — you will enter them in your identity provider:

Step 2: Configure Your Identity Provider

Okta

1. In the Okta Admin Console, go to Applications > Create App Integration.
2. Select SAML 2.0 and click Next.
3. Set the App name to "SecureAI" and click Next.
4. Enter the SAML settings:
   • Single sign-on URL: paste the ACS URL from Step 1.
   • Audience URI (SP Entity ID): paste the Entity ID from Step 1.
   • Name ID format: EmailAddress
   • Application username: Email
5. Under Attribute Statements, add:
   • email → user.email
   • firstName → user.firstName
   • lastName → user.lastName
6. Click Next, select "I'm an Okta customer adding an internal app", then Finish.
7. On the Sign On tab, find the Metadata URL (under "SAML Signing Certificates" > Actions > View IdP metadata). Copy this URL.

Azure AD (Microsoft Entra ID)

1. In the Azure portal, go to Microsoft Entra ID > Enterprise Applications > New Application.
2. Click Create your own application, name it "SecureAI", and select "Integrate any other application you don't find in the gallery".
3. Go to Single sign-on > SAML.
4. In Basic SAML Configuration, set:
   • Identifier (Entity ID): paste the Entity ID from Step 1.
   • Reply URL (ACS URL): paste the ACS URL from Step 1.
   • Sign on URL: your SecureAI instance URL.
5. In Attributes & Claims, verify these claims exist:
   • emailaddress → user.mail
   • givenname → user.givenname
   • surname → user.surname
6. In SAML Certificates, copy the App Federation Metadata URL.
7. Assign users or groups under the Users and groups tab.

Auth0

1. In the Auth0 Dashboard, go to Authentication > Enterprise > SAMLP Identity Provider.
2. Click Create Connection and name it "SecureAI".
3. Enter the following:
   • Sign In URL: your Auth0 tenant's SAML login URL (found in the connection's setup instructions).
   • Sign Out URL: the Single Logout URL from Step 1.
4. Download the Auth0 IdP Metadata file from the connection's setup page.
5. In your Auth0 Application settings, enable this SAML connection under Connections > Enterprise.

Other SAML 2.0 Providers

For other SAML-compliant identity providers, configure a new SAML application with:

• ACS URL / Reply URL: https://your-org.secureai.example.com/saml/acs
• Entity ID / Audience: https://your-org.secureai.example.com/saml/metadata
• Name ID format: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
• Required attributes: email, firstName, lastName

Then export or copy your IdP's metadata URL or XML.

Step 3: Enter IdP Details in SecureAI

1. Return to Admin Panel > Settings > Authentication > SAML.
2. Toggle Enable SAML SSO to on.
3. Enter the IdP Metadata URL you copied from your identity provider. Alternatively, upload the metadata XML file if your IdP does not provide a URL.
4. Configure attribute mapping if your IdP uses non-standard attribute names:
   • Email attribute: default email (Azure AD uses http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress)
   • First name attribute: default firstName (Azure AD uses http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname)
   • Last name attribute: default lastName (Azure AD uses http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname)
5. Click Save.

Step 4: Test the Connection

1. Open a private/incognito browser window.
2. Navigate to your SecureAI login page.
3. You should see a Sign in with SSO button.
4. Click it and verify you are redirected to your identity provider's login page.
5. After authenticating, you should be redirected back to SecureAI and logged in.

If the test fails, see Troubleshooting below.

Step 5: Configure SSO Policies (Optional)

After verifying the connection works, you can optionally:

• Require SSO for all users: Under Admin Panel > Settings > Authentication, toggle "Require SSO" to prevent password-based logins.
• Auto-provision users: Enable "Just-in-time provisioning" to automatically create SecureAI accounts for any user who authenticates through your IdP.
• Map IdP groups to roles: Under the SAML settings, configure group attribute mapping to automatically assign Admin or User roles based on IdP group membership.

Troubleshooting

"Invalid SAML response" error

• Verify the ACS URL in your IdP matches exactly: https://your-org.secureai.example.com/saml/acs
• Check that the Entity ID in your IdP matches the Entity ID shown in SecureAI.
• Ensure your IdP's signing certificate has not expired.

User is authenticated but gets "account not found"

• The email address returned by your IdP must match an existing SecureAI user, or you must enable Just-in-time provisioning.
• Check that the email attribute mapping is correct in Step 3.

Redirect loop after login

• Clear the browser cache and cookies, then try again in an incognito window.
• Verify the Sign-on URL in your IdP points to your correct SecureAI instance URL.
• Ensure your IdP is not sending the user to a different ACS URL.

SSO button does not appear on login page

• Confirm that Enable SAML SSO is toggled on in the admin panel.
• Verify the IdP metadata was saved successfully (check for validation errors).

Next Steps

• Review the User Management guide for managing SSO-provisioned users.
• Consider setting up SCIM provisioning for automated user lifecycle management (contact support for availability).
• For OIDC-based SSO, see the OIDC configuration guide (coming soon).