SSO (Single Sign-on) Attribute Mapping

Estimated Reading Time:  6 minutes


Unqork uses attribute mapping to enable SSO (Single Sign-On) authentication with Identity Providers (IdP). SSO attribute mapping matches the attribute values of a user's profile stored by IdP services to Unqork's user profile attribute values.

In Unqork, attribute mapping for SSO provides these benefits:

TIP  To learn more about Single Sign-On management, visit our Single Sign-On (SSO) Management article.

What You'll Learn

In this article, you’ll understand how attribute mappings and Nunjucks work, and how to create static and conditional SSO mappings.

Understanding How Attribute Mappings Work

Attribute mappings match the attribute values of the identity management service to those used in Unqork. Identity management services, or Identity Providers (IdPs), use different protocols and attribute values for authentication. Because each service uses different attribute values and authentication methods, the data must match the corresponding values in the connecting service.

For example, in IdP services that use SAML (Security Assertion Markup Language), the attribute for a User ID is NameID. Using attribute mapping, the value of this attribute is matched to Unqork's User ID userID attribute value.

TIP  For an in-depth explanation of OIDC and SAML authentication methods, visit our OpenID Connect (OIDC) and Unqork as a SAML Service Provider articles.

Understanding How Nunjucks Work

Nunjucks Nunjucks is a templating language that's powered by JavaScript. It's a way of extending HTML to add logic, loops, and various other capabilities. is a templating language created for JavaScript JavaScript is an object-oriented computer programming language. It is most-commonly used for interactive effects in the browser.. Nunjucks templates use variables and expressions to perform complex logic in modern browsers. These variables and expressions replace the attribute values when the template renders. In Unqork, SSO mapping attributes use Nunjucks in SAML and OIDC claims to create dynamic and conditional authentication setups. For example, when authenticating in an Okta OIDC configuration, a nunjucks attribute mapping of {{ sub }} tells the OIDC protocol to fill {{ sub }} with the Okta userID.

TIP  To discover the full range of Nunjuck template features, visit the Nunjucks website:

Creating Attribute Mappings

In Unqork, you can create three types of attribute mappings: dynamic, conditional, and static.

Dynamic Attribute Mappings

Unqork uses Nunjucks to create dynamic attribute mappings when creating an attribute mapping. Doing so lets you dynamically populate the attribute with the value returned by the IdP. The example below is for a new Express Role that has already filled out the Basic Information and Configure protocol tabs.

Here's how you'd map the email SAML attribute to the email attribute in Unqork:

1. At the top right of the Unqork Designer Platform, click the Settings ▾ drop-down.
2. Click Administration.
3. Under Environment, click Single Sign-On (SSO).
4. Find an Express SSO to add a SAML attribute to.
5. Click Manage ▾.
6. Click Edit.
7. Click the Attribute Mapping tab.
8. Click + Add Attribute Mapping.
9. In the SAML Claim side of the mapping, enter {{email}} .

NOTE  When filling out the SAML Claim side of the mapping, use the exact spelling and capitalization of the attribute as found from the IdP.

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

10. From the Unqork Attribute drop-down, select email .

NOTE  The Unqork Attribute drop-down lists some 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}.

A static image displaying the New Express SSO modal. The tab is set to Attribute Mapping. The unqork attribute is set to email and the samel claim is set to email in brackets.

Conditional Attribute Mappings

You can also use more complex Nunjucks in the IdP Claim side of the mapping. For example, conditionally mapping values to your Unqork attribute based on the contents of one or more attributes. This is useful in scenarios where you want to automatically redirect some users to certain application pages.

Another example is to send users with Administrator permissions directly to an Administrator's dashboard. Your app can only have a single entry point 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, you can reference that attribute to create custom redirect rules.

Here's an example of a conditional SAML attribute mapping:

A static image displaying the New Express SSO modal. The expressRoles Unqork attribute field is highlighted with the associated SAML Claim

And here are the contents of the SAML Claim side of the mapping:

{% if dynamic_group | length %}
{% if 'MMC-Admin' in dynamic_group | string %}{{ 'MMC-Admin' }}
{% elif  'Eforms-Admin'  in dynamic_group | string %}{{userState}}
{% endif %}{% elif  userState | length %}{{userState}}
{% else %}{{ 'Unverified' }}{% endif %}

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

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

Let's take a look at what this means, line by line:

  • 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'. And, if the value 'MMC-Admin' maps 'MMC-Admin' to the expressRoles attribute in Unqork.

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

Next, this line checks if the value in the dynamic_group SAML attribute is the string 'Eforms-Admin'. If the value is 'Eforms-Admin', it maps the value in the userState SAML attribute to the expressRoles attribute in Unqork.

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

This line checks if there is a value in the userState SAML attribute. If there is, it maps the value in the userState attribute to the expressRoles attribute in Unqork.

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

And finally, if none of the previous conditions are met, the mapped value is the string 'Unverified'. So, if the dynamic_group and userState attributes have no values, they map 'Unverified' to the expressRoles attribute in Unqork. In this example, Unverified is the name of a role in the Unqork environment.

Static Attribute Mappings

You have one more option for using the Attribute Mappings section. Instead of using Nunjucks to reference an attribute in the IdP assertion, you can hardcode a value. For example, you might need to set a static value that always displays in the currentUser object. But, the IdP can't or won't provide that value as an attribute in the assertion. To set a static value, type the value in the Claim side of the mapping. No extra formatting is necessary. For example:

A static image displaying the New Express SSO modal, the Attribute Mapping tab is displayed, and the Unqork attribute internalemployee is set to yes.

Best Practices

When managing Express roles using SSO Attributes: