Skip to main content
Generic SAML 2.0 works with any SAML-compliant Identity Provider — Okta, Microsoft Entra ID, ADFS, OneLogin, JumpCloud, PingIdentity, Shibboleth, and others. This guide covers what you fill in on the firmly Connect side. For provider-specific application setup steps (creating the SAML application, configuring assertions, mapping attributes), refer to your IdP’s own integration documentation.

​
Prerequisites

Before you start, make sure you have:
  • At least one verified domain in firmly Connect — see Verify a Domain.
  • A SAML 2.0 application registered in your IdP that signs assertions and accepts the SP’s Audience / Entity ID and Assertion Consumer Service URL.
  • From your IdP, either:
    • A metadata XML file describing the IdP, or
    • The three values manually: Entity ID / Issuer, SSO URL, and the X.509 signing certificate in PEM format.

​
firmly’s Service Provider details

The IdP configuration form displays three Service Provider (SP) values that you provide to your IdP. Copy them from the firmly Connect Dashboard rather than guessing — they are deployment-specific. SP Entity ID, ACS URL, and SP Metadata download panel

​
Add a SAML Identity Provider

1

Open Settings → Single Sign-On

Navigate to the Single Sign-On page in your firmly Connect Dashboard settings.
2

Click Add Identity Provider

The IdP picker dialog opens with all available protocols.
3

Select SAML 2.0

Click the SAML 2.0 tile to open the configuration form.
4

Provide IdP configuration

Either upload your IdP’s metadata XML for one-click setup, or fill in the three required fields manually. See Field reference below.
5

Click Save

The IdP is created in disabled state. You can now test it, bind it to verified domains, and enable it.
IdP picker with SAML tile

​
Fast path: upload IdP metadata XML

Most modern IdPs offer a downloadable metadata XML file describing the SAML endpoints and signing certificate.
  1. Download the metadata XML from your IdP.
  2. On the firmly SAML form, click the IdP Metadata XML (optional) upload control and select the file.
  3. firmly parses the file in your browser and auto-fills IdP Entity ID, SSO URL, and X.509 Certificate.
  4. Review the auto-filled values, edit anything if needed, and click Save.
The metadata XML itself is not stored — only the three extracted fields are persisted.

​
Field reference

SAML Fields
SAML signing certificates expire. Track the expiry date of the certificate you upload here, and update the X.509 Certificate field with a fresh certificate before the old one expires — once the certificate expires, every SAML sign-in for this IdP will fail until you update it.

​
NameID and user matching

firmly Connect uses the email returned by your IdP to look up the user. Configure your IdP to:
  • Send a NameID that is either the user’s email address (with a NameID format such as urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress) or any stable user identifier — firmly does not parse NameID for matching.
  • Include an email attribute in the SAML assertion. By default firmly looks at common email attribute names; if your IdP uses a non-standard name, set the Email Attribute field to that exact name.
The email’s domain portion must match a verified domain that is bound to this IdP. Sign-in for users whose email domain is not bound to this IdP will be rejected.

​
Bind the IdP to verified domains

The IdP configuration form includes an Authorized Domains section listing every domain you have verified. Each verified domain appears as a toggle.
  • Turn on the toggle for each domain you want this IdP to handle.
  • A single IdP can be bound to multiple domains.
  • A single domain can be bound to multiple IdPs (users will be presented with a choice at sign-in).
  • At least one domain must be bound before the IdP can be enabled.

​
Enable the IdP

The Enabled toggle at the top of the form becomes available once:
  • All required fields are filled and pass validation (including a well-formed PEM certificate), and
  • At least one verified domain is bound under Authorized Domains.
Toggle Enabled on to make the IdP usable for sign-in. A disabled IdP keeps all its configuration but cannot complete authentication for any user.

​
Test the connection

The Test Connection button appears on the IdP form in edit mode (after the initial save), provided there are no unsaved changes and all required fields are filled. Clicking Test Connection performs a real SAML round trip against your IdP:
  1. firmly redirects you to your IdP’s SSO URL with a SAML AuthnRequest.
  2. You authenticate with a real account at your IdP.
  3. Your IdP posts a signed SAML response back to firmly’s ACS URL.
  4. firmly verifies the response signature against the configured X.509 certificate, validates the audience matches the configured SP Entity ID, and extracts the email attribute.
On success, the form displays the extracted attributes. On failure, it displays a formatted error pointing to where the round trip broke down (for example, signature verification failure, audience mismatch, missing email attribute).
Always run Test Connection successfully before enabling the IdP for a domain that you plan to enforce SSO on. A misconfigured IdP combined with enforcement will lock users out of the dashboard until the configuration is fixed.
Test Connection button and success result

​
Update the certificate

When your IdP rotates the SAML signing certificate (typically annually):
  1. Obtain the new certificate from your IdP — either as a fresh metadata XML, or as a PEM-formatted certificate.
  2. Open the IdP configuration in firmly Connect.
  3. Either re-upload the new metadata XML (which refreshes all three fields), or paste the new PEM into X.509 Certificate directly.
  4. Click Save, then run Test Connection to confirm the new certificate works.
There is no separate “rotate” workflow — updating the field and saving is the rotation.

​
Disable or delete the IdP

  • Disable — turn the Enabled toggle off on the form. The configuration is preserved, the IdP is removed from sign-in, and any domain enforcement that depended solely on this IdP becomes unavailable.
  • Delete — from the IdP row’s actions menu on the SSO page, choose Delete. This is a hard delete, recorded in the audit log, and will unbind the IdP from any domains that referenced it.

​
Troubleshooting

The X.509 certificate stored in firmly does not match the certificate your IdP signed the response with. Re-download the current certificate (or metadata XML) from your IdP and update the X.509 Certificate field. Make sure the PEM is pasted with the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines intact and no extra whitespace.

​
Next steps

Verify a Domain

Add and verify the domains you want this IdP to handle, and enable enforcement when you’re ready.

SSO Overview

Recap the full setup flow and per-domain enforcement model.