OpenID Connect (OIDC) Attribute Mappings

Overview

Attribute mapping provides a more seamless experience for your end-user Includes the Short Answer component, Long Answer component, Select Boxes, Radio component, Dropdown, Number component and Single Checkbox.. For example, mapping the email address returned by the OpenID Provider (OP) 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. to the email attribute in the currentUser object. Then, use that value to autopopulate any email address fields in your application.

Use the Attribute Mapping tab on Unqork's Single Sign-On (SSO) Management administration page to map claims 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. between a JSON Web Token (JWT) 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.  and Unqork attributes 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.. Specifically, you'll map claims to attributes in the currentUser object in the session's submission data 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.. 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 OIDC (OpenID Connect) is an identity authentication protocol that lets two applications share user information without exposing user credentials. SSO Single Sign-On is an authentication scheme that enables users to use one set of login credentials across multiple services. configuration in Unqork.

To learn more about the Single Sign-On (SSO) page, view our Single Sign-On (SSO) Management 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 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. 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 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):

Express SSO Default Attributes

Below is a list of Express SSO default attributes in Unqork and their default value source:

Designer SSO Default Attributes

Below is a list of Designer SSO default attributes in Unqork and their default value source:

To learn more about configuring Designer roles using Workspaces Role-Based Access Control (WSRBAC), view our 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 article.

$$"currentUser"$$: {
           $$"3"$$: !!"testNum"!!,
           $$"#"$$: !!"testHash"!!,
           $$"$$!!\"!!$$test$$!!\"!!$$"$$: !!"testQuote"!!,
           $$"options"$$: {
               $$"1"$$: !!"opt1"!!,
               $$"One"$$: !!"optOne"!!,
               $$"Three"$$: {
                   $$"three"$$: !!"three"!!
               },
               $$"Two"$$: !!"{'subTwo':'subTwoValue'}"!!,
           $$true$$: !!"isServiceUser"!!
           },
}

While any valid JSON JSON (JavaScript Object Notation) is an open standard file and data interchange format. Unqork uses JSON for submission (record) data. 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 Single Sign-On is an authentication scheme that enables users to use one set of login credentials across multiple services. 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:

• Claims with key names in a URL format cannot be parsed by 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.. Many IdPs 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. 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:

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 page:

{% 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:

Below is an example of how you'd configure this conditional attribute mapping using Single Sign-On (SSO) Management:

{% 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 %}

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. 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 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..

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:

{
   $$"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)

• Single Sign-On (SSO) Management