Skip to main content

Securing Coginiti with SAML Authentication

This guide walks you through configuring SAML 2.0 authentication for Coginiti Team and Enterprise using popular identity providers. SAML integration enables single sign-on (SSO) and centralized user management for your organization.

Overview​

SAML (Security Assertion Markup Language) authentication allows users to log into Coginiti using their existing corporate credentials from supported identity providers. This eliminates the need for separate Coginiti passwords and provides centralized access control with enhanced security features.

Supported Identity Providers​

Coginiti supports any SAML 2.0-compliant identity provider through standard metadata exchange, including:

  • Microsoft Azure Active Directory (Entra ID)
  • Okta
  • Google Workspace
  • Auth0
  • Ping Identity
  • ADFS (Active Directory Federation Services)
  • OneLogin
  • Custom SAML 2.0 providers

Prerequisites​

Before configuring SAML authentication, ensure you have:

Coginiti Requirements​

  • Admin access to your Coginiti Team or Enterprise instance
  • Coginiti hostname configured with HTTPS (required for SAML)
  • Valid SSL certificate installed and properly configured

Identity Provider Requirements​

  • Admin access to your identity provider (Okta, Azure AD, etc.)
  • Ability to create applications in your identity provider
HTTPS Required

SAML authentication requires HTTPS. Ensure your Coginiti instance is properly configured with a valid SSL certificate before proceeding.

Azure Active Directory (Entra ID) Configuration​

Step 1: Access Azure Portal​

  1. Log into the Azure Portal as an administrator
  2. Navigate to Microsoft Entra ID (formerly Azure Active Directory)

Step 2: Create Enterprise Application​

  1. Go to Enterprise applications → New application
  2. Click Create your own application
  3. Configure the application:
    • Name: Coginiti Team SAML (or your preferred name)
    • Application type: Integrate any other application you don't find in the gallery (Non-gallery)
  4. Click Create

Step 3: Configure Single Sign-On​

  1. Navigate to Single sign-on in the left sidebar

  2. Select SAML as the single sign-on method

  3. Configure the basic SAML configuration:

    Identifier (Entity ID):

    https://your-coginiti-hostname

    Reply URL (Assertion Consumer Service URL):

    https://your-coginiti-hostname/api/saml2/callback

    Sign on URL:

    https://your-coginiti-hostname/api/auth/login/saml2

    Logout URL:

    https://your-coginiti-hostname/api/saml2/callback?client_name=SAML2Client&logoutendpoint=true

Step 4: Configure Attributes and Claims​

  1. In the Attributes & Claims section, configure the required claims for Coginiti:

    • Unique User Identifier (Name ID): User's email address (Email format)
      • Expected value: johnsmith@company.com
      • Example source: user.userprincipalname
    • Username attribute: Map to appropriate user property
      • Expected value: johnsmith
      • Example source: ExtractMailPrefix() with user.mail
    • First name attribute: Map to user's first name property
      • Expected value: John
      • Example source: user.givenname
    • Last name attribute: Map to user's last name property
      • Expected value: Smith
      • Example source: user.surname
    • Group attribute: Map to user's groups (for group mapping)
      • Expected value: ["Admins", "Users"] or "Admins"
      • Example source: user.groups

Step 5: Download Metadata​

  1. In the SAML Certificates section, download the Federation Metadata XML
  2. Save this file - you'll upload it to Coginiti in the next section

Step 6: Upload Service Provider Certificate​

  1. In the SAML Certificates section, find the Verification certificates (optional) section
  2. Click Edit
  3. Check the Require verification certificates checkbox
  4. Upload the Coginiti certificate file (generated in Step 5: Save and Generate Certificate)
  5. Return to this step after completing the Coginiti Configuration to upload the certificate

Step 7: Assign Users​

  1. Go to Users and groups
  2. Click Add user/group
  3. Add users who should have access to Coginiti

Okta Configuration​

Step 1: Access Okta Admin Console​

  1. Log into your Okta account as an administrator
  2. Your Okta admin URL should resemble: https://{your-org}-admin.okta.com/

Step 2: Create SAML Application​

  1. Navigate to Applications → Applications
  2. Click Create App Integration
  3. Select the following options:
    • Sign-in method: SAML 2.0
  4. Click Next

Step 3: Configure Application Settings​

Fill in the application configuration:

General Settings:

  • App name: Coginiti Team (or your preferred name)
  • App logo: Upload Coginiti logo (optional)

SAML Settings:

  • Single sign-on URL: https://your-coginiti-hostname/api/saml2/callback
  • Audience URI (SP Entity ID): https://your-coginiti-hostname
  • Name ID format: EmailAddress
  1. Click Show Advanced Settings to access additional configuration options:
    • Allow application to initiate Single Logout: ✅ Enable this option first
    • SP Issuer: https://your-coginiti-hostname
    • Single Logout URL: https://your-coginiti-hostname/api/saml2/callback?client_name=SAML2Client&logoutendpoint=true
    • Signature Certificate: Upload the certificate file (you'll return to this step after generating the certificate in Step 5: Save and Generate Certificate)
    • Enable Signed Requests: ✅ Enable this option for enhanced security

Attribute Statements:

  • username: user.login
  • firstName: user.firstName
  • lastName: user.lastName

Group Attribute Statements (optional):

  • groups: .* with filter Matches regex
  1. Click Next and Finish
Name ID Format Requirement

Ensure the Name ID format is set to Email Address format (urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress) as this is enforced by Coginiti.

Step 4: Save Metadata​

  1. Navigate to the Sign On tab of your newly created application
  2. Find the Metadata URL in the SAML 2.0 section
  3. Copy the metadata URL (it will look like: https://your-org.okta.com/app/abc123/sso/saml/metadata)
  4. Open the metadata URL in your browser to view the XML content
  5. Save the XML content to a file (e.g., okta-metadata.xml) on your computer
  6. This metadata file will be uploaded to Coginiti in the next section

Step 5: Assign Users and Groups​

  1. Go to the Assignments tab
  2. Click Assign → Assign to People or Assign to Groups
  3. Add users who should have access to Coginiti

Coginiti Configuration​

Step 1: Access SAML Settings​

  1. Log into Coginiti Team or Enterprise as an administrator
  2. Navigate to Administration → SAML Configuration
  3. The SAML configuration will open in a modal dialog
Administrator Required

SAML configuration requires administrator privileges. Regular users cannot access SAML settings.

Step 2: Upload Identity Provider Metadata​

  1. In the Identity Provider Configuration section:
    • Identity Provider Metadata XML: Click Upload and select the metadata XML file downloaded from your identity provider
    • The system will automatically extract and populate:
      • IdP Entity ID (read-only)
      • Single Sign-On URL (read-only)
      • Single Logout URL (read-only)

Step 3: Configure Service Provider Settings​

Fill in the Service Provider configuration:

  • SP Entity ID: https://your-coginiti-hostname
  • SP Callback URL: https://your-coginiti-hostname/api/saml2/callback
  • Certificate Validity Period: 365 (optional - you can specify any number)
  • Time Unit: Days (optional - available options: Days, Months, Years)
Entity ID Matching

The SP Entity ID can be customized, but must match exactly the Entity ID (Identifier) configured in your identity provider.

Step 4: Configure User Provisioning​

Set up user provisioning and attribute mapping:

  • JIT User Provisioning: ✅ Enable (to automatically create users on first login)
  • Username Attribute: username (maps to the username attribute configured in your IdP)
  • First Name Attribute: firstName (maps to the first name attribute configured in your IdP)
  • Last Name Attribute: lastName (maps to the last name attribute configured in your IdP)
  • Group Attribute: groups (maps to the group attribute configured in your IdP for automatic group assignment)

Step 5: Save and Generate Certificate​

  1. Click Save to save the SAML configuration
  2. Click Generate Certificate to create a self-signed certificate for SAML signing
  3. Download the Service Provider Metadata and Certificate

Step 6: Upload Certificate to Identity Provider​

  1. Return to your identity provider configuration:
  2. Upload the downloaded certificate file to complete the SAML trust relationship
  3. Save the identity provider configuration

User Management​

Creating Users in Coginiti​

You can manage user creation in Coginiti using one of two approaches:

Option 1: Pre-create Users​

  1. Navigate to Users or User Management in Coginiti admin
  2. Create users with email addresses that match their identity provider accounts
  3. Users can be created without passwords when using SAML

Option 2: Just-in-Time (JIT) Provisioning​

Enable automatic user creation on first login:

  1. Enable JIT User Provisioning in SAML configuration
  2. Configure attribute mapping for user information
  3. Users will be created automatically on first successful SAML authentication
Email Conflict with Existing Users

If you have manually created users with the same email addresses as your SAML users, JIT provisioning will fail because email addresses must be unique. See the troubleshooting section for how to resolve this issue.

User Group Mapping​

Configure how identity provider groups map to Coginiti groups:

  1. Manual Assignment: Assign Coginiti groups manually after user creation
  2. Group Mapping: Configure the Group Attribute to automatically assign groups based on SAML group claims
  3. Automatic Sync: Groups are updated on each login when group attribute mapping is configured

Testing SAML Authentication​

Step 1: Test Configuration​

  1. Log out of Coginiti completely
  2. Navigate to your Coginiti login page
  3. You should see a "Login with SSO?" link

Step 2: Perform Login Test​

  1. Click the "Login with SSO?" link
  2. You should be redirected to your identity provider's login page
  3. Enter your identity provider credentials
  4. You should be redirected back to Coginiti and logged in

Step 3: Verify User Information​

  1. Check that your user profile shows correct information from the identity provider
  2. Verify you have appropriate groups assigned
  3. Test access to workspaces and resources

Step 4: Test Single Logout​

  1. Click logout in Coginiti
  2. Verify you are logged out of both Coginiti and your identity provider (if SLO is configured)
  3. Attempting to access Coginiti should redirect to the login page
Single Logout Limitations

Currently, only SP-initiated logout is supported. IdP-initiated logout (logging out from the identity provider to automatically log out of Coginiti) is not yet supported.

Troubleshooting​

Common Issues​

"Invalid SAML Response" Error​

Symptoms: Authentication fails with SAML response validation errors
Solutions:

  1. Check that clocks are synchronized between Coginiti and identity provider
  2. Verify the Entity ID matches exactly between IdP and Coginiti configuration
  3. Ensure the Assertion Consumer Service URL is configured correctly in both systems
  4. Check that the SAML response is signed and certificates are valid

"User Not Found" Error​

Symptoms: SAML authentication succeeds but user cannot access Coginiti
Solutions:

  1. Ensure user exists in Coginiti with matching email address
  2. Enable JIT User Provisioning if you want automatic user creation
  3. Check that the email is being sent correctly in the SAML NameID
  4. Verify the Username Attribute configuration matches your IdP's username attribute

"Invalid Metadata" Error​

Symptoms: Error uploading identity provider metadata XML
Solutions:

  1. Verify the metadata XML file is valid and well-formed
  2. Check that the metadata contains required elements (EntityDescriptor, SingleSignOnService)
  3. Ensure the metadata is downloaded directly from your identity provider
  4. Try downloading fresh metadata from your IdP

SSL/Certificate Issues​

Symptoms: SAML redirects fail or certificate validation errors
Solutions:

  1. Ensure Coginiti is accessible via HTTPS with valid certificate
  2. Check certificate expiration and CA trust chain
  3. Test certificate validity: openssl s_client -connect your-domain:443

Email Conflict with Existing Manual Users​

Symptoms: Error message during SAML login:

User with given email already registered: john.doe@example.com 
Please contact your system administrator.

Cause: JIT provisioning is enabled but a user with the same email already exists in the database as a manually created (non-external) user.

Solution:

  1. Delete the existing manual user from Coginiti user management
  2. Ask the user to attempt SAML login again
  3. The user will be created automatically via JIT but will be disabled
  4. Manually enable the newly created external user in user management

"Attribute Mapping Issues"​

Symptoms: User profile information is missing or incorrect
Solutions:

  1. Check attribute mapping configuration in both Coginiti and identity provider
  2. Verify attribute names match exactly (case-sensitive)
  3. Test that attributes are being sent in SAML assertion
  4. Review IdP attribute mapping and release policies

Debugging Steps​

Examine SAML Response​

For detailed debugging, examine the SAML assertion:

  1. Use browser developer tools to capture SAML response
  2. Decode base64 SAML assertion to view XML content
  3. Verify required attributes are present and correctly named
  4. Check signature validation and certificate chain

Check Application Logs​

Review Coginiti application logs for SAML-related errors:

  • Authentication request logs
  • SAML response validation logs
  • User provisioning logs
  • Attribute mapping logs
  • Certificate validation logs

Validate Configuration​

  1. Test SAML endpoints are accessible:

    curl -I https://your-coginiti-hostname/api/saml2/callback

  2. Verify metadata is properly formatted:

    curl -X POST https://your-coginiti-hostname/saml2/metadata

  3. Check certificate validity:

    curl -X POST https://your-coginiti-hostname/saml2/certificate

Security Best Practices​

Certificate Management​

  • Secure certificate storage: Coginiti automatically generates and stores certificates securely
  • Regular rotation: Plan to regenerate certificates before expiration
  • Strong encryption: Uses RSA 2048-bit certificates with SHA256WithRSA signing

Network Security​

  • Use HTTPS for all SAML endpoints and redirects
  • Validate SSL certificates and certificate chains

User Access Control​

  • Review user assignments regularly in identity provider
  • Implement least privilege access principles
  • Monitor authentication logs for suspicious activity
  • Regular access reviews to ensure only authorized users have access

SAML Security​

  • Signed assertions: Ensure your identity provider signs SAML assertions
  • Certificate validation: Verify IdP certificates are valid and trusted
  • Time-based validation: SAML assertions include timestamp validation to prevent replay attacks

Support and Resources​

Getting Help​

For SAML configuration assistance:

  • Coginiti Support: support@coginiti.co
  • Identity Provider Documentation: Consult your IdP's official SAML docs
  • Community Forums: Stack Overflow with appropriate tags

Additional Resources​

Summary​

You have successfully configured SAML authentication for Coginiti! Key achievements:

✅ Identity Provider: Configured SAML application in your IdP with proper settings
✅ Coginiti Integration: Configured SAML settings with correct metadata and attributes
✅ User Management: Set up user accounts and JIT provisioning
✅ Security: Implemented secure authentication flow with signed assertions
✅ Testing: Verified login and logout flows work correctly

Your users can now authenticate to Coginiti using their existing corporate credentials, providing a seamless single sign-on experience with enhanced security through SAML 2.0 assertions and centralized access control.