Documentation

Getting started

SAML 2.0 (Security Assertion Markup Language) ↗ is an XML-based data format used to exchange authentication and authorization data between a service provider (often abbreviated SP), such as Foundry, and an identity provider (IdP), such as Azure AD or Okta. The most common use case for SAML 2.0 is Single Sign-On (SSO) from a web browser.

Concepts

In the following section, authentication concepts common in Foundry are discussed.

SAML integration metadata

The SAML integration metadata, also called service provider metadata, is the information about Foundry that needs to be passed to the identity provider. This information includes:

Entity ID: A unique ID identifying Foundry for the identity provider, in a URN ↗ format urn:uuid:[$UUID].
Assertion Consumer Service (ACS) URL: The Foundry endpoint that accepts SAML response messages for the purpose of establishing a session based on an assertion.
Single Logout URL: The Foundry endpoint that accepts SAML single logout requests from the identity provider.
Certificate: Used for signing the SAML messages sent to the identity provider.

This information is encoded as an auto-generated XML file that can be copied in whole to be uploaded to the identity provider by the customer. In addition, Control Panel extracts the information to separate fields that can be copied individually.

Identity provider metadata

Identity provider metadata is the information about the identity provider that needs to be passed to Foundry. This information includes the identity provider’s entity ID, Single Sign-On (SSO) and Single Logout URLs, and a certificate.

Identity provider metadata is encoded as an XML file that should be copied from the identity provider and uploaded in Control Panel.

Email domains

Email domains are used to decide which identity provider integrations are presented to users as a login option. When a user enters their email or username in the login screen, email domains of all the configured identity provider integrations will be tested and only matching identity provider integrations will be shown.

Email domains can be regular expressions, though they are usually of the simple form @example.com, which will be automatically converted into .*@example\.com. Use .* if the identity provider integration should be shown to all users.

"Allowed email domains" window that enables you to define the email domains associated with an authentication provider. The "Restrict email domains" option is selected and several example domains, both of the simple form and as regular expressions, have been allowed.

Note that both the simple form of email domains (@example.com) and regular expressions (.*@example\.com) are case-sensitive by default. Email domains can be made case-insensitive by adding (?i) to the start of the regular expression, so a case-insensitive version of the simple form @example.com would be (?i).*@example\.com or (?i)@example\.com.

Supported hosts

Supported hosts are used to:

Construct the ACS & Single Logout URLs in the SAML integration metadata.
Ensure the integration is only presented to users that log in using these hosts.

You can choose from the hosts configured for your enrollment.

Map attributes

Map SAML responses to Foundry to ensure sufficient and correct user attributes are being passed through.

User attributes

After a user authenticates with the identity provider during the SAML login process, a SAML response is sent to Foundry. This SAML response contains the user’s attributes (also called "claims"), such as name, email, and any available additional information. These attributes are sent in a map of attribute key to value (e.g. email → user@example.com) or values.

For Foundry to have the correct values for user attributes, you must map identity provider attributes (or "claims") to matching Foundry attributes. Foundry requires the following mappings:

ID: Set to NameID by default. This value should always be present on SAML assertions and has a static unique value.
Username: Set to NameID by default, but can be changed to a different human-readable attribute (e.g., http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name for Azure AD).
Email: Should be mapped to the email attribute (e.g., http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress for Azure AD).
First name: Should be mapped to the first name attribute (e.g., http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname for Azure AD).
Last name: Should be mapped to the last name attribute (e.g., http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname for Azure AD).

View the reference mappings for Azure AD and Okta.

Additional mappings can be set to create more user attributes in Foundry by clicking Add attribute mapping. Input the attribute name in Foundry in the left field, and the attribute name in the identity provider on the right field.

For each mapping, there is a toggle that lets you choose the behavior when an attribute has multiple values in the SAML response. This toggle can be set to First (which will populate the attribute with the first value received) or All (which will populate the attribute with all the values received).

Provider groups

You can also configure Foundry to create groups based on identity provider attributes (called "provider groups"), allowing you to mirror your existing group memberships in Foundry. You may need to additionally configure your provider to include group attributes in the SAML response.

To set up a mapping for a provider group, click Add attribute mapping under Group attribute mapping. When a user logs in, every value for the configured attribute(s) will be mirrored as provider groups, and the user will be enrolled as a member.

Optionally, you can set a regex pattern to extract groups in cases where the groups are sent as a single value instead of a list. For instance, use [^,]+ for comma-separated groups.

Advanced settings

Asynchronous user managers

Asynchronous user managers (AUMs) are configurable extra steps in the login flow. Expand Asynchronous user managers to see the available AUMs.

Creating a Login Checkpoint redirects users at the time of login to a configurable prompt that can ask for a justification before allowing the login to proceed. To enable a Login Checkpoint, first toggle on the Checkpoints Login AUM, and then follow the steps to create a checkpoint.

Configure SAML 2.0 integration

To configure a new SAML integration, see the specific steps for your identity provider below:

Troubleshooting

This error indicates that the username entered by the user does not match any of the authentication provider email domains that were configured and allowlisted in Control Panel. It could also mean that the host from which the user is attempting to log in was not added as a supported host for their configured authentication provider.