SAML provider

Route: /external-providers/saml/new (create) · /external-providers/saml/<id> (edit)

A SAML provider enables single sign-on through your identity provider (IdP). Users sign in from a button on the login page; ToBeAlert acts as the service provider (SP) and maps assertion attributes to user profiles, views, and roles.

See also: Overview · LDAP provider

Editor chrome

The full-page editor header shows a breadcrumb Auth Providers / provider name (with a SAML badge when editing an existing provider). Use Auth Providers to return to the list. Header actions include Current status and Create / Update configuration.

Configuration overview

The editor is a single page with grouped cards (not a stepped wizard). All sections are visible; attribute and group mappings unlock after the first save.

Area	Purpose
General settings	Connection name, login button label/icon, IdP metadata
Configuration URLs	ACS URL and Entity ID to register in the IdP; optional Test connection
Security settings	Signature and unsolicited-response options
Attribute mappings	Map IdP claims to Login, Name, Email, Groups
Role and view mappings	Map SAML group names to views and roles

LDAP comparison

The LDAP provider uses a four-step wizard where each step must pass a connection test before the next unlocks. SAML saves metadata first, then you register SP URLs in the IdP and optionally run Test connection.

Create a SAML provider

1. Open Access Control → External Providers (/external-providers).
2. Click Create auth provider → Configure SAML.
3. On General settings, enter Connection Name and optional login button branding.
4. Under Identity Provider Details, provide metadata using Enter URL or Upload XML, then click Fetch IdP metadata.
5. Click Create in the page header to save the provider and generate Entity ID.
6. Copy ACS URL and Entity ID from Configuration URLs into your IdP application settings.
7. Optional: click Test connection to complete an IdP login and populate attribute suggestions.
8. Configure Attribute mappings (at least Login and Name required to enable).
9. Optional: add Role and view mappings for SAML groups.
10. Click Update configuration, then enable the provider from Current status or the list toggle.

Entity ID

Entity ID appears after the first save. Before save, the field shows Save the provider first to get the Entity ID.

General settings

Field	Description
Connection Name	Internal label (for example Okta prod, Azure AD SSO)
Button Label	Login button text (placeholder: Continue with SSO)
Button Icon	Optional image (max 2 MB) shown beside the label on the login button

Login button branding

Button Label and Button Icon control how this provider appears on the sign-in page:

Control	Description
Button Label	Short text users click to start SSO (for example Continue with SSO or your IdP name)
Button Icon	Optional logo or icon (max 2 MB, image formats). Click Select icon image to upload; after upload the preview shows Icon ready to use. Click the preview or remove the icon to change or clear it

If you leave Button Label empty, the placeholder Continue with SSO is shown. If you omit Button Icon, the button shows label text only.

Identity provider setup

Identity Provider Details

Provide IdP metadata before the first Create.

Tab	Field / action	Description
Enter URL	IdP Metadata URL	HTTPS URL that returns the IdP SAML metadata document
Enter URL	Fetch IdP metadata	Load metadata from the URL
Upload XML	Upload XML	Select the IdP metadata file from disk
Upload XML	Fetch IdP metadata	Confirm the uploaded XML is ready

Configuration URLs

After save, register these values in your IdP:

Value	Description
ACS URL	Assertion Consumer Service endpoint ToBeAlert exposes to the IdP
Entity ID	SP entity identifier for this provider

Use the copy buttons beside each field.

Test connection

Test connection is in the Configuration URLs card. It opens the IdP login flow in a new window. When login succeeds, attribute names appear in mapping dropdowns and a Test successfully loaded tag is shown.

Testing is optional — if you lack an IdP test account, enter claim names manually from IdP documentation.

Enable requirements

You cannot enable a SAML provider until Login and Name attribute mappings are configured. The list toggle and Current status show an error if mappings are missing.

LDAP comparison

LDAP runs separate tests per wizard step (Try connection, Test User, Search Users). SAML uses a single optional Test connection after the provider is saved.

Attribute mappings

Map Identity Provider Attribute (left) to App Field (right):

App field	Purpose
Login	Required — unique user identifier
Name	Required — display name
Email	Optional email address
Groups	Optional groups or roles claim for group mapping

Click Add Mapping for additional rows. Dropdowns list attributes from the last successful Test connection; you can also type claim names manually.

Group and role mappings

Field	Description
SAML group name	Group name from the IdP (for example Domain Admins)
Assign views	Views granted to members of that group
Assign roles	Roles granted to members of that group

Click Add Group Mapping for more rules. Group mappings apply based on the Groups attribute mapping when users sign in through SAML.

LDAP comparison

LDAP group mappings apply after Sync Users. SAML applies mappings at sign-in when the Groups claim is present in the assertion.

Security settings

Setting	Description
Allow unsolicited	Allow IdP-initiated login without a prior AuthnRequest from ToBeAlert
Want assertions signed	Require signed SAML assertions from the IdP
Authn request signed	Sign AuthnRequest messages from ToBeAlert; IdP must trust the SP certificate
Want response signed	Require signed SAML response envelopes

Match these toggles to what your IdP supports and your security policy requires.

Not applicable to SAML-only readers

These toggles are SAML-specific. LDAP providers use SSL on the server connection step instead of assertion signing options.

Edit and enable

Control	Description
Update configuration	Saves changes (enabled when the form differs from last save)
Current status	Toggle active/inactive (requires login + name mappings to enable)
List Status toggle	Same enable/disable behavior from the provider table

To change IdP metadata after creation, update the URL or re-upload XML, then Fetch IdP metadata and Update configuration.

LDAP-only: Sync Users

Sync Users is available for LDAP providers only. SAML users are created or updated when they sign in through SSO.

Best practices

1. Register ACS URL and Entity ID in the IdP immediately after the first save — mismatched URLs are the most common SSO failure.
2. Customize login button branding so users recognize the SSO option on the sign-in page.
3. Start with Want assertions signed enabled unless the IdP documentation specifies otherwise.
4. Run Test connection when possible to avoid guesswork on claim names.
5. Use separate providers for production and staging IdP applications.
6. Keep local login enabled in Backend Config until SAML login is verified for multiple users.
7. Align security toggles with IdP metadata (signed assertions, signed responses, AuthnRequest signing).
8. Review role and view mappings with your IdP group naming before enabling for all users.