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

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

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 Administration > Environment > 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 Administration > Integration > 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 for detailed terminology and protocol explanations.
2. Configure SSO: See Single Sign-On Management for step-by-step configuration instructions.
3. Manage certificates: See Certificate Management for storing SAML certificates.
4. Assign roles: See Express Role Administration (Express) or Creator Role Administration (Designer).