Unqork as a SAML Service Provider

Unqork as a SAML service provider secures applications that work with sensitive information. Having end-users use SSO (single sign-on) to access your application is an effective approach. When setting up SSO, you can select the authentication provider for your Unqork application. Instead of storing end-users' credentials in Unqork, the SSO provider manages them. SSO also gives your end-users fewer credentials to remember and a seamless login experience. You can trust your SSO provider to verify that the right people have access to your app.

SAML (Security Assertion Markup Language) is one of the SSO methods Unqork supports. SAML makes granting access to your Unqork application easier by:

• Letting you grant access to end-users without Unqork credentials.

• Letting Unqork users log in without having to input their credentials.

In this article, you'll learn about using Unqork as a SAML Service Provider.

Unqork also supports SSO using the OIDC (openid Connect) authentication method. To learn more, search openid Connect (OIDC) in our In-Product Help.

What Is a SAML Service Provider?

SAML is a secure exchange of information between an Identity Provider (IdP) and a Service Provider (SP). The SP in this case is Unqork. The IdP is any SSO provider, like Okta or Microsoft Azure Entra ID.

As an SP, Unqork supports three SAML request/response flows:

• IdP-Initiated Flow

• SP-Initiated Flow (AuthnRequest HTTP-Redirect Binding)

• SP-Initiated Flow (AuthnRequest HTTP-POST Binding)

IdP-Initiated Flows are the most common SAML configuration in Unqork. In this flow, an end-user begins on a client's website, clicks a link, and gains access to an Unqork application without logging in. The client has already established the user's identity and uses SAML to pass proof of that identity to Unqork.

One Unqork environment can support multiple SAML configurations.

How SSO Using SAML Works in Unqork

Here is how the authentication process works when using SAML. In this explanation, the SSO provider is the IdP and Unqork is the SP.

If the end-user is already logged in to the SSO provider when they open your application, they GET a seamless login experience and don't need to log in again. If your end-user does need to log in first, you decide how they log in. For example, you can set up an automatic redirect to a provider-hosted login page. Or, you can use a series of API calls to communicate between an Unqork-hosted page and the SSO provider's API.

When the end-user successfully logs in to the IdP, the IdP issues a SAML assertion and sends it to your Unqork environment. A SAML assertion is an encoded XML document that contains identity information about the end-user. The SAML assertion authenticates your end-user's identity. The assertion also contains information that tells your Unqork application whether the end-user has authorization to access your app—for example, if the end-user has specific role permissions or characteristics your app recognizes. The XML document structures this information as a series of Attribute elements. Each Attribute element contains an attribute name and an attribute value.

The IdP doesn't send the SAML assertion directly to your application's front end. It also doesn't send it to a module you can access from Designer View. Your application should only have access to the attributes specified in the SAML configuration, not all the information in the assertion. So, the IdP sends the assertion to the Callback URL entered in the SAML configuration on the IdP's end. The Callback URL is an endpoint of the SP's underlying platform. For Unqork applications, that endpoint typically looks like https://<host>/auth/saml/consume?idp=<SAMLname>. There, the Unqork platform decodes the SAML assertion and creates a session for the end-user. Unqork also strips the assertion, keeping only the attributes listed in your SAML configuration. These attributes map to attributes in the currentUser object of the session's Submission Data.

When configuring which attributes to pull from the SAML assertion, you also specify which Unqork attribute receives the mapped value. You control this mapping in the Attribute Mappings section of the SAML configuration. You can use attribute mapping to improve your end-user's experience. For example, you can use the email address returned by the IdP to autofill an email field in your application.

Understanding the SAML Settings in Single Sign-On (SSO) Management

To connect the SAML configuration on the SSO provider's end to your Unqork application, use the Single Sign-On (SSO) Management page. Begin by reviewing each setting in the SSO configuration Modal.

Available settings in the SSO configuration Modal vary between Express View and Designer SSO configurations. The following images reflect the Express View SSO configuration modal. The settings description tables note which settings are specific to Express View or Designer configurations.

To learn more about using the Single Sign-On Management page, view our Single Sign-On Management article.

Basic Information Tab

Configure Protocol Tab

Select SAML from Select Protocol to access the following SAML configuration settings.

The Configure Protocol tab is where you enter the IdP metadata XML file. The foundation of any SAML setup is creating a relationship between the IdP and SP by exchanging IdP and SP metadata XML files. The administrator of the SSO provider account issues an IdP metadata XML file, which you use to complete your SAML configuration. In return, you give the IdP the SP metadata XML file. This is the preferred method of configuration.

