Single Sign-On (SSO) Management

To access Single Sign-On (SSO) Management, navigate to Administration > Environment > Single Sign-On (SSO) Management.

Single Sign-On (SSO) Management lets administrators create and manage SSO configurations for the Unqork environment. SSO lets Creators authenticate through an external identity provider instead of through Unqork's built-in login. An identity provider is a system like Okta, Azure AD, or Google that manages user credentials. Configurations are separated by domain—Express for Express application users and Designer for Creators.

For background on SSO protocols and terminology, see SSO Concepts.

Managing SSO configurations requires administrative permissions. Administrators needing access should contact their environment administrator.

[docs-mockup:DocsAdminListCanvas] Administration panel overview

Configuration List

The page displays SSO configurations organized into the following tabs.

Tab	Description
Express	SSO configurations for Express application users.
Designer	SSO configurations for Creators.

Each tab displays a table with the following columns:

Column	Description
Name	The name of the SSO configuration.
Protocol	The authentication protocol: SAML or OIDC.
Default Role	The role automatically assigned to users who authenticate through this configuration.
Actions	Configuration-level actions.

Page Actions

Action	Description
Add SSO Configuration	Opens a drop-down to select a domain (Express or Designer), then opens a modal to create a new configuration. This action is always available regardless of which tab is selected.

Configuration Actions

Select the actions menu on any row to access the following:

Action	Description
Edit	Opens the configuration form to edit the settings.
Preview	Opens the SSO login flow in a new browser tab for testing.
Delete	Permanently removes the SSO configuration. This action cannot be undone.

Adding a Configuration

Click New SSO and choose a domain to open a modal. The modal is organized into the following sections: Basic Information, Configure Protocol, and Attribute Mapping.

Basic Information

Field	Description
SSO Name	A unique identifier for this SSO configuration. Spaces are replaced with hyphens. Cannot be changed after creation.
Default Role	The role assigned to users who authenticate through this configuration. For Express configurations, options are populated from the environment's Express roles and default to NoAccess. For Designer configurations, options are populated from Creator roles and default to Environment:BASIC.
Default Groups	The groups automatically assigned to new Express users who authenticate through this configuration. Select from existing Express groups. Displays for Express domain configurations only.

Configure Protocol

Select a protocol to display the relevant configuration fields—either SAML or OIDC. The protocol cannot be changed after creation. Use SAML for enterprise identity providers that exchange XML metadata. Use OIDC for modern cloud-based providers that support a discovery URL.

SAML

IdP Details

Field	Description
IdP Metadata XML	The XML metadata from the identity provider. Paste the full XML to auto-populate the NameID Format, SSO URL, and Certificate fields.
SAML IdP NameID Format	The NameID format used by the identity provider. Auto-populated from the IdP Metadata XML.
SAML IdP SSO URL	The SSO endpoint URL of the identity provider. Auto-populated from the IdP Metadata XML.
SAML IdP X.509 Certificate	The certificate used to verify SAML responses from the identity provider. Auto-populated from the IdP Metadata XML. Accepts multiple certificates as a comma-separated list.

Configuration Details

Field	Description
SAML SP Entity ID	The service provider entity ID. Must match the SP Entity ID configured in the identity provider.
SAML Callback URL	The URL the identity provider redirects to after authentication. Defaults to a dynamic host based on the initial request.

Click Copy Metadata URL to copy the service provider metadata URL to your clipboard. Use this URL when configuring Unqork as a service provider in the identity provider.

Advanced Settings

Setting	Description
Use HTTP-POST Binding	When checked, this setting uses HTTP-POST binding for the AuthnRequest instead of HTTP-Redirect.
Use Signed AuthnRequest	When checked, this setting signs the AuthnRequest with a certificate. Required by some identity providers for added security.
Expect Encrypted Assertions	When checked, this setting requires the identity provider to send encrypted assertion data. Required when the identity provider is configured to encrypt assertions.
Do Not Request a Specific Authentication Context	When checked, this setting omits the RequestedAuthnContext from the SAML request. Required by some identity providers that reject this element.
SAML Certificate	Displays when Use Signed AuthnRequest or Expect Encrypted Assertions is checked. The certificate to use for signing or decryption. Manage certificates in Certificate Management.

OIDC

IdP Details

Field	Description
OP Discovery URL/Issuer	The OpenID Provider's discovery URL or issuer identifier.
OP Client ID	The client identifier registered with the OpenID Provider.
OP Client Secret	The client registered with the OpenID Provider.

Configuration Details

Field	Description
Scope	A space-separated list of scopes to request. Defaults to `openid`.
Redirect URI	The URI the OpenID Provider redirects to after authentication.

Advanced Settings

Setting	Description
Store OIDC ID Token	When checked, this setting stores the OIDC ID token for use in downstream requests.
Get claims from instead of UserInfo Endpoint	When checked, this setting reads user claims from the access token instead of the UserInfo endpoint.
PKCE Code Challenge Method	The Proof Key for Code Exchange (PKCE) method for securing the authorization code flow. Options include: Disable PKCE, SHA256, or Plain.
Additional Parameters	Custom key-value pairs appended to the authorization request. Click + Add Parameter to add a row.

Attribute Mapping

Maps identity provider claims to Unqork user attributes. At least one mapping is required.

Mappings

Column	Description
[Protocol] Claim	The claim returned by the identity provider. For SAML, defaults to `{{ NameID }}`. For OIDC, defaults to `{{ sub }}`.
Unqork Attribute	The Unqork user attribute to map the claim to.

Click + Add Attribute Mapping to add a row.

User Management

Setting	Description
Require User Exists	When checked, this setting restricts authentication to existing Unqork users only. Users not already in the system are denied access.
Disable User Creation	When checked, this setting prevents SSO-authenticated users from being modified through the API.
Match Attribute	The attribute used to match an SSO login to an existing Unqork user. Defaults to `NameID` for SAML and `sub` for OIDC.

Changelog

Date	Change
—	Initial publication.