---
title: "Setting Up Single Sign-On (SSO) in Unqork"
slug: "setting-up-single-sign-on-sso-in-unqork-unqork-platform"
tags: ["authentication", "single-sign-on"]
updated: 2026-09-14T17:00:38Z
published: 2026-09-14T17:00:38Z
canonical: "docs.unqork.io/setting-up-single-sign-on-sso-in-unqork-unqork-platform"
---

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

# Setting Up Single Sign-On (SSO) in Unqork

Single Sign-On (SSO) lets users authenticate through an external identity provider instead of managing separate Unqork credentials. This guide provides an overview of SSO in Unqork, supported protocols, and the setup process for both Designer and Express domains.

## What Is SSO?

Single Sign-On (SSO) delegates user authentication to an external identity provider (IdP) like Okta, Microsoft Entra ID, or Google Workspace. When users access Unqork, they authenticate through the IdP, which confirms their identity and provides user information to Unqork. This eliminates the need for separate Unqork passwords and centralizes authentication in your organization's existing identity system.

### Benefits of SSO

- **Centralized authentication**: Users authenticate once through your organization's IdP to access multiple applications.
- **Improved security**: Password policies and multi-factor authentication are managed centrally at the IdP level.
- **Simplified user management**: User accounts and permissions are controlled through the IdP, reducing manual administration.
- **Better user experience**: Users sign in with credentials they already use for other corporate applications.

## SSO Domains in Unqork

Unqork separates SSO configurations into two domains, each controlling authentication for different user types:

### Designer SSO

Controls how **Creators** authenticate.

**Use Designer SSO when:**

- You want Creators to sign in through your organization's identity provider.
- You need to enforce centralized password policies for Creators.
- You want to integrate Creator authentication with Active Directory or another enterprise system.

**Example**: A development team authenticates through Okta to access Module Builder and manage applications.

### Express SSO

Controls how **end-users** authenticate.

**Use Express SSO when:**

- Your application serves internal employees who already authenticate through an IdP.
- You want to provide seamless access to applications without requiring separate credentials.
- You need to enforce organizational authentication policies for end-users.

**Example**: Employees authenticate through Microsoft Entra ID to access a claims processing application built in Unqork.

### Independent Configurations

Designer and Express SSO configurations are independent. You can:

- Configure SSO for Designer only (Creators use SSO, end-users use Unqork credentials).
- Configure SSO for Express only (end-users use SSO, Creators use Unqork credentials).
- Configure SSO for both domains (both Creators and end-users use SSO).
- Use different identity providers for each domain.

## Supported SSO Protocols

Unqork supports two SSO protocols: **SAML 2.0** and **OpenID Connect (OIDC)**. Both protocols let an identity provider verify user identity, but use different technical approaches.

### SAML 2.0

**What it is**: Security Assertion Markup Language (SAML) is an XML-based standard commonly used in enterprise environments. When a user authenticates, the IdP generates a signed XML document called an assertion and sends it to Unqork.

**Configuration requirements**:

- IdP metadata XML document.
- X.509 certificate for signature verification.
- Service Provider (SP) entity ID.

**When to use SAML**:

- Your IdP is an enterprise system like Active Directory Federation Services (ADFS).
- Your organization already uses SAML for other applications.
- Your IdP provides an XML metadata document.

**Example providers**: Active Directory Federation Services (ADFS), Okta (SAML application), Ping Identity, OneLogin (SAML)

### OpenID Connect (OIDC)

**What it is**: OpenID Connect (OIDC) is a modern authentication protocol built on OAuth 2.0. Instead of XML assertions, the IdP returns JSON Web Tokens (JWTs) containing user identity claims.

**Configuration requirements**:

- Discovery URL or issuer identifier.
- Client ID.
- Client .

**When to use OIDC**:

- Your IdP is a cloud-based system like Google Workspace or Auth0.
- Your organization prefers modern cloud-native protocols.
- Your IdP provides a discovery URL.

**Example providers**: Google Workspace, Auth0, Okta (OIDC application), Microsoft Entra ID (OIDC endpoint)

### SAML vs. OIDC Comparison

|  | SAML 2.0 | OIDC |
| --- | --- | --- |
| **Data format** | XML assertions | JSON Web Tokens (JWTs) |
| **Configuration complexity** | Higher (metadata exchange) | Lower (discovery URL) |
| **Best for** | Enterprise identity providers | -based identity providers |
| **Setup process** | Exchange metadata XML | Provide discovery URL, client ID, and secret |
| **Token format** | Signed XML | Signed JWT |
| **Additional security** | Signed requests, encrypted assertions | PKCE (Proof Key for Code Exchange) |

