--- title: "OpenID Connect (OIDC) Attribute Mappings" slug: "openid-connect-oidc-attribute-mappings" updated: 2025-09-26T02:50:23Z published: 2025-09-26T02:50:23Z canonical: "docs.unqork.io/openid-connect-oidc-attribute-mappings" --- > ## 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. # OpenID Connect (OIDC) Attribute Mappings ## Overview Attribute mapping provides a more seamless experience for your end-user. For example, mapping the email address returned by the OpenID Provider (OP) to the `email`attribute in the `currentUser` object. Then, use that value to autopopulate any email address fields in your [application](/v1/docs/introduction-to-unqork-applications). Use the **Attribute Mapping** tab on Unqork's [Single Sign-On (SSO) Management](/v1/docs/single-sign-on-ssomanagement) administration page to map claims between a **(**JWT**)** and Unqork attributes. Specifically, you'll map claims to attributes in the `currentUser `object in the session's submission data. In addition to mapping claims to existing attributes in Unqork, you can also create custom attributes. In this article, you'll learn how to create attribute mappings for your OIDC SSO configuration in Unqork. > To learn more about the Single Sign-On (SSO) page, view our [Single Sign-On (SSO) Management](/v1/docs/single-sign-on-ssomanagement) article. ## Considerations It's important to note the relationship between scopes and claims. If you want to list a claim in your attribute mapping, you must request access to the scope where that claim is grouped. For example, the `email`claim is part of the `email`scope. The OP does not grant access to the email claim unless you enter the email in the **OIDC Scope** setting on Unqork's Single Sign-On (SSO) Management administration page. Adding only the email claim to your attribute mapping will not work as expected. ## Default Attribute Mappings in Unqork Many attributes are set by default in Unqork. You do not need to include them in the **Attribute Mapping** tab of the [Single Sign-On (SSO) Management](/v1/docs/single-sign-on-ssomanagement) page. Some of these attributes prevent you from overriding them with custom mapping. If you attempt to customize and override them, the Unqork platform reverts them to their default value. ### Reserved Attributes Below is a list of reserved attributes in Unqork and their default value source (these attributes cannot be overridden): | SSO Variable | Value Source | | --- | --- | | `created` | The Unqork user record. | | `ip` | The end-user's internet IP address. | | `isAdmin` | The effective Unqork permission level. | | `isDesignerUser` | The Unqork user record and SSO method. | | `isUserLocked` | The Unqork user record. | | `lastLogin` | The Unqork user record. | | `modified` | The Unqork user record. | ### Express SSO Default Attributes Below is a list of Express SSO default attributes in Unqork and their default value source: | SSO Variable | Default Value Source | | --- | --- | | `_id` | The generated identifier. | | `applicationRoles` | As defined in the SSO configuration. | | `expressRoles` | N/A > [!NOTE] > This value defaults to an empty array. | | `groups` | N/A > [!WARNING] > This value must include valid groups configured in your environment. | | `isServiceUser` | The Unqork user record. > [!TIP] > Accepts a Boolean value, but it has no effect on the Unqork platform. You can use this SSO variable for configuration logic. | | `role` | This value has been [sunsetted](/v1/docs/unqork-sunsetting-process). Please use `expressRoles` or `designerRoles` values. | | `userId` > [!WARNING] > Note the capitalization of this SSO variable. | N/A | | `userid` > [!WARNING] > Note the capitalization of this SSO variable. | N/A | ### Designer SSO Default Attributes Below is a list of Designer SSO default attributes in Unqork and their default value source: | SSO Variable | Default Value Source | | --- | --- | | `_id ` | The generated identifier. | | `applicationRoles` | As defined in the SSO configuration. | | `designerRoles` | As defined in the SSO configuration. | | `expressRoles` | N/A > [!NOTE] > This value defaults to an empty array. | | `groups` | N/A > [!WARNING] > This value must include valid groups configured in your environment. | | `isServiceUser` | The Unqork user record. > [!TIP] > Accepts a Boolean value, but it has no effect on the Unqork platform. You can use this SSO variable for configuration logic. | | `role` | This value has been sunsetted. Please use expressRoles or designerRoles values. | | `userId` > [!WARNING] > Note the capitalization of this SSO variable. | N/A | | `userid` > [!WARNING] > Note the capitalization of this SSO variable. | N/A | > To learn more about configuring Designer roles using Workspaces Role-Based Access Control (WSRBAC), view our [Workspaces Role-Based Access Control (WSRBAC)](/v1/docs/workspaces-role-based-access-control-wsrbac) article. ### Custom Attributes You can also define custom attributes and map them to the `currentUser` object. The key name and value are flexible, so you can enter special characters, long text, and nested objects. Below are examples of valid Unqork attributes under the `currentUser` object. These values can be configured using the **Attribute Mapping** tab on the Single Sign-On (SSO) Management page. That said, not all examples follow best practice naming conventions. > To learn more about the Single Sign-On (SSO) Management administration page, view our [Single Sign-On (SSO) Management](/v1/docs/single-sign-on-ssomanagement) article. | OIDC Claim | Unqork Attribute | | --- | --- | | `testNum` | `3` | | `testHash` | `#` | | `testQuote` | `"test"` | | `opt1` | `options.1` | | `optOne` | `options.One` | | `{'subTwo':'subTwoValue'}` | `options.Two` | | `three` | `options.Three.three` | | `true` | `isServiceUser` | ```json "currentUser": {           "3": "testNum",           "#": "testHash",           "\"test\"": "testQuote",           "options": {               "1": "opt1",               "One": "optOne",               "Three": {                   "three": "three"               },               "Two": "{'subTwo':'subTwoValue'}",           true: "isServiceUser"           }, } ``` While any valid JSON string is accepted as a key name or value, note the following considerations: - These attributes are included in the `currentUser` object which is sent in the payload of every screen. So, the amount of data that is mapped directly influences the amount of data transferred to the end-user’s browser. - In many cases, data mapped from SSO claims must be parsed by logic in the Unqork configuration. Keeping the data succinct and targeted helps reduce performance impacts. - The variables are mapped in the order they are entered into the SSO configuration. To maintain consistency and readability, follow the same naming conventions used elsewhere in the platform: - Use camelCase without spaces or punctuation. - Use short and descriptive attribute names. - Use appropriate prefixes—for example, `isX` for Boolean values. - Claims with key names in a URL format cannot be parsed by Nunjucks. Many IdP will recommend that custom attributes and claims be sent with a namespace in the form of a URL. For example, `{"http://www.example.com/favoriteColor":"green"}`. This notation is not supported in Unqork mapping. Instead, modify the custom attribute name to omit the URL portion use on the attribute name: `"favoriteColor":"green"`. Or, while still preserving namespaces, modify it in the following way: `"unqorkNamespace_favoriteColor":"green"`. ## Creating Attribute Mappings You can create three attribute mapping types in Unqork. These types include: - **Dynamic**: Dynamically populates the value returned by your OP. - **Conditional**: Conditionally maps values to your Unqork attribute based on the contents of one or more claims. - **Static**: Hardcode a value that always displays, preventing the OP from returning a value as a claim. ### Dynamic Attribute Mappings You most commonly use Nunjucks when creating an attribute mapping. Doing so lets you dynamically populate the attribute with the value returned by the OP. For example, if you want to map the email OIDC claim to the email attribute in Unqork, you'll perform the following steps using [Single Sign-On (SSO) Management](/v1/docs/single-sign-on-ssomanagement): 1. At the top right of the Unqork Designer Platform, click **Settings ▾**. 2. Select **Administration**. 3. Under Environment, click **Single Sign-On (SSO)**. 4. Locate an OIDC SSO configuration you want to create attribute mappings for and click Manage. 5. Select Edit. The SSO configuration displays. 6. Click the **Attribute Mapping** tab. 7. Click **+ Add Attribute Mapping**. 8. In the **OIDC Claim** field, enter `{{email}}`. > [!WARNING] > You must use the same spelling and capitalization as the claim configured in the OP. The name of your Unqork Attribute does not need to match the name of the OIDC claim. 9. From the **Unqork Attribute** drop-down, select **email**. ![](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/Attribute_Map_Dynamic_thumb_0_0.jpg?sv=2026-02-06&spr=https&st=2026-11-09T03%3A51%3A18Z&se=2026-11-09T04%3A51%3A18Z&sr=c&sp=r&sig=bdGewW%2Fsc6JC%2FkB2V7UAiz1DUR6pbE6ogcjC9LjO2UQ%3D) 10. Click **Save**. ### Conditional Attribute Mappings You can use more complex Nunjucks on the OIDC claim side of the mapping. For example, conditionally mapping values to your Unqork attribute based on the contents of one or more claims. This scenario is useful when you want to automatically redirect users to specific application pages. Let's say you want to send users with administrator permissions directly to an administrator's dashboard. Your application can only have a single entry point for all users, regardless of their role permissions. You can conditionally assign a `currentUser` attribute based on the claim values returned by the OP. Then, reference that attribute to create custom redirect rules. For this example, you'll enter the following contents into the **OIDC Claim** field of the [Single Sign-On (SSO) Management](/v1/docs/single-sign-on-sso-nbsp-management) page: ```plaintext {% if dynamic_group | length %} {% if 'Global' in dynamic_group | string %}{{ 'Global' }} {% elif  'Operations-Admin'  in dynamic_group | string %}{{userState}} {% endif %}{% elif  userState | length %}{{userState}} {% else %}{{ 'Unverified' }}{% endif %} ``` The Nunjucks validates the contents of the `dynamic_group` and `userState` claims to determine which value to map to the Unqork attribute role. Let's explore each line of the **OIDC Claim** content: | OIDC Claim | Description | | --- | --- | | `{% if dynamic_group \| length %}` | This line confirms there is a value in the `dynamic_group` claim sent by the OP. | | `{% if 'Global' in dynamic_group \| string %}{{ 'Global' }}` | This line determines if the value in the `dynamic_group` claim is the following string: `'Global'`. If the value exists, it maps 'Global' to the role attribute. | | `{% elif 'Operations-Admin' in dynamic_group \| string %}{{userState}}{% endif %}` | This line determines if the value in the `dynamic_group` claim is the following string: `'Operations-Admin'`. If the value exists, it maps `'Operations-Admin'` to the `userState `claim to the role attribute. | | `{% elif userState \| length %}{{userState}} ` | This line determines if there is any value in the `userState` claim. If a value exists, it maps that value to the `userState` claim to the role attribute. | | `{% else %}{{ 'Unverified' }}{% endif %}` | If none of the previous conditions are met, the mapped value is following string: `'Unverified'`. So, if the `dynamic_group` and `userState` claims have no values, it maps `'Unverified'` to the role attribute. In this example, **Unverified** is the name of a role in the Unqork environment. | Below is an example of how you'd configure this conditional attribute mapping using [Single Sign-On (SSO) Management](/v1/docs/single-sign-on-ssomanagement): 1. At the top right of the Unqork Designer Platform, click **Settings ▾**. 2. Select **Administration**. 3. Under Environment, click **Single Sign-On (SSO)**. 4. Locate an OIDC SSO configuration you want to create attribute mappings for and click Manage. 5. Select Edit. The SSO configuration modal displays. 6. Click the **Attribute Mapping** tab. 7. Click **+ Add Attribute Mapping**. 8. In the **OIDC Claim** field, enter the following information: ```plaintext {% if dynamic_group | length %} {% if 'Global' in dynamic_group | string %}{{ 'Global' }} {% elif  'Operations-Admin'  in dynamic_group | string %}{{userState}} {% endif %}{% elif  userState | length %}{{userState}} {% else %}{{ 'Unverified' }}{% endif %} ``` > [!TIP] > When completing the OIDC claim side of the mapping, entered values show as a single line of text. This example uses a multiple-line display for clarity. You might want to compose the Nunjucks template in an external text editor first. 9. In the **Unqork Attribute** field, enter role. 10. Click **Enter (Return)** on your keyboard. > [!NOTE] > By default, the **Unqork Attribute** drop-down includes commonly referenced attributes. To create a custom attribute, enter the attribute in the **Unqork Attribute** field and click **Enter (Return)** on your keyboard. ![](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/Attribute_Map_Conditional_thumb_0_0.jpg?sv=2026-02-06&spr=https&st=2026-11-09T03%3A51%3A18Z&se=2026-11-09T04%3A51%3A18Z&sr=c&sp=r&sig=bdGewW%2Fsc6JC%2FkB2V7UAiz1DUR6pbE6ogcjC9LjO2UQ%3D) 11. Click **Save**. ### Static Attribute Mappings Instead of using Nunjucks to reference a claim in the JWT, you can hardcode a value. For example, you might set a static value to always display in the `currentUser` object. That way, the OP does not provide that value as a claim in the JWT. To set a static value, enter the value into the **OIDC Claim** field using [Single Sign-On (SSO) Management](/v1/docs/single-sign-on-ssomanagement). No additional formatting is necessary. In the following example, the OIDC Claim of `yes` is a static value mapped to the Unqork Attribute of `internalemployee`. Though this value is not a valid claim in the JWT, it stores the attribute in the `currentUser` object of Unqork's session submission data. 1. At the top right of the Unqork Designer Platform, click **Settings ▾**. 2. Select **Administration**. 3. Under Environment, click **Single Sign-On (SSO)**. 4. Locate an OIDC SSO configuration you want to create attribute mappings for and click Manage. 5. Select Edit. The SSO configuration modal displays. 6. Click **+ Add Attribute Mapping**. 7. In the **OIDC Claim** field, enter `yes`. 8. In the **Unqork Attribute** field, enter `internalemployee`. ![](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/Attribute_Map_Static_thumb_0_0.jpg?sv=2026-02-06&spr=https&st=2026-11-09T03%3A51%3A18Z&se=2026-11-09T04%3A51%3A18Z&sr=c&sp=r&sig=bdGewW%2Fsc6JC%2FkB2V7UAiz1DUR6pbE6ogcjC9LjO2UQ%3D) 9. Click **Save**. ## Testing and Validating To verify that values are mapped correctly, query the `/auth/me` endpoint after authentication. Doing so returns the data related to the currently logged-in user, including default values and custom-mapped attributes. You'll query using the following format: `https://{your-environment}.unqork.io/auth/me`. The following is an example of what you should expect returned: ```json {    "authUser": {        "_id": "dyjlvqlaotbzt_tmwrgwu7rg3jscv_fnnxwztvyibdo",        "authMethod": "oidc",        "authMethodDetails": {            "op": "JM-Test-Entra"        },        "ip": "174.31.225.5",        "isDesignerUser": false,        "sessionId": "5e9731b8-8125-4cf0-89df-2f773ad2e995",        "refreshExp": 1728490346149,        "_csrf": "Lm0ZClDPXyefjt4L0NAeZ4lD",        "exp": 1728418348,        "data": {            "3": "testNum",            "userId": "dyjlvqlaotbzt_tmwrgwu7rg3jscv_fnnxwztvyibdo",            "role": "Authenticated",            "expressRoles": [                "Authenticated"            ],            "groups": [],            "applicationRoles": {},            "created": "2024-10-08T16:12:26.135Z",            "modified": "2024-10-08T16:12:26.228Z",            "lastLogin": "2024-10-08T16:12:26.148Z",            "isUserLocked": false,            "#": "testHash",            "options": {                "1": "opt1",                "One": "optOne",                "Three": {                    "three": "three"                },                "Two": "{'subTwo':'subTwoValue'}"            },            "userid": "dyjlvqlaotbzt_tmwrgwu7rg3jscv_fnnxwztvyibdo",            "_id": "dyjlvqlaotbzt_tmwrgwu7rg3jscv_fnnxwztvyibdo",            "ip": "174.31.225.5",            "isAdmin": false        }    } } ``` ## Resources - [OpenID Connect (OIDC)](/v1/docs/openid-connect-oidc) - [Single Sign-On (SSO) Management](/v1/docs/single-sign-on-ssomanagement) End-users, also known as Express Users, are the individuals accessing an application through Express View. In most cases, end-users are the customers using the product. An OpenID Provider (OP) is Identity Provider (IdP) that acts as a service for authenticating users, provide tokens, and confirm user consent. OIDC providers conform to OpenID Connect, using ID tokens to verify a user's identity. Claims define a user based on an identify provider. They ensure an application can trust the attributes of a user. Claims can include the user's name, email address, and so on. A JSON Web Token (JWT) is used to identify an authenticated user. They are issued by an authentication server to secure use on aclient server. Attributes are pieces of information about a user that are included in an SSO claim. Typically key/value pairs, attributes are used to make decisions about a user's access. Also known as Record Data. Submission data consists of information saved by Unqork components. View submission data by using the angular command, or in Record Collections. OIDC (OpenID Connect) is an identity authentication protocol that lets two applications share user information without exposing user credentials. Single Sign-On is an authentication scheme that enables users to use one set of login credentials across multiple services. An OpenID Provider (OP) is Identity Provider (IdP) that acts as a service for authenticating users, provide tokens, and confirm user consent. OIDC providers conform to OpenID Connect, using ID tokens to verify a user's identity. End-users, also known as Express Users, are the individuals accessing an application through Express View. In most cases, end-users are the customers using the product. The Internet Protocol (IP) address is a unique identifier for a device or network connected to the internet. JSON (JavaScript Object Notation) is an open standard file and data interchange format. Unqork uses JSON for submission (record) data. A naming convention for computer programming. Use camelCase for Property IDs, for example: newUser, lastName, & rdoButton. Nunjucks is a flexible JavaScript templating engine that supports template inheritance, filters, and logic-based expressions for dynamic content rendering. 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. A modal is a window that appears on top of the content you are currently viewing.