Documentation Index

Fetch the complete documentation index at: https://docs.unqork.io/llms.txt

Use this file to discover all available pages before exploring further.

Using Certificates With SAML Assertions

  • Updated on Jul 13, 2026
  • Published on Jul 7, 2026
  • 15 minute(s) read
Prev Next

This guide walks you through creating and managing SAML certificates for SSO configurations in Unqork. SAML certificates validate the identity of the identity provider (IdP) by verifying the digital signature on SAML assertions. By uploading certificates to Unqork's Certificate Management system, you can reference them by ID across multiple SSO configurations, simplifying certificate rotation and management for multi-environment deployments.

Prerequisites

Before you begin, ensure you have:

In Unqork:

From Your Identity Provider:

  • The X.509 certificate used to sign SAML assertions.
  • Certificate in PFX or PKCS12 format with private key (if available).
  • (Optional) Certificate passphrase (if the certificate file is password-protected).

Knowledge:

  • Basic understanding of SAML 2.0 authentication flow.
  • Awareness of your Identity Provider's certificate format and location.

Understanding SAML Certificate Formats

SAML Identity Providers sign SAML assertions using X.509 certificates to prove their authenticity. Unqork validates these signatures by verifying the certificate against the one you provide. Understanding the certificate format is important for successful configuration.

Supported Certificate Formats

Unqork's Certificate Management system supports the following formats:

PFX / PKCS12 Format:

  • Binary format containing the certificate and private key.
  • Typically has file extensions: .pfx, .p12.
  • May be password-protected (requires passphrase).
  • Used for both signature validation and signing requests.

Base64-encoded pem Format:

  • Text format with -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- headers.
  • Typically has file extensions: .pem, .crt, .cer.
  • Does not include private key.
  • Used only for signature validation (most common for SAML).

When to Use Certificate Management:

Use Unqork's Certificate Management when:

  • You manage multiple Unqork environments (development, staging, production).
  • You need to rotate certificates across multiple SSO configurations.
  • You want centralized certificate expiration tracking.
  • You use the same IdP certificate for multiple SSO configurations.

When to Inline Certificates:

Inline the certificate directly in the SSO configuration when:

  • You have a single SSO configuration.
  • You need a quick setup for testing.
  • Certificate rotation is infrequent.

Creating a SAML Certificate

Step 1: Navigate to Certificate Management

Navigate to Administration > Integration > Certificate Management in the Unqork IDE.

  1. Click Add Certificate.

The certificate form displays with fields for certificate details.

Step 2: Configure Certificate Details

Certificate Title:

  • Enter a unique, descriptive name (for example, Okta-Production-2026).
  • Name must contain only alphanumeric characters and hyphens.
  • Spaces are automatically replaced with hyphens.
  • Recommendation: Include the IdP name, environment, and year for easy identification.

Certificate Type:

  • Select SAML.
  • This indicates the certificate is used for SAML SSO signature validation.

Step 3: Upload the Certificate

Certificate:

  • Paste the hex-encoded PFX/PKCS12 certificate content, or.
  • Upload the certificate file using the file selector.

For PEM/Base64 Certificates: If your IdP provides a PEM-formatted certificate (with -----BEGIN CERTIFICATE----- headers):

  1. Copy the entire certificate including the headers.
  2. Paste directly into the Certificate field.
  3. Unqork accepts both PEM and PFX formats.

For PFX/PKCS12 Certificates: If your IdP provides a binary PFX or PKCS12 file:

  1. Open the file in a text editor or certificate tool.
  2. Convert to hex encoding if needed.
  3. Paste the hex-encoded content, or upload the file directly.

PFX Passphrase (Optional):

  • Enter the passphrase if the certificate file is password-protected.
  • Leave blank if the certificate has no passphrase.
  • Note: Most SAML certificates for signature validation do not require a passphrase.

Services (Optional):

  • Leave blank for SAML certificates.
  • This field is used only for mTLS (mutual TLS) configurations with API services.

Step 4: Save the Certificate

  1. Review all fields.
  2. Click Save.
  3. Unqork validates and stores the certificate.
  4. The Certificate Management page displays with your new certificate listed.

After saving, note the certificate's:

  • Name: Used to identify the certificate in the list.
  • Issue Date: When the certificate was created.
  • Expiration Date: When the certificate expires.

Important: Set a reminder to rotate the certificate before the expiration date.

Adding a SAML Certificate to a New SSO Configuration

