Unqork documentation is available in two workspaces: UnqorkAI for the latest AI-first platform, and legacy Unqork for previous versions. Use the drop-down near the logo to switch.

Advanced SSO Attribute Mapping with Nunjucks

Prev Next

Single Sign-On (SSO) attribute mappings can evaluate identity provider (IdP) claims with Nunjucks templates. A template reads the claims in a login, applies conditions, and returns the value Unqork stores in a user attribute like designerRoles or expressRoles. Administrators use templates when an IdP sends a large group array, a single string, or group IDs instead of role names.

To use templates, open the Attribute Mapping section of an SSO configuration. For the full setup, see Single Sign-On (SSO) Management. For the templating language, see the Nunjucks templating documentation.

Not every Nunjucks feature is available in attribute mappings. If a template fails to evaluate, contact Unqork Support.

How Templating Works

To open Single Sign-On (SSO), navigate to icon Administration > icon Environment Settings > icon Environment > Single Sign-On (SSO). Each mapping row has two fields.

Field

Description

[Protocol] Claim

The template or claim name that Unqork evaluates at login. The label displays SAML Claim or OIDC Claim, based on the protocol. A plain claim like {{ sub }} returns the claim value. A longer template can use conditions and filters.

Unqork Attribute

The user attribute that receives the template output. The list offers email, userId, name, and phone. For roles, enter designerRoles or expressRoles as a custom value.

The following attributes receive roles:

Attribute

Description

designerRoles

The Creator roles for a user. Use it on a Designer configuration. The value is a single role name or a comma-delimited list of role names.

expressRoles

The Express roles for a user. Use it on an Express configuration. The value is a single role name or a comma-delimited list of role names.

Unqork removes extra spaces around each role name, so spaces and line breaks around a template's output do not change the roles.

SAML Claims with Colons

A template cannot read a claim name that contains a colon. SAML IdPs often send claims with URI names, like the Microsoft groups claim http://schemas.microsoft.com/ws/2008/06/identity/claims/groups. A template that references that name fails to evaluate.

To work around the limit, configure the IdP to send the value as a custom claim without colons, like groups or MemberOf. Then reference the custom claim in the template.

Extract Roles From a Large SAML Array

An IdP can send many group memberships, and only some apply to Unqork. The template reads the MemberOf claim and keeps values that begin with the prefix ROLE and the delimiter _. It removes the prefix and returns the remaining names as a comma-delimited list.

The IdP sends the following input claim:

{
  "MemberOf": [
    "ROLE_CustomValueOne",
    "IGNORE_CustomValueTwo",
    "ROLE_CustomValueThree",
    "ERROR_CustomValueFour"
  ]
}

The template is the following:

{%- set prefix = "ROLE" -%}
{%- set delimiter = "_" -%}
{%- set prefixCombine = prefix + delimiter -%}
{%- set unqorkExpressRoles = [] -%}
{%- for group in MemberOf %}
  {%- set elements = group.split(delimiter) -%}
  {%- if (elements[0] == prefix) -%}
    {%- set stringTrimmed = group | replace(prefixCombine, "") -%}
    {%- set unqorkExpressRoles = (unqorkExpressRoles.push(stringTrimmed), unqorkExpressRoles) -%}
  {%- endif -%}
{%- endfor -%}
{{unqorkExpressRoles|safe}}

The template works in the following steps:

  1. Sets the prefix and delimiter, and combines them into ROLE_.

  2. Creates an empty list to hold the roles.

  3. Loops over each value in MemberOf and splits the value at the delimiter.

  4. Keeps a value when the first part matches the prefix, removes ROLE_, and adds the result to the list.

  5. Returns the list.

The output is the following value. Unqork stores it in the mapped attribute.

CustomValueOne,CustomValueThree

This template expects MemberOf to be an array. When the IdP sends a single value as a string instead of an array, the template returns an empty value.

Mapping Build Agent Roles

Access to the Build Agent is set for each Creator role. To give a Creator the roles that control Build Agent access, map a template to designerRoles on a Designer configuration. After login, set the access level for each role in Build Agent Access Control.

The role names in the following examples are samples. Replace them with the names of the Creator roles in the environment.

Example 1: Group Names (OIDC)

When the IdP sends a groups claim with group names, a conditional block returns the matching role.

{% if 'AI-Superusers' in groups %}
  Sample Builder Role
{% elif 'AI-Learners' in groups %}
  Sample Ask Only Role
{% else %}
  Sample Standard Role
{% endif %}

The template returns the first role that matches, and returns the last role when no group matches.

When the login has no groups claim, this template fails to evaluate and the login fails. Examples 2 and 4 behave the same way. If the IdP can omit the claim, add the | length check from Example 3.

Example 2: Group Object IDs (Microsoft Entra ID)

Microsoft Entra ID usually sends group memberships as an array of directory object IDs instead of names. The template matches against the specific IDs. The IDs in this example are samples.

{% if '00000000-0000-4000-8000-000000000001' in groups %}
  Sample Builder Role
{% elif '00000000-0000-4000-8000-000000000002' in groups %}
  Sample Ask Only Role
{% else %}
  Sample Restricted Role
{% endif %}

Example 3: Type Casting for Strings and Arrays (OIDC)

Some IdPs send one group as a string and several groups as an array. The | string filter converts the claim to text, so the same check works for both formats. The | length filter skips the check when the claim is empty or missing.

{% if groups | length %}
  {% if 'Unqork_AI_Full' in groups | string %}
    Sample Builder Role
  {% elif 'Unqork_AI_View' in groups | string %}
    Sample Ask Only Role
  {% else %}
    Sample Standard Role
  {% endif %}
{% else %}
  Sample Standard Role
{% endif %}

Because | string searches the full text of the claim, a group name that contains another group name as a part also matches. Use distinct group names.

Example 4: Multiple Roles

The designerRoles attribute accepts a comma-delimited list. A template can return a base environment role and a Build Agent role together.

{% if 'Dept-Engineering' in groups %}
  Sample Admin Role,Sample Builder Role
{% elif 'Dept-Product' in groups %}
  Sample User Role,Sample Ask Only Role
{% else %}
  Sample User Role,Sample No Access Role
{% endif %}

Changelog

Date

Change

2026-11-19

Created the article from source and sandbox testing.