Add a SAML Provider
Use the Add Provider action to connect a SAML 2.0 identity provider, so users can sign in to Qualytics with their corporate identity. The configuration fields can be filled in automatically from your identity provider's metadata URL or metadata file.
Permissions
Only users with the Admin role can manage sign-in providers. See the Permissions page for details.
Field reference
The Add Provider form shows the sections below when SAML 2.0 is selected. Importing your identity provider's metadata, by file or by URL, fills in the Identity Provider fields for you.
General
Identifies the provider to the people who sign in with it, and shows the two values your identity provider needs.
| Field | Required | Type | Description |
|---|---|---|---|
| Display Name | Text | The name shown to users on the sign-in page. | |
| Identity provider values | Text | Read-only. The ACS URL and SP Entity ID to register in your identity provider's SAML application, each with a copy button. See Register Qualytics in Your IdP below. |
Identity Provider
Where Qualytics sends users to authenticate, and how it verifies the assertion that comes back.
| Field | Required | Type | Description |
|---|---|---|---|
| Import from metadata XML file | File | Fills in the fields below from the metadata file downloaded from your identity provider. | |
| IdP Metadata URL | Text | Your identity provider's metadata endpoint. Providing it fills in the fields below automatically, with the same result as the file import. | |
| IdP Entity ID | Text | Your identity provider's entity identifier. Already filled in when you provide the IdP Metadata URL or import the metadata XML file. | |
| SSO URL | Text | The identity provider's single sign-on URL. | |
| SLO URL | Text | The identity provider's single logout URL. | |
| X.509 Certificate | Text | The identity provider's signing certificate. Required when creating the provider. Stored securely and never displayed again; on an existing provider, paste it again only to replace it. | |
| Name ID Format | Option | The format of the subject identifier your identity provider sends: Unspecified, Email Address (default), Persistent, or Transient. See Choosing a Name ID Format below. | |
| Signed assertions | Checkbox | Requires the identity provider to cryptographically sign SAML assertions. On by default. Turning it off asks for an explicit confirmation, because unsigned responses can be tampered with. | |
| Session Duration | Number | How long a Qualytics session stays valid after sign-in, in minutes. Defaults to 480, which is 8 hours. Any whole number greater than 0 is accepted, but the deployment caps every session at its maximum session lifetime, 24 hours by default, so a longer value has no further effect. See Sessions. |
Choosing a Name ID Format
The Name ID is the subject identifier your identity provider puts in the assertion, and Qualytics reads it twice: as the identity it links the Qualytics account to, and as a fallback for the email address when the assertion carries no email attribute. That is why the choice matters beyond the label.
| Option | What your identity provider sends | What it means here |
|---|---|---|
| Email Address | The person's email address | The default, and the option that needs the least setup. The same value serves as both the identity and the email, so sign-in works even with no attribute mapping configured. |
| Unspecified | Whatever the identity provider decides, commonly an email address or a username | Fine when that value is an email address, or when the provider also sends an email attribute. Otherwise sign-in is refused, because Qualytics ends up with no valid email address for the account. |
| Persistent | A stable opaque identifier, the same at every sign-in and unique to this person and this provider | A dependable identity anchor, but it is not an email address, so the provider has to send the email as an attribute. |
| Transient | A throwaway identifier that changes at every sign-in | It cannot identify anyone across sessions and is not an email address, so the attribute mapping has to supply both subject_id and email. Prefer one of the options above unless your identity provider requires this one. |
When the format is not Email Address, confirm your identity provider sends an email attribute, and use Attribute Mapping below if it names that attribute differently from the default.
Note
Importing your identity provider's metadata fills this field in for you. A wand icon next to the field marks every value that came from the import.
Service Provider Metadata
Only needed when your identity provider expects a specific service provider identifier.
| Field | Required | Type | Description |
|---|---|---|---|
| SP Entity ID | Text | Overrides the service provider entity ID advertised to the identity provider. Leave empty to use the metadata URL shown in the form. |
Attribute Mapping
Only needed when your identity provider names its attributes differently from the defaults.
| Field | Required | Type | Description |
|---|---|---|---|
| SAML Attribute Mapping | Mapping | Maps Qualytics user fields to the SAML attribute names your identity provider emits. The supported fields are subject_id, email, and name. Leave the mapping empty to use the provider defaults. |
Access Restriction
Who is allowed to sign in through this provider, and what their group membership grants them.
| Field | Required | Type | Description |
|---|---|---|---|
| Groups Claim | Text | The SAML attribute name that contains the user's group memberships. Without it no groups are read, and the groups that are read appear in the Identity Provider Groups field of the Edit User dialog. | |
| Allowed Groups | List | Only users in these groups can sign in. Leave empty to allow all users. | |
| Allowed Email Domains | List | Only users with an email in these domains can sign in. Leave empty to allow all domains. | |
| Sync groups to Teams | Checkbox | Adds users to Teams whose name matches a group this provider presents. Add-only: membership is never revoked. Off by default, and unavailable until Groups Claim holds a value. See Just-in-Time Provisioning and Group Sync. |
Provisioning and Linking
What happens when someone signs in with an identity Qualytics has not seen before.
| Field | Required | Type | Description |
|---|---|---|---|
| Automatic user provisioning | Checkbox | Creates a Qualytics user after a successful sign-in when the identity is not linked to an account yet. On by default. | |
| Cross-provider account linking | Checkbox | Allows an identity from this provider to request linking to an existing account with the same email. On by default. | |
| Require administrator approval | Checkbox | Keeps newly proposed cross-provider links pending until an administrator approves them in Link approvals. Off by default, so links are created without review unless you turn it on. |
Advanced SAML Security
| Field | Required | Type | Description |
|---|---|---|---|
| Allow unsolicited SAML responses | Checkbox | Accepts sign-ins started from the identity provider's own portal, without a matching Qualytics authentication request. Off by default, and turning it on asks for an explicit confirmation. Enable it only when your identity provider is trusted and requires this flow. |
Info
For how provisioning, linking, and restrictions behave at sign-in, see How It Works.
Register Qualytics in Your IdP
Setting up SAML is an exchange in both directions. The fields above bring your identity provider's values into Qualytics; the two values below go the other way, into the SAML application you create at your identity provider. Both appear in the provider form with a copy button, so you can hand them over while you fill the form in.
| Value | Description |
|---|---|
| Assertion Consumer Service (ACS) URL | The endpoint where your identity provider sends the SAML assertion. |
| SP Entity ID | Qualytics's service provider identifier. |
Once the provider is saved, you can pass the same information as a file or a link instead of copying the two values by hand: click Download SP Metadata for a metadata file, or Copy Metadata URL for the metadata endpoint.
Steps
Step 1: Open Settings from the left sidebar, click the Access tab, and open the Providers tab.
Step 2: Click the Add Provider button, or select Provider from the Add menu in the top right corner.
Step 3: The Add Provider modal appears.
Step 4: Select SAML 2.0 as the provider type.
Step 5: Fill in the provider fields (see Field reference above). To fill the Identity Provider fields in automatically, turn on Import from metadata XML file and upload the file your identity provider gave you, or paste its IdP Metadata URL.
Step 6: Click the Test button and review the results.
Step 7: Click the Create button. A success message appears and the provider is listed in the Providers tab.
Step 8: Register Qualytics at your identity provider using the ACS URL and SP Entity ID from the provider form, or hand over the file from Download SP Metadata. See Register Qualytics in Your IdP above.