When creating a new SAML SSO configuration, you can reference a managed certificate instead of pasting the certificate inline.

Step 1: Create a New SSO Configuration

Navigate to Administration > Environment > Single Sign-On (SSO) in the Unqork IDE.

  1. Click Add SSO Configuration.
  2. Select Express or Designer depending on your use case.
  3. Select SAML as the protocol.

Step 2: Configure Basic Information

Complete the basic configuration fields:

  • SSO Name: Enter a unique name for the configuration.
  • Default Role: Select the appropriate role for authenticated users.
  • (Express only) Default Groups: Select groups to assign (optional).

Step 3: Configure SAML Protocol Settings

IdP Metadata XML:

  • Upload the metadata XML from your Identity Provider, or.
  • Manually configure Entry Point, Identifier Format, and other fields.

Certificate:

Instead of pasting the certificate content, reference the managed certificate:

  1. Leave the Certificate field blank.
  2. Scroll to the Certificate ID field (displays below the Certificate field).
  3. Click the Certificate ID drop-down.
  4. Select the certificate you created in Certificate Management (for example, Okta-Production-2026).

The certificate is now referenced by ID. Unqork will use the managed certificate to validate SAML assertions.

Note: If you provide both a Certificate (inline) and a Certificate ID, the Certificate ID takes precedence.

Step 4: Complete the Configuration

  1. Configure Attribute Mappings to map IdP claims to Unqork user attributes.
  2. Configure Advanced Settings as needed.
  3. Click Save Changes.

The SSO configuration now references the managed certificate. Future certificate rotations can be performed by updating the certificate in Certificate Management without editing the SSO configuration.

Adding a SAML Certificate to an Existing SSO Configuration

If you have an existing SAML SSO configuration with an inline certificate, you can replace it with a managed certificate reference.

Step 1: Create the Certificate in Certificate Management

Follow the steps in the "Creating a SAML Certificate" section to upload your certificate to Certificate Management.

Step 2: Edit the SSO Configuration

Navigate to Administration > Environment > Single Sign-On (SSO) in the Unqork IDE.

  1. Locate your SSO configuration.
  2. Click the three-dot menu for the configuration.
  3. Select Edit.

Step 3: Replace Inline Certificate With Certificate ID

Remove the inline certificate:

  1. Scroll to the Certificate field.
  2. Clear the certificate content (delete all text).

Reference the managed certificate:

  1. Scroll to the Certificate ID field.
  2. Click the Certificate ID drop-down.
  3. Select the certificate you created in Certificate Management.

Step 4: Save and Verify

  1. Review all settings to ensure no other changes occurred.
  2. Click Save Changes.
  3. Unqork updates the SSO configuration to reference the managed certificate.

Important: Test authentication immediately after saving to verify the certificate reference works correctly.

Testing Your Configuration

After adding a certificate to an SSO configuration, test authentication to verify the certificate validates SAML assertions correctly.

Step 1: Access the SSO Preview

Navigate to Administration > Environment > Single Sign-On (SSO) in the Unqork IDE.

  1. Locate your SSO configuration.
  2. Click the three-dot menu for the configuration.
  3. Select Preview.

Doing so opens the Identity Provider login page in a new browser tab.

Step 2: Authenticate with a Test User

  1. Enter credentials for a test user assigned to the application in your IdP.
  2. Complete any multi-factor authentication challenges.
  3. The IdP authenticates the user and sends a SAML assertion to Unqork.

Step 3: Verify Successful Authentication

After successful authentication:

  1. The IdP sends a signed SAML assertion to Unqork.
  2. Unqork retrieves the certificate from Certificate Management by ID.
  3. Unqork validates the SAML assertion signature using the certificate.
  4. If valid, Unqork authenticates the user.

If authentication succeeds:

  • The Unqork interface loads (Designer or Express, depending on configuration).
  • The certificate is correctly configured and validating signatures.

If authentication fails:

  • Review the error message (if displayed).
  • Check the browser console for errors.
  • Proceed to the Troubleshooting section.

Step 4: Verify Certificate Usage

To confirm the SSO configuration is using the managed certificate:

Navigate to Administration > Environment > Single Sign-On (SSO) in the Unqork IDE.

  1. Click the three-dot menu for your configuration.
  2. Select Edit.
  3. Verify the Certificate ID field displays the selected certificate name.
  4. Verify the Certificate field is empty (no inline certificate).