## SSO Setup Process

Setting up SSO involves configuration in both your identity provider and Unqork. The exact steps vary by protocol and provider, but the general process follows these stages:

### 1. Prepare Your Identity Provider

Before configuring SSO in Unqork, prepare your identity provider:

**For SAML**:

1. Create a new SAML application in your IdP.
2. Configure the application with Unqork's SP metadata URL (provided in Unqork).
3. Download or copy the IdP metadata XML document.
4. Note the SSO URL, certificate, and NameID format.

**For OIDC**:

1. Register Unqork as a new application in your IdP.
2. Note the client ID and client secret.
3. Copy the discovery URL or issuer identifier.
4. Configure the redirect URI (provided in Unqork).

### 2. Configure SSO in Unqork

Navigate to Single Sign-On (SSO) to create an SSO configuration:

1. Click **Add SSO Configuration** and select the domain (Designer or Express).
2. Provide a unique name for the configuration.
3. Select the protocol (SAML or OIDC).
4. Enter the protocol-specific settings:
  - **SAML**: Paste IdP metadata XML or manually enter SSO URL, certificate, and NameID format.
  - **OIDC**: Enter discovery URL, client ID, and client secret.
5. Configure attribute mappings (map IdP claims to Unqork user attributes).
6. Set a default role for users who authenticate through this configuration.
7. (Optional) Configure advanced settings like PKCE, signed requests, or encrypted assertions.
8. Save the configuration.

### 3. Map User Attributes

Attribute mapping connects user information from your IdP to Unqork user records. At minimum, map one unique identifier:

**Common mappings**:

- Email address: `{{ email }}` → `NameID` (SAML) or `{{ email }}` → `email` (OIDC).
- User ID: `{{ NameID }}` → `NameID` (SAML) or `{{ sub }}` → `sub` (OIDC).
- Display name: `{{ displayName }}` → `displayName`.

**Additional mappings for Express**:

- Role membership: Map IdP group claims to Express roles.
- Organization: Map department or division to custom attributes.

### 4. Test the Configuration

After saving, test the SSO configuration before enabling it for all users:

1. Navigate to the **Single Sign-On (SSO)** page.
2. Click the **three-dot menu** for the configuration and select **Preview** to open the SSO login flow in a new tab.
3. Authenticate through the IdP.
4. Verify that authentication succeeds and user attributes are mapped correctly.
5. Check that the default role is assigned.

### 5. Enable for Users

Once tested, enable the SSO configuration:

**For Designer SSO**:

- Inform Creators that they can now sign in through SSO.
- Provide the SSO login URL or direct them to the login page.
- Creators can choose between SSO and standard login (unless standard login is disabled).

**For Express SSO**:

- Configure modules to require SSO authentication.
- Update application login flows to redirect to the SSO endpoint.
- End-users authenticate through the IdP when accessing the application.

## User Lifecycle Management

SSO configurations control how users are created and matched:

### User Creation

**Automatic creation**: By default, when a user authenticates through SSO for the first time, Unqork creates a new user record with:

- Attributes mapped from IdP claims.
- The default role assigned in the SSO configuration.
- Default groups (Express only).

**Disable automatic creation**: Check **Require User Exists** to restrict authentication to existing Unqork users. New users without an account are denied access.

### User Matching

Unqork matches SSO logins to existing user accounts using the **Match Attribute**:

- **Default**: `NameID` for SAML, `sub` for OIDC.
- **Custom**: Set a different attribute like `email` if your IdP uses email as the unique identifier.

When a user authenticates, Unqork checks if an existing user has a matching value for the match attribute. If found, that user is authenticated. If not found, a new user is created (unless automatic creation is disabled).

## Security Considerations

### Certificate Management

**For SAML**:

- The X.509 certificate verifies the authenticity of SAML assertions from the IdP.
- Store certificates in Certificate Management.
- Rotate certificates before expiration to prevent authentication failures.

**For OIDC**:

- OIDC uses JWTs signed by the IdP's private key.
- Unqork validates tokens using the IdP's public key from the discovery endpoint.
- No certificate management is required.

### Advanced Security Options

**SAML**:

- **Signed AuthnRequest**: Sign authentication requests to prevent tampering.
- **Encrypted Assertions**: Require encrypted SAML responses for sensitive data.
- **HTTP-POST Binding**: Use POST instead of redirect for large SAML payloads.

**OIDC**:

- **PKCE (SHA256)**: Add a code challenge to the authorization flow to prevent interception attacks.
- **Additional Parameters**: Include custom parameters required by your IdP.

### Role Assignment

Always configure a **default role** for SSO users:

**For Designer SSO**:

- Assign a Creator role that grants appropriate resource permissions.
- Default: **Environment:BASIC** (basic Creator access).
- Consider workspace roles for fine-grained access control.

**For Express SSO**:

- Assign an Express role that controls application and data access.
- Default: **NoAccess** (explicitly denies access until granted).
- Map IdP groups to Express roles for dynamic permission assignment.

## Troubleshooting Common Issues

### SAML Metadata Parsing Fails

**Cause**: Invalid or incomplete IdP metadata XML.

**Solution**:

- Verify the metadata XML is complete (no truncation).
- Manually enter the NameID format, SSO URL, and certificate if auto-population fails.
- Check for special characters that might break XML parsing.

### OIDC Discovery URL Not Found

**Cause**: Incorrect discovery URL or network access issue.

**Solution**:

- Verify the discovery URL ends with `/.well-known/openid-configuration`.
- Test the URL in a browser to confirm it returns a JSON discovery document.
- Check firewall rules if Unqork cannot reach the URL.

### User Not Created on First Login

**Cause**: **Require User Exists** is enabled, or attribute mapping is incorrect.

**Solution**:

- Verify **Require User Exists** is unchecked if automatic user creation is desired.
- Check attribute mappings to ensure the match attribute is populated correctly.
- Review IdP claims to confirm the expected attributes are present.

### Authentication Succeeds but Wrong Role Assigned

**Cause**: Default role in SSO configuration does not match expected permissions.

**Solution**:

- Edit the SSO configuration and update the default role.
- For Express, verify the role exists in **Express Role Administration**.
- For Designer, verify the Creator role exists in **Creator Role Administration**.

## Next Steps

After understanding the SSO setup overview:

1. **Review SSO concepts**: See [SSO Concepts](/unqorkai/docs/single-sign-on-sso-concepts) for detailed terminology and protocol explanations.
2. **Configure SSO**: See [Single Sign-On Management](/unqorkai/docs/single-sign-on-sso-management) for step-by-step configuration instructions.
3. **Manage certificates**: See [Certificate Management](/unqorkai/docs/certificate-management) for storing SAML certificates.
4. **Assign roles**: See [Express Role Administration](/unqorkai/docs/express-role-administration) (Express) or [Creator Role Administration](/unqorkai/docs/creator-role-administration) (Designer).

---

**Changelog**

| Date | Change |
| --- | --- |
| 2026-07-10 | Initial publication. |

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.

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.

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.

Okta is a cloud-based identity and access management (IAM) platform that helps organizations manage user identities, access rights, and credentials across multiple applications, websites, and databases.

Also known as Unqork Users, or Designer Users; is anyone who is inside the Unqork platform.

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.

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.

Extensible Markup Language (XML) is markup language that lets you define and store data in a shareable way.

OAuth, or Open Authorization, is an authorization protocol that lets users grant third-party access to their information without sharing their passwords. OAuth is an industry standard that's used by many companies, including Google, Amazon, and Microsoft.

JSON (JavaScript Object Notation) is an open standard file and data interchange format. Unqork uses JSON for submission (record) data.

A URL (uniform resource locator) is a unique identifier used to locate a resource on the internet. Also known as a web address.

The client_id is a public identifier for apps

Auth0 is an identity access management (IAM) platform that enables developers to add authentication and authorization features to their applications.

An API endpoint is the location where an API receives requests for a specific resource on its server. It's the point of contact between an API client and an API server, and is usually a uniform resource locator (URL) that provides the location of the resource.

URI (Uniform Resource Identifier) identifies a resource by name, location, or both.

A key-value pair is a fundamental data structure where a unique "key" is associated with a specific "value," used for organizing and retrieving data efficiently, like in dictionaries or databases.

HTTP (Hypertext Transfer Protocol) is an application-layer protocol used to transmit hypermedia documents like HTML.

The HTTP POST method is used to send data to a server to create or update a resource, typically including the data in the body of the request.

Also known as Unqork Users, or Designer Users; is anyone who is inside the Unqork platform.