SSO (Single Sign-on) Attribute Mapping

Estimated Reading Time:  6 minutes

Overview

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:

• Associates authentication values between Unqork and different services, including Okta, Azure, and Amazon Web Services (AWS).

• Simplifies the user SSO authentication process for Creators Also known as Unqork Users, or Designer Users; is anyone who is inside the Unqork platform. and Express users.

• Allows for complex, dynamic authentication setups by using 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..

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: https://mozilla.github.io/nunjucks/templating

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:

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:

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

1
2
3
4
5
{% 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 %}

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

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

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

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

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:

Best Practices

When managing Express roles using SSO Attributes:

• In the user object, define a role for Express using the expressRoles property .

• The expressRoles property accepts an array An array is a type of object that stores one or more data types. Data types supported in arrays include numbers, strings, and objects. of roles. For example, ['Role1', 'Role2'].

• While the existing rolestring A string is an object that represents a sequence of characters. Strings typically hold data represented in text form. property is functional, use the expressRoles array property to assign rules to end-users.

Resources

• Single Sign-On (SSO) Management

• Unqork as a SAML Service Provider

• OpenID Connect (OIDC)

• Environment Administration