Troubleshooting

Issue: "SAML assertion validation failed: Certificate verification failed"

Cause: The managed certificate does not match the certificate the IdP uses to sign assertions.

Solution:

  1. In your IdP, download the current signing certificate.
  2. Compare the certificate contents with the certificate in Certificate Management.
  3. If different, update the certificate in Certificate Management:
  4. Test authentication again (no need to edit the SSO configuration).

Issue: Certificate ID Dropdown is Empty

Cause: No SAML certificates exist in Certificate Management, or certificates are not type SAML.

Solution:

  1. Navigate to Administration > Integration > Certificate Management.
  2. Verify at least one certificate exists with Type set to SAML.
  3. If no SAML certificates exist, create one using the "Creating a SAML Certificate" steps.
  4. Return to the SSO configuration and select the certificate from the drop-down.

Issue: Authentication Works With Inline Certificate But Fails With Certificate ID

Cause: The managed certificate content differs from the inline certificate, or there is a delay in certificate retrieval.

Solution:

  1. Verify the certificate in Certificate Management matches the inline certificate exactly:

    • Compare certificate contents character-by-character.
    • Ensure headers (-----BEGIN CERTIFICATE-----) are included in both.

  2. Check the certificate expiration date in Certificate Management.

  3. If the certificate is expired, upload a new certificate and update the Certificate ID.

  4. Retry authentication.

Issue: "Certificate name must contain only alphanumeric characters and hyphens"

Cause: The certificate name contains invalid characters.

Solution:

  1. Edit the certificate name to remove special characters.
  2. Allowed characters: a-z, A-Z, 0-9, - (hyphen).
  3. Cannot start with a hyphen.
  4. Example valid names: Okta-2026, Entra-ID-Production, Auth0-Staging.

Issue: Certificate Expired Warning

Cause: The certificate in Certificate Management has passed its expiration date.

Solution:

  1. Obtain a new certificate from your Identity Provider.
  2. Navigate to Administration > Integration > Certificate Management.
  3. Click the three-dot menu for the expired certificate.
  4. Select Edit.
  5. Replace the certificate content with the new certificate.
  6. Click Save.
  7. Unqork updates the certificate and all SSO configurations referencing it automatically use the new certificate.
  8. Test authentication to verify the new certificate works.

Issue: IdP Provides Certificate in DER Format

Cause: Some IdPs provide certificates in binary DER format instead of PEM or PFX.

Solution:

  1. Convert the DER certificate to PEM format using OpenSSL: 
    openssl x509 -inform der -in certificate.cer -out certificate.pem
  2. Open the certificate.pem file in a text editor.
  3. Copy the contents (including -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----).
  4. Paste into the Certificate Management Certificate field.
  5. Save the certificate.

Best Practices

Use Descriptive Certificate Names

Name certificates to identify the IdP, environment, and year:

  • Good: Okta-Production-2026, Entra-ID-Staging-2026, Auth0-Dev-2025.
  • Bad: Certificate1, cert, test.

Descriptive names make it easier to identify which certificate to rotate when expiration approaches.

Set Expiration Reminders

SAML certificates expire after a period (typically 1-3 years). Set calendar reminders to rotate certificates before expiration:

  1. Note the Expiration Date displayed in Certificate Management.
  2. Set a reminder 30 days before expiration.
  3. Obtain a new certificate from your IdP.
  4. Update the certificate in Certificate Management.
  5. Test authentication to verify the new certificate works.

Advantage of Managed Certificates: Updating a managed certificate automatically updates all SSO configurations that reference it. You don't need to edit each SSO configuration individually.

Rotate Certificates in Certificate Management

When rotating a certificate:

  1. Edit the existing certificate in Certificate Management.
  2. Replace the certificate content with the new certificate.
  3. Keep the same name and ID.
  4. Click Save.

All SSO configurations referencing the certificate by ID will automatically use the new certificate. This is faster and less error-prone than editing multiple SSO configurations.

Use Separate Certificates for Each Environment

If you manage multiple Unqork environments (development, staging, production), use separate certificates for each:

  • Create separate IdP applications for each environment.
  • Upload each environment's certificate to Certificate Management with environment-specific names.
  • Reference the appropriate certificate in each environment's SSO configuration.

This prevents a certificate rotation in production from affecting development or staging environments.

Verify Certificate Format Before Upload

Before uploading a certificate to Certificate Management, verify it is in a supported format:

  • Open the certificate file in a text editor.
  • PEM certificates display readable text with -----BEGIN CERTIFICATE----- headers.
  • PFX/PKCS12 certificates display binary content (unreadable characters).
  • DER certificates display binary content and need conversion to PEM.

If unsure, use OpenSSL to inspect the certificate:

openssl x509 -in certificate.pem -text -noout

Document Certificate Sources

Maintain documentation that maps each certificate to its source:

  • Certificate name in Unqork Certificate Management.
  • IdP application name.
  • Where to download the certificate in the IdP.
  • Contact for certificate renewal.

This documentation helps team members rotate certificates when you are unavailable.

Test After Every Certificate Update

After updating a certificate in Certificate Management:

  1. Test authentication for each SSO configuration referencing the certificate.
  2. Verify users can authenticate successfully.
  3. Check for certificate validation errors in browser console.

This catches configuration issues before they affect end-users.

Security Considerations

Protect Certificate Passphrases

If a certificate requires a passphrase:

  • Store the passphrase securely (use a password manager).
  • Do not share the passphrase in plain text (email, chat, documentation).
  • Rotate passphrases regularly if the IdP supports it.

Limit Access to Certificate Management

Only administrators with SSO configuration responsibilities should have access to Certificate Management. Use Unqork's role-based access control to restrict access.

Monitor Certificate Expiration

Set up monitoring or alerts for certificate expiration:

  1. Review certificates in Certificate Management monthly.
  2. Note certificates expiring in the next 60 days.
  3. Coordinate with your IdP administrator to obtain renewal certificates.

Use Strong Certificates

Ensure certificates from your IdP meet security standards:

  • Minimum 2048-bit RSA key length (4096-bit recommended).
  • SHA-256 or stronger signature algorithm.
  • Valid certificate chain (not self-signed unless for testing).

Audit Certificate Changes

Maintain an audit log of certificate changes:

  • Who uploaded or edited the certificate.
  • When the change occurred.
  • Reason for the change (scheduled rotation, compromise, expiration).

This helps investigate authentication issues and maintain compliance.

Advanced Configuration

Using the Same Certificate for Multiple SSO Configurations

If multiple SSO configurations use the same IdP certificate (for example, Express and Designer SSO with the same IdP):

  1. Upload the certificate to Certificate Management once.
  2. Reference the certificate by ID in both SSO configurations.
  3. When rotating, update the certificate in Certificate Management.
  4. Both SSO configurations automatically use the new certificate.

This eliminates duplicate certificate management and reduces rotation errors.

Migrating From Inline Certificates to Managed Certificates

If you have multiple SSO configurations with inline certificates:

  1. Identify unique certificates across all SSO configurations.
  2. Upload each unique certificate to Certificate Management with a descriptive name.
  3. Edit each SSO configuration:
    • Clear the Certificate field.
    • Select the corresponding certificate from the Certificate ID drop-down.
    • Save changes.
  4. Test authentication for each configuration.
  5. Document which configurations reference which managed certificates.

Benefit: Future certificate rotations require updating only the managed certificates, not each SSO configuration individually.

Certificate Rotation Strategy for Zero-Downtime

To rotate a certificate with zero downtime:

  1. Obtain the new certificate from your IdP before the old certificate expires.
  2. In your IdP, configure both old and new certificates as valid (if supported).
  3. Test the new certificate in a staging environment:
    • Upload the new certificate to Certificate Management (staging).
    • Update staging SSO configurations to reference the new certificate.
    • Verify authentication works.
  4. Schedule the production rotation:
    • Upload the new certificate to Certificate Management (production).
    • Update production SSO configurations during a maintenance window.
    • Test authentication immediately after rotation.
  5. Monitor authentication logs for failures.
  6. After confirming the new certificate works, remove the old certificate from your IdP (if configured for dual certificate support).

Next Steps

After successfully configuring SAML certificates:

  1. Set expiration reminders: Add calendar reminders for certificate expiration dates.
  2. Document the configuration: Record certificate sources, IdP application names, and rotation procedures.
  3. Test all SSO configurations: Verify each SSO configuration referencing a managed certificate authenticates successfully.
  4. Plan rotation procedures: Establish a process for rotating certificates before expiration.
  5. Review security practices: Ensure certificates meet your organization's security standards.

Changelog

Date Change
2026-07-10 Initial publication.
Related articles

Copyright © 2025 Unqork