Overview

SAML (Security Assertion Markup Language) is an open-standard format for exchanging authentication and authorization data between an identity provider (IdP) and a service provider (SP). As a service provider, QuikData supports both IdP-initiated and SP-initiated SAML single sign-on (SSO).

• IdP-initiated SSO: The user starts at their Identity Provider (e.g., Microsoft Entra ID, Google Workspace, Okta), selects the QuikData application, and is redirected to QuikData with a SAML assertion.
• SP-initiated SSO: The user starts at the QuikData login page. QuikData identifies the user's email domain, generates a SAML authentication request, and redirects the user to their Identity Provider to authenticate. After authentication, the IdP sends the user back to QuikData with a SAML assertion.

How SAML Works with QuikData

SAML assertions (tokens) verify user identity when logging into the platform. These assertions contain:

• User Identity: Information about the individual who has logged in
• Issuer URL: The identity provider that issued the assertion (configured as the Endpoint URL in QuikData)
• Audience: The intended recipient of the assertion (QuikData)
• Digital Signature: Cryptographic protection ensuring the assertion hasn't been tampered with

An assertion is only valid if it originates from a known Issuer URL, is addressed to the expected Audience, and is correctly signed.

Multi-IdP Support and Email Domain Mapping

QuikData supports multiple identity providers simultaneously by mapping user email domains to specific IdPs. This allows organizations to:

• Route users from different domains to different identity providers
• Support subsidiaries or departments with separate IdP configurations
• Maintain fallback authentication for unmapped domains

Important: Users whose email domain is not mapped to an IdP will authenticate using QuikData's integrated username and password system. All users must be created within the QuikData site before their first SAML login attempt.

SAML Workflow

Workflow Steps Explained

1. User Authentication: The user logs into their organization's identity provider (e.g., Microsoft Entra ID, Google Workspace, Okta)
2. Application Selection: The user selects the QuikData application from their IdP's app catalog or dashboard
3. Assertion Generation: The IdP creates a SAML assertion containing the user's identity information and digitally signs it
4. Browser POST: The Identity Provider sends a SAML response to the user's browser, which automatically POSTs it to QuikData's Assertion Consumer Service (ACS) endpoint
5. Validation: QuikData validates the assertion by verifying the issuer, audience, signature, and that the user exists in the system
6. Access Granted: Upon successful validation, the user is logged into QuikData

Configuration Prerequisites

Before configuring SAML SSO, ensure the following requirements are met:

Identity Provider Requirements

• Your organization must have a SAML 2.0 compatible Identity Provider
• The IdP must be network-accessible from the QuikData web application server
• The IdP must be configured to send assertions to QuikData's ACS endpoint

QuikData Requirements

• Site Administrator privileges are required to configure SSO
• Users must be pre-created in QuikData before they can authenticate via SAML
• User email addresses in QuikData must match the email/NameID sent by the IdP

Information You'll Need from Your IdP

• Issuer URL (also called Entity ID or Issuer)
• SSO Endpoint URL (also called SAML 2.0 Endpoint or Login URL)
• X.509 Certificate (for signature validation)

Information to Provide to Your IdP

When configuring QuikData as a Service Provider in your Identity Provider, you will need to provide the following values:

Note: Replace your-quikdata-server.com with your organization's actual QuikData server URL. The default ACS path is /Account/SAMLLogin, but this is configurable in Site Settings. Contact your QuikData administrator if you are unsure of the correct value.

Registering a SAML Identity Provider

Getting There

1. Log in to QuikData with a Site Administrator account
2. Navigate to Site Admin → Identity Providers
3. Click the New Identity Provider button

Registering a New Identity Provider

Click the "New Identity Provider" button to open the form to register a new IdP. The following popup form will appear:

• Domain Name
  The email domain for the users who should be routed to this Identity Provider during login. This determines which users are directed to authenticate through the IdP.
  Example: gmail.com
• Issuer Name
  The unique identifier of the Identity Provider, typically a URI string. QuikData uses this value to validate SSO requests and ensure they originate from the correct IdP. This must exactly match the Issuer value configured on your Identity Provider.
• Registered Name
  The registered application name associated with this SSO configuration. In most cases, this will simply be "QuikData". This value may be displayed in your Identity Provider's application catalog or user login flows.
• Endpoint Address
  The Identity Provider's Single Sign-On URL (also called Login URL or SAML 2.0 Endpoint). This is the URL where users are sent to authenticate with your IdP. This value is provided by your Identity Provider and is required for establishing a trusted connection.
• Certificate
  The X.509 certificate provided by the Identity Provider, used to validate signed SAML assertions or tokens. Uploading the certificate is required for production environments. Without certificate validation, SAML assertions cannot be verified as authentic, leaving the system vulnerable to forged login attempts. You may omit the certificate only during initial testing with non-production data.

Examples

Microsoft Entra ID (formerly Azure AD)

Step 1: Create an Enterprise Application in Entra ID

1. Sign in to the Microsoft Entra admin center
2. Navigate to Identity → Applications → Enterprise applications
3. Click New application → Create your own application
4. Enter "QuikData" as the application name
5. Select Integrate any other application you don't find in the gallery (Non-gallery)
6. Click Create

Step 2: Configure SAML SSO in Entra ID

1. In your new application, go to Single sign-on → Select SAML
2. In the Basic SAML Configuration section, click Edit and enter:
   • Identifier (Entity ID): QuikData (or your preferred identifier)
   • Reply URL (ACS URL): https://your-quikdata-server.com/Account/SAMLLogin (default endpoint; confirm with your QuikData administrator if customized)
3. In the Attributes & Claims section, ensure the following claim is configured:
   • Required claim: emailaddress → user.mail or user.userprincipalname
4. In the SAML Certificates section, download the Certificate (Base64)

Step 3: Gather Configuration Values

From the Set up QuikData section in Entra ID, copy:

• Login URL → Use as Endpoint Address in QuikData
• Microsoft Entra Identifier → Use as Issuer Name in QuikData

Step 4: Configure QuikData

Step 5: Assign Users in Entra ID

1. In the Enterprise application, go to Users and groups
2. Click Add user/group
3. Select the users or groups who should have access to QuikData
4. Click Assign

Google Workspace

Step 1: Create a Custom SAML Application

1. Sign in to the Google Admin Console
2. Navigate to Apps → Web and mobile apps
3. Click Add app → Add custom SAML app
4. Enter "QuikData" as the application name and click Continue

Step 2: Download Google IdP Information

On the Google Identity Provider details page:

1. Download the Certificate (you'll upload this to QuikData)
2. Copy the SSO URL → Use as Endpoint Address
3. Copy the Entity ID → Use as Issuer Name
4. Click Continue

Step 3: Configure Service Provider Details

Enter the following in Google Admin:

• ACS URL: https://your-quikdata-server.com/Account/SAMLLogin (default endpoint; confirm with your QuikData administrator if customized)
• Entity ID: QuikData
• Name ID format: EMAIL
• Name ID: Basic Information > Primary email

Click Continue, then Finish.

Step 4: Configure QuikData

Step 5: Enable the Application for Users

1. In the Google Admin Console, return to the QuikData app
2. Click User access
3. Select ON for everyone or configure organizational unit access
4. Click Save

Troubleshooting

Common Issues and Solutions

"User not found" Error

Cause: The user does not exist in QuikData, or the email address doesn't match.

Solution:

1. Verify the user exists in QuikData with the correct email address
2. Confirm the IdP is sending the email address as the NameID or in an email claim
3. Check for case sensitivity issues (some systems treat User@Domain.com and user@domain.com differently)

"Invalid Issuer" Error

Cause: The Issuer in the SAML assertion doesn't match the configured Issuer Name.

Solution:

1. Compare the Issuer value in QuikData with your IdP's Entity ID
2. Ensure exact character matching, including trailing slashes
3. Check for URL encoding differences

"Signature Validation Failed" Error

Cause: The certificate configured in QuikData doesn't match the signing certificate used by the IdP.

Solution:

1. Download a fresh certificate from your IdP
2. Upload the new certificate to QuikData
3. Ensure the certificate hasn't expired

"Audience Mismatch" Error

Cause: The Audience/SP Entity ID in the assertion doesn't match what QuikData expects.

Solution:

1. Verify the Audience URI/SP Entity ID configured in your IdP matches QuikData's expected value
2. Check the Registered Name field in QuikData

Users Are Not Being Routed to SSO

Cause: The email domain isn't mapped to an IdP, or the mapping is incorrect.

Solution:

1. Verify the Domain Name in the IdP configuration matches the user's email domain exactly
2. Ensure there are no typos (e.g., gmail.com vs gmal.com)
3. Check that the IdP is active and properly configured

Gathering Diagnostic Information

When contacting support, please provide:

1. The exact error message displayed
2. The user's email address (domain portion only for privacy)
3. The configured Domain Name, Issuer Name, and Endpoint Address
4. Timestamp of the failed login attempt
5. Any relevant logs from your Identity Provider

Security Best Practices

Certificate Management

• Always upload a certificate: Certificate validation is required for production environments to prevent assertion tampering
• Monitor certificate expiration: IdP certificates typically expire every 1–3 years; schedule renewals before expiration
• Update certificates promptly: When your IdP rotates certificates, update QuikData immediately to avoid authentication outages

Access Control

• Pre-provision users carefully: Since users must exist before SSO login, establish clear provisioning procedures
• Regular access reviews: Periodically audit user accounts and IdP assignments
• Remove access promptly: When employees leave, disable their QuikData accounts

Network Security

• Use HTTPS: Ensure all endpoints use TLS encryption
• Firewall rules: Restrict access to SAML endpoints as appropriate for your environment

Frequently Asked Questions

Q: Can users log in with both SSO and username/password?

A: Users whose email domain is mapped to an IdP will be directed to SSO. Users can still use username/password if they access QuikData directly and their account has a password set, but this behavior depends on your site configuration.

Q: What happens if our IdP is unavailable?

A: Users will not be able to authenticate via SSO. Consider maintaining emergency administrator accounts with password authentication for system access during IdP outages.

Q: Can we use multiple IdPs for the same email domain?

A: No, each email domain can only be mapped to one Identity Provider. If you need to split users from the same domain across multiple IdPs, consider using sub-domains or aliases.

Q: How do I test SSO without affecting existing users?

A: Create a test user with an email address in the domain you're configuring. Configure the IdP mapping, then attempt to log in as the test user from your IdP.