Single Sign-On (SSO) lets Creators and end-users log in once through an external identity provider and access Unqork without maintaining a separate password. This article covers the protocols, terminology, and flow behind SSO so Creators can configure it correctly in Single Sign-On (SSO) Management.
What Is SSO?
Single Sign-On (SSO) lets Creators and end-users authenticate once through an external system called an identity provider and access Unqork without managing a separate password. Instead of Unqork verifying credentials directly, it delegates that responsibility to the identity provider, which confirms the user's identity and passes that information back.
In Unqork, SSO configurations are separated by domain:
Express: Controls how end-users authenticate.
Designer: Controls how Creators authenticate.
Core Concepts
Term | Definition |
|---|---|
Identity Provider (IdP) | The system that authenticates users and provides identity information. Common examples include Okta, Microsoft Entra ID (formerly Azure AD), and Ping Identity. |
Service Provider (SP) | The application that relies on the IdP for authentication. In Unqork SSO configurations, Unqork is the SP. |
Claim | A piece of user information provided by the IdP, like an email address or group membership. |
Attribute Mapping | A configuration that maps an IdP claim to a Unqork user attribute, so user data from the IdP can be used in Unqork. |
Protocols
Unqork supports two SSO protocols: SAML and OIDC. Both protocols let an identity provider vouch for a user's identity, but use different approaches.
SAML
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. Unqork validates the assertion using the IdP's certificate and grants access.
SAML configuration begins with exchanging metadata: the IdP provides an XML metadata document, and Unqork's SP metadata URL can be shared with the IdP in return.
Use SAML when the identity provider is an enterprise system like Active Directory Federation Services (ADFS), a SAML-specific Okta application, or any provider that delivers an XML metadata document.
OIDC
OpenID Connect (OIDC) is a modern authentication protocol built on OAuth 2.0. Instead of XML assertions, the identity provider returns JSON Web Tokens (JWTs)—a compact, signed format that is easier to work with in cloud-native environments. Configuration requires only a discovery URL, client ID, and client secret, with no metadata exchange needed.
Use OIDC when the identity provider is a cloud-based system like Google Workspace, Auth0, or a modern Okta application that supports a discovery URL.
Creators and end-users have 30 minutes to complete the OIDC authentication flow after it begins. If the flow is not completed in that time, the session expires and authentication must begin again. This timeout is not configurable.
If the SSO login process includes tasks that might exceed 30 minutes, like new user registration in the IdP, separate those tasks from the SSO flow. For example, on a custom login screen, add a New User Registration link that directs end-users to the registration flow in the IdP. Once registered, the user can begin the SSO authorization at the Unqork SSO endpoint.
Refresh Tokens
Unqork supports OIDC refresh tokens. When an end-user logs in, the IdP may send both an access_token and a refresh_token. The IdP does not send the refresh_token unless the offline_access scope is requested — this scope is configured in the IdP or Identity Engine. Unqork can request this scope as part of the SSO configuration. Depending on the IdP, other scopes may be required, like openid.
Once the end-user is logged in, Unqork issues an ID token for use in the platform to identify and authorize the end-user. Unqork does not proactively refresh the access_token. It checks whether the access_token has expired only when the end-user attempts to access a service configured in Services Administration to use OIDC authentication. If the token has expired, Unqork uses the refresh_token against the /token endpoint defined in the IdP's .well-known/openid-configuration to get a new access_token and refresh_token.
SAML vs. OIDC
The right protocol depends on what the identity provider supports. SAML is the established standard in enterprise environments; OIDC is the modern default for cloud-based providers.
Criteria | SAML | OIDC |
|---|---|---|
Data format | XML | JSON (JWT) |
Configuration | Metadata XML exchange | Discovery URL, client ID, client secret |
Typical providers | ADFS, Okta (SAML app), enterprise IdPs | Google Workspace, Auth0, Okta (OIDC app) |
Tokens | Assertions (signed XML) | ID Token and Access Token (JWTs) |
PKCE support | No | Yes |
Refresh token support | No | Yes |
SAML Terms
Term | Definition |
|---|---|
IdP Metadata XML | An XML document provided by the IdP containing configuration details, including the SSO URL, certificate, and supported NameID formats. Pasting this into Unqork auto-populates several fields. |
NameID Format | Identifies how the subject of a SAML assertion is named. Auto-populated from the IdP Metadata XML. |
SSO URL (Entry Point) | The URL on the IdP where authentication requests are sent. Auto-populated from the IdP Metadata XML. |
X.509 Certificate | A digital certificate used to establish trust between the IdP and SP. Auto-populated from the IdP Metadata XML. |
SP Entity ID | A unique identifier for Unqork as the service provider. Must match the SP Entity ID configured in the IdP. |
Callback URL | The URL the IdP redirects users to after successful authentication. |
SP Metadata URL | A URL that exposes Unqork's service provider metadata. Copy and share this with the IdP when configuring Unqork as a service provider. |
HTTP-POST Binding | An alternative method for delivering the SAML AuthnRequest. Some IdPs require POST binding instead of the default HTTP-Redirect. |
Signed AuthnRequest | A SAML authentication request signed with a certificate. Some IdPs require signed requests for added security. |
Encrypted Assertions | SAML assertions encrypted by the IdP before delivery. Required when the IdP is configured to encrypt assertion data. |
OIDC Terms
Term | Definition |
|---|---|
OP Discovery URL/Issuer | The URL that identifies the OpenID Provider and hosts a discovery document describing its endpoints and capabilities. |
Client ID | The identifier assigned to Unqork by the OpenID Provider when the application is registered. |
Client Secret | A secret key used alongside the Client ID to authenticate requests to the OpenID Provider. |
ID Token | A JWT issued by the OpenID Provider that contains identity claims about the authenticated user. |
Access Token | A JWT that grants access to protected resources. Some providers include user claims in the access token instead of the UserInfo endpoint. |
Scope | Specifies what user information to request from the IdP. Defaults to |
Redirect URI | The URL the OpenID Provider redirects users to after authentication. Must match the URI registered with the provider. |
PKCE (Proof key for Code Exchange) | An OAuth 2.0 extension that adds security to the authorization code flow by signing the request with a code challenge. SHA256 is the most widely supported method. |
Attribute Mapping Terms
Term | Definition |
|---|---|
Attribute Mapping | Maps an IdP claim to a Unqork user attribute so identity data from the IdP is stored correctly on the Unqork user record. |
Match Attribute | The attribute used to match an incoming SSO user to an existing Unqork account. Defaults to |
Default Role | The role automatically assigned to Creators or end-users who log in through an SSO configuration for the first time. |
Default Groups | Groups automatically assigned to end-users who log in through an Express SSO configuration. |
Changelog
Date | Change |
|---|---|
— | Initial publication. |