--- title: "Advanced SSO Attribute Mapping with Nunjucks" slug: "advanced-sso-attribute-mapping-with-nunjucks" description: "Use Nunjucks templates in SSO attribute mappings to extract roles from SAML claims, group names, or IDs and assign Unqork designerRoles." tags: ["administration", "single-sign-on", "authentication"] status: "new" updated: 2026-11-20T15:26:39Z published: 2026-11-20T15:26:39Z canonical: "docs.unqork.io/advanced-sso-attribute-mapping-with-nunjucks" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.unqork.io/llms.txt > Use this file to discover all available pages before exploring further. # Advanced SSO Attribute Mapping with Nunjucks 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](/unqorkai/docs/single-sign-on-sso-management). For the templating language, see the [Nunjucks templating documentation](https://mozilla.github.io/nunjucks/templating.html). > [!NOTE] > 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](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/api_upload_20261120_152018_e632413c6fa647c69fd69da70d11ce66.svg?sv=2026-02-06&spr=https&st=2026-11-20T17%3A50%3A45Z&se=2026-11-20T18%3A50%3A45Z&sr=b&sp=r&sig=SfS550lUyQArPr33FBdXY4rOnUH%2BUp0fduqKjBcb%2Bd4%3D) **Administration** > ![icon](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/api_upload_20261120_152018_a0e0cb463e574112aa50231d870e867a.svg?sv=2026-02-06&spr=https&st=2026-11-20T17%3A50%3A45Z&se=2026-11-20T18%3A50%3A45Z&sr=b&sp=r&sig=YYg80TJRt8MRAz%2FNpnGPPCnAAJjSZwOKervsULMWTyY%3D) **Environment Settings** > ![icon](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/api_upload_20261120_152018_87d88b39c8c042fdae489ca357421812.svg?sv=2026-02-06&spr=https&st=2026-11-20T17%3A50%3A45Z&se=2026-11-20T18%3A50%3A45Z&sr=b&sp=r&sig=Cw3Fj0pn3ot4PyBvuwi%2FGyBy3Hlzwu7lF5%2F9RnGGZB8%3D) **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: ```json {  "MemberOf": [    "ROLE_CustomValueOne",    "IGNORE_CustomValueTwo",    "ROLE_CustomValueThree",    "ERROR_CustomValueFour"  ] } ``` The template is the following: ```plaintext {%- 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. ```plaintext CustomValueOne,CustomValueThree ``` > [!WARNING] > 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](/unqorkai/docs/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. ```plaintext {% 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. > [!WARNING] > 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. ```plaintext {% 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. ```plaintext {% 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. ```plaintext {% 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. | Single Sign-On is an authentication scheme that enables users to use one set of login credentials across multiple services. Identity provider (IdP) provide a service that creates, manages, and verifies users' digital identities, allowing them to securely authenticate and access different applications or services. Identity provider (IdP) provide a service that creates, manages, and verifies users' digital identities, allowing them to securely authenticate and access different applications or services. An array is a type of object that stores one or more data types. Data types supported in arrays include numbers, strings, and objects. A string is an object that represents a sequence of characters. Strings typically hold data represented in text form. A functionality of a software. For example, Copy and Paste is a feature of a computer's operating system. Security Assertion Markup Language (SAML) is a protocol that allows an identity provider (IdP) to send a user's credentials to a service provider (SP) to verify their identity and grant them access to a service. OIDC (OpenID Connect) is an identity authentication protocol that lets two applications share user information without exposing user credentials. Also known as Unqork Users, or Designer Users; is anyone who is inside the Unqork platform. The Unqork front-end application framework that delivers Creator-built applications to end-users. Express is the layer end-users interact with—the published forms, screens, and navigation built in the Module Builder. Express is distinct from Express View, which is a Creator-facing preview tool in the IDE. URI (Uniform Resource Identifier) identifies a resource by name, location, or both. A delimiter is a chracter or symbol that seperates words, data, or other characters. Use delimiters to mark the begining, or end of of value. Example delimiters include the comma ",", ampersand "&", or an empty space " ". An object is a type of data structure that represents a single, self-contained entity that acts as a container for the characteristics of that entity. ## Related - [Single Sign-On (SSO) Management](/single-sign-on-sso-management.md) - [Setting Up Microsoft Entra ID for SSO in Designer (SAML)](/setting-up-microsoft-entra-id-for-sso-in-designer-saml-unqork-platform.md) - [Setting Up Okta for SSO in Designer (SAML)](/setting-up-okta-for-sso-in-designer-saml-unqork-platform.md)