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.
firmly fieldWhere to use it in your IdP
SP Entity IDEnter as the Audience / Entity ID / SP Identifier in your IdP application. Read-only on the firmly form, with a copy button.
ACS URLEnter as the Assertion Consumer Service (ACS) URL / Reply URL / Single Sign-On URL in your IdP application.
SP Metadata XMLClick Download SP Metadata to download an XML file. If your IdP supports importing SP metadata, upload this file instead of copying the SP Entity ID and ACS URL fields manually.
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

​
Field reference

FieldRequiredWhat to enter
IdP Metadata XMLNoOptional metadata XML file from your IdP. Auto-fills the three fields below. UI-only — the file itself is not stored.
IdP Entity IDYesThe unique identifier of your IdP, sometimes called Issuer. Example: http://www.okta.com/exk1234567890.
SSO URLYesYour IdP’s Single Sign-On endpoint — the URL firmly redirects users to in order to authenticate. Must use https://.
X.509 CertificateYesYour IdP’s public signing certificate in PEM format, including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines. firmly validates the PEM wrapper and base64 body, and uses this certificate to verify the signatures on SAML responses.
Email AttributeNoThe SAML attribute Name containing the user’s email address. Leave empty to try common defaults automatically. Set this if your IdP emits the email under a non-standard attribute (for example, the long urn:oid:0.9.2342.19200300.100.1.3 URN used by some directories).
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.