You can also set up a SAML configuration without parsing an IdP metadata file. However, using a metadata file is the preferred and most common setup method.

In some cases, the administrator of the SSO provider account requests the SP metadata XML file before they issue the IdP metadata XML file. The configuration modal lets you generate a placeholder SP metadata XML file. Click Copy Metadata URL to generate an SP metadata XML file based on default configuration values and copy its URL to your clipboard.

IdP Details

After pasting the contents of the IdP metadata XML file in the IdP Metadata XML field, Unqork automatically parses the file. If the file is valid, the other fields in this section display and autofill based on the file's contents.

All settings in this section are required:

Using Multiple Certificates

Unqork supports multiple certificates from a single IdP metadata file, displaying each one in the SAML IdP X.509 Certificate field separated by a comma.

If the first certificate fails or expires, Unqork attempts to validate using the next certificate in the list. Use this method to ensure service availability when rotating from an expiring certificate to a new one. The order in which Unqork uses a certificate depends on the order the certificates appear in the XML file.

The following code block shows IdP Metadata with multiple certificates:

<?xml version="1.0" encoding="UTF-8"?>
<EntityDescriptor entityID="https://idp.example.com/simplesaml/saml2/idp/metadata.php" 
    xmlns="urn:oasis:names:tc:SAML:2.0:metadata" 
    xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
    
    <IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
        
        <KeyDescriptor use="signing">
            <ds:KeyInfo>
                <ds:X509Data>
                    <ds:X509Certificate>
                        MIICajCCAdOgAwIBAgIBADANBgkqhkiG9w0BAQ0FADBSMQswCQYDVQQGEwJVUzETMBEG
                        A1UECAwKQ2FsaWZvcm5pYTasdfgsdfhdfghwwNU2FuIEZyYW5jaXNjbzENMAsGA1UECgwE
                        S2V5dDEOMAwGA1UEAwwFbm9kZTEwHhcNMTkwMTAxMDAwMDAwWhcNMjkwMTAxMDAwMDAw
                        WjBSMQswCQYDVQQGEwJVUzETMBEGA1UECAwKQ2FsaWZvcmasdYTEWMBQGA1UEBwwNU2Fu
                        ... (Certificate Data) ...
                    </ds:X509Certificate>
                </ds:X509Data>
            </ds:KeyInfo>
        </KeyDescriptor>

        <KeyDescriptor use="signing">
            <ds:KeyInfo>
                <ds:X509Data>
                    <ds:X509Certificate>
                        MIIEAzCCAuugAwIBAgIUBm6h6B9WvO3D2K5Jm6h6B9WvO3AwDQYJKoZIhvcNAQELBQAw
                        RzELMAkGA1UEBhMCasdsgdfghdfhfgBAgMadWSdDUI3IDFHGHFASgdfFGaghdwMTAxMDAwMDAwWhcNMzYwMTAxMDAw
                        MDAwWjBHMQswCQYDVQQGEwJVUzETMBEGA1UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwN
                        ... (New Certificate Data) ...
                    </ds:X509Certificate>
                </ds:X509Data>
            </ds:KeyInfo>
        </KeyDescriptor>

        <NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</NameIDFormat>
        <SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://idp.example.com/saml2/sso"/>
        
    </IDPSSODescriptor>
</EntityDescriptor>

Configuration Details

Advanced Settings

Click Show Advanced Settings to display the following settings:

Attribute Mapping Tab

The Attribute Mapping tab is where you map attributes in the SAML assertion to attributes in Unqork. Specifically, you map SAML attributes to attributes in the currentUser object in the session's submission data. You can also create custom attributes in addition to mapping SAML attributes to existing Unqork attributes. Attribute mapping provides a more seamless experience for your end-user. For example, you can map the email address returned by the IdP to the email attribute in the currentUser object, then use that value to autofill email address fields in your application.

The Attribute Mapping tab refers to SAML attributes as SAML claims.

See the Creating Attribute Mappings section for examples of dynamic, conditional, and static attribute mappings.

Click + Add Attribute Mapping to create a new mapping.

By default, the Attribute Mapping tab includes the mapping {{NameID}} to userId. Do not delete this mapping or your SSO configuration will fail.

User Management

Click Show User Management to display the following settings:

Creating Attribute Mappings

You can create three types of attribute mappings: dynamic, conditional, and static.

Dynamic Attribute Mappings

When creating an attribute mapping, you most commonly use Nunjucks to dynamically populate the attribute with the value returned by the IdP. For example, here is how to map the email SAML attribute to the email attribute in Unqork:

1. On the Attribute Mapping tab, click + Add Attribute Mapping.

2. Enter {{email}} in the SAML Claim side of the mapping.

   When filling out the SAML Claim side of the mapping, use the exact spelling and capitalization of the attribute as it displays on the IdP.

   The name of your Unqork Attribute doesn't need to match the name of the SAML attribute.

3. Select email from the Unqork Attribute drop-down.

   The Unqork Attribute drop-down lists commonly-referenced attributes. To create a custom attribute, type the attribute in the Unqork Attribute field, then press Enter/Return or select Create {attribute name}.

   

Conditional Attribute Mappings

You can also use more complex Nunjucks in the SAML Claim side of the mapping. For example, you can conditionally map values to your Unqork attribute based on one or more other attributes. This is useful when you want to automatically redirect some users to certain pages of your application. For example, you might want to send users with admin permissions directly to an administrator's dashboard. Your app can only have a single point of entry for all users, regardless of their role permissions. But you can conditionally assign a currentUser attribute based on the attribute values returned by the IdP, then reference that attribute to create custom redirect rules.

You cannot configure custom redirects based on roles and attributes in the SSO Configuration modal.

Here is an example of a conditional attribute mapping:

Here are the contents of the SAML Claim side of the mapping:

1 {% if dynamic_group | length %}
2 {% if 'MMC-Admin' in dynamic_group | string %}{{ 'MMC-Admin' }}
3 {% elif  'Eforms-Admin'  in dynamic_group | string %}{{userState}}
4 {% endif %}{% elif  userState | length %}{{userState}}
5 {% else %}{{ 'Unverified' }}{% endif %}

When completing the SAML Claim side of the mapping, entered values show as a single line of text. This explanation uses a multiple-line display for clarity.

In this example, the Nunjucks checks the dynamic_group and userState SAML attributes to determine what value to map to the Unqork attribute role. Both the dynamic_group and userState attributes contain values that could map to an Unqork role.

Here is what each line does:

Line 1: {% if dynamic_group | length %}

This line checks that there is a value in the dynamic_group SAML attribute sent by the IdP.

Line 2: {% if 'MMC-Admin' in dynamic_group | string %}{{ 'MMC-Admin' }}

The next line checks if the value in the dynamic_group SAML attribute is the string 'MMC-Admin'. If so, Unqork maps 'MMC-Admin' to the role attribute.

Line 3: {% elif  'Eforms-Admin'  in dynamic_group | string %}{{userState}}{% endif %}

This line checks if the value in the dynamic_group SAML attribute is the string 'Eforms-Admin'. If so, Unqork maps the value in the userState SAML attribute to the role attribute.

Line 4: {% elif  userState | length %}{{userState}}

This line checks if the userState SAML attribute contains a value. If it does, Unqork maps that value to the role attribute.

Line 5: {% else %}{{ 'Unverified' }}{% endif %}

Finally, if none of the previous conditions are true, Unqork maps 'Unverified' to the role attribute. Use this fallback when the dynamic_group and userState attributes have no values. In this example, Unverified is the name of a role in the Unqork environment.

Static Attribute Mappings

The Attribute Mappings section has one more option. Instead of using Nunjucks to reference an attribute in the SAML assertion, you can hardcode a value. For example, you might need a static value that always displays in the currentUser object, but the IdP doesn't provide it as an attribute in the SAML assertion. To set a static value, type it in the SAML Claim side of the mapping. No additional formatting is necessary. For example:

Configuring SSO Using SAML With Different SSO Providers

Now that you know the SAML configuration settings, you're ready to begin connecting Unqork to your chosen SSO provider. Use the SSO guides below to begin:

SSO in Express View (SAML)

Set Up Microsoft Entra ID for SSO in Express View (SAML)

Set Microsoft Entra ID as an SSO (single sign-on) provider using the SAML (Security Assertion Markup Language) authentication method.

Set Up Okta for SSO in Express View (SAML)

Learn how to use Okta as an SSO (single sign-on) provider using the SAML (Security Assertion Markup Language) authentication method.

SSO in Designer (SAML)

Set Up Microsoft Entra ID for SSO in Designer (SAML)

Learn how to use Microsoft Entra ID as an SSO (single sign-on) provider, using the SAML (Security Assertion Markup Language) authentication method.                                                

Set Up Okta for SSO in Designer (SAML)

Learn how to use Okta as an SSO (single sign-on) provider, using the SAML (Security Assertion Markup Language) authentication method.

SSO Certificates

Using Certificates with SAML Assertions

Create a SAML signing certificate, then add it to a new or existing SSO configuration.