Setting Up Okta for SSO in Designer (SAML)

This guide walks you through configuring Okta as a SAML 2.0 identity provider for Designer SSO in Unqork. Okta is an enterprise identity and access management service that provides authentication, authorization, and user directory services. By configuring Okta as an SSO provider, Creators can authenticate through your organization's existing Okta directory instead of managing separate Unqork credentials.

This guide covers Designer SSO. For Express SSO, the configuration steps are similar but use the Express domain instead of Designer.

Prerequisites

Before you begin, ensure you have:

In Okta:

• An Okta account with administrator privileges.
• Access to create and configure SAML applications.
• At least one test user in your Okta directory.

In Unqork:

• Administrator access to the Unqork environment.
• Access to Administration > Environment > Single Sign-On (SSO).
• Understanding of Creator roles and permissions in Unqork.

Knowledge:

• Basic familiarity with Okta application management.
• Understanding of SAML 2.0 authentication flow.
• Awareness of which Creator role to assign as the default for SSO users.

How Settings Map Between Okta and Unqork

Understanding the mapping between Okta configuration and Unqork SSO settings helps streamline the setup process.

SAML Configuration Fields

User Attribute Mappings

Note: Okta uses simple attribute names in SAML assertions. The Name ID typically contains the user's email address and serves as the primary identifier.

Setting Up Okta

Step 1: Create a SAML Application

1. Sign in to your Okta Admin Console.
2. Navigate to Applications > Applications.
3. Click Create App Integration.
4. Select SAML 2.0 as the sign-in method.
5. Click Next.

General Settings:

1. Enter an App name (for example, Unqork Designer SSO).
2. (Optional) Upload an app logo.
3. Check Do not display application icon to users if you don't want users to see this app in their dashboard.
4. Click Next.

Note: This creates a custom SAML application for your Unqork environment. Okta will guide you through the SAML configuration.

Step 2: Configure SAML Settings

On the Configure SAML page, you'll configure the initial SAML settings. Because Unqork hasn't provided the SP metadata yet, you'll use temporary placeholder values.

SAML Settings:

Single sign on URL:

• Enter a temporary placeholder: https://your-environment.unqork.io/auth/saml/temp.
• Check Use this for Recipient URL and Destination URL (if displayed).
• You will update this later with the actual callback URL from Unqork.

Audience URI (SP Entity ID):

• Enter a temporary placeholder: unqork-designer-temp.
• You will update this later with the actual SP Entity ID from the metadata XML.

Default RelayState:

• Leave blank.

Name ID format:

• Select EmailAddress.
• This matches how Unqork identifies users by email.

Application username:

• Select Email.
• This ensures the Name ID contains the user's email address.

Update application username on:

• Select Create and update.

Attribute Statements (Optional):

Add attribute statements to pass user information to Unqork:

To add an attribute:

1. Click Add Another in the Attribute Statements section.
2. Enter the Name (for example, email).
3. Leave Name format as Unspecified.
4. Enter the Value (for example, user.email).

Click Next

Note: These temporary values let you complete the initial configuration. You will replace them after configuring SSO in Unqork and downloading the SP metadata XML.

Step 3: Complete the Application Setup

On the Feedback page:

1. Select I'm an Okta customer adding an internal app.
2. (Optional) Select This is an internal app that we have created.
3. Click Finish.

Okta creates the application and displays the application settings page.

Step 4: Assign Users or Groups

Before testing, assign at least one user to the application:

1. In your application, navigate to the Assignments tab.
2. Click Assign > Assign to People or Assign to Groups.
3. Click Assign next to the test user or group.
4. (Optional) Verify the user's Name ID and attributes.
5. Click Save and Go Back.
6. Click Done.

Note: Only assigned users can authenticate through this SSO configuration.

Step 5: Note Your Configuration Values

Gather the following values to use in Unqork:

1. In your application, navigate to the Sign On tab.
2. Scroll to the SAML 2.0 section.
3. Click View SAML setup instructions.

This opens a new page with the SAML configuration values.

Identity Provider Single Sign-On URL (Entry Point):

• Copy the URL from the instructions page.
• Format: https://your-company.okta.com/app/your-app-id/sso/saml.

Identity Provider Issuer:

• Copy the issuer URL.
• Format: http://www.okta.com/your-issuer-id.

X.509 Certificate:

• Copy the certificate text (without the BEGIN/END lines) or download the certificate.
• You can also download the certificate by clicking Download certificate on the Sign On tab.

Identity Provider metadata:

• Copy the metadata URL if available, or save the XML content.
• This URL provides all configuration values in one file.

Keep these values accessible: You will paste them into the Unqork SSO configuration form.

Setting Up Okta as a SAML Configuration in Single Sign-On (SSO) Management

Step 1: Navigate to SSO Management

Navigate to Administration > Environment > Single Sign-On (SSO) in the Unqork IDE.

1. Click Add SSO Configuration and select Designer.
2. On the configuration form, select SAML as the protocol.

Step 2: Configure Basic Information

SSO Name:

• Enter a unique name (for example, Okta Designer).
• This name identifies the configuration in Unqork and is used in the callback URL.

Default Role:

• Select a Creator role to assign to users who authenticate through Okta.
• Common choice: Environment:BASIC (basic Creator access with view permissions).
• Important: This role determines the user's environment-level permissions for creating and managing resources.

Step 3: Configure SAML Protocol Settings

IdP Metadata XML:

You have two options to provide the Identity Provider metadata:

Option 1: Upload Metadata XML (Recommended)

1. Click Upload Metadata.
2. Enter the Identity Provider metadata URL from Okta (if available).
3. Click Fetch.
4. Unqork retrieves and parses the metadata automatically.
5. Verify that Entry Point and Certificate fields populate.

Option 2: Manual Configuration

1. Leave IdP Metadata XML blank.
2. Manually enter Entry Point, Certificate, and other fields (see below).

Entry Point:

• If using metadata upload, this auto-populates.
• If manual, paste the Identity Provider Single Sign-On URL from Okta.
• Format: https://your-company.okta.com/app/your-app-id/sso/saml.

Certificate:

• If using metadata upload, this auto-populates.
• If manual, paste the full certificate contents from Okta.
• Include -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----.
• If the Okta certificate doesn't include these headers, add them manually.

Identifier Format:

• Select urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress.
• This matches Okta's Name ID format configuration.

Callback URL:

• Unqork provides a default callback URL pattern: https://<host>/auth/saml/consume?idp=<name>.
• You can use the default or enter a custom value.
• Copy this URL to add to Okta later (for example, https://your-environment.unqork.io/auth/saml/consume?idp=okta).

Step 4: Configure Attribute Mappings

Attribute mappings connect Okta user attributes to Unqork user attributes.

Default mappings:

1. Email mapping:.

   • Claim: email.
   • Attribute: email.
   • This populates the user's email address.

2. First name mapping (Optional):.

   • Claim: firstName.
   • Attribute: firstName.
   • This populates the user's first name.

3. Last name mapping (Optional):.

   • Claim: lastName.
   • Attribute: lastName.
   • This populates the user's last name.

To add a mapping:

1. Click Add Mapping.
2. In the Claim field, enter the attribute name (for example, email).
3. In the Attribute drop-down, select the Unqork attribute.
4. Repeat for each attribute you want to map.

Available Unqork attributes:

• email: User email address
• name: User display name
• firstName: User first name
• lastName: User last name

Match Attribute:

• Select email as the match attribute.
• This determines how Unqork identifies returning users.
• Recommendation: Use email for Designer SSO as it is stable and unique in Okta.

Require User Exists:

• Leave unchecked to create new Designer users automatically on first login.
• Check this if only pre-existing Unqork Designer users are permitted to authenticate.

Step 5: Configure Advanced Settings (Optional)

Use HTTP-POST Binding:

• Leave checked (default).
• Okta requires POST binding for assertions.

Use Signed AuthnRequest:

• Leave unchecked unless Okta requires signed authentication requests.
• Signing is optional for Okta.

Expect Encrypted Assertions:

• Leave unchecked unless you configure assertion encryption in Okta.
• Okta supports encryption but does not require it by default.

Disable Requested AuthnContext:

• Leave unchecked.
• Okta supports AuthnContext in SAML requests.

Step 6: Save the Configuration

1. Review all settings.
2. Click Save Changes.
3. Unqork creates the SSO configuration and displays the message: "SSO configuration created successfully.".

After saving, Unqork generates the SP metadata XML file. You will use this file to update the configuration in Okta.

Providing Okta With SP Metadata XML

After saving the SSO configuration in Unqork, you must update Okta with the Service Provider (SP) metadata. This resolves the circular dependency where Okta needs the callback URL and Unqork needs the IdP metadata.

Step 1: Download the SP Metadata XML from Unqork

Navigate to Administration > Environment > Single Sign-On (SSO) in the Unqork IDE.

1. Locate your Okta Designer configuration.
2. Click the three-dot menu for the configuration.
3. Select Download Metadata.
4. Save the metadata.xml file.

This file contains the SP Entity ID and Assertion Consumer Service URL that Okta requires.

Step 2: Extract Values from the Metadata XML

Open the metadata.xml file in a text editor and locate the following values:

SP Entity ID:

• Found in the <EntityDescriptor> tag's entityID attribute.
• Format: https://your-environment.unqork.io/auth/saml/metadata.xml?idp=okta.

Assertion Consumer Service URL:

• Found in the <AssertionConsumerService> tag's Location attribute.
• Format: https://your-environment.unqork.io/auth/saml/consume?idp=okta.

Note: You can also manually construct these URLs using the callback URL pattern from the Unqork SSO configuration.

Step 3: Update Okta SAML Settings

1. Return to your Okta Admin Console.
2. Navigate to Applications > Applications.
3. Select your Unqork Designer SSO application.
4. Navigate to the General tab.
5. Scroll to the SAML Settings section.
6. Click Edit.

Replace the placeholder values:

Click Next to reach the Configure SAML page.

Single sign on URL:

• Delete the temporary placeholder.
• Enter the Assertion Consumer Service URL from the metadata XML.
• Example: https://your-environment.unqork.io/auth/saml/consume?idp=okta.

Audience URI (SP Entity ID):

• Delete the temporary placeholder.
• Enter the SP Entity ID from the metadata XML.
• Example: https://your-environment.unqork.io/auth/saml/metadata.xml?idp=okta.

Verify other settings:

• Name ID format: EmailAddress.
• Application username: Email.
• Attribute Statements: Ensure email, firstName, and lastName are configured (if you want those attributes).

Click Next

Click Finish on the Feedback page

Important: The Single sign on URL and Audience URI in Okta must match exactly what displays in the SP metadata XML. Any mismatch will cause authentication to fail.

Step 4: Verify the Configuration

1. Review the SAML Settings section to ensure the Single sign on URL and Audience URI are correct.
2. Verify the Attribute Statements are configured.
3. Navigate to the Assignments tab and verify test users are assigned.
4. Navigate to the Sign On tab and verify the SAML setup displays the correct values.

Testing Your Configuration

Step 1: Access the SSO Preview

Navigate to Administration > Environment > Single Sign-On (SSO) in the Unqork IDE.

1. Locate your Okta Designer configuration.
2. Click the three-dot menu for the configuration.
3. Select Preview.

Doing so opens the Okta login page in a new browser tab.

Step 2: Authenticate with a Test User

1. On the Okta login page, enter the credentials for a test user assigned to the application.
2. Click Sign In.
3. If prompted, complete any multi-factor authentication challenges.
4. Okta authenticates the user and redirects to Unqork.

Step 3: Verify Successful Authentication

After successful authentication:

1. Okta sends a SAML assertion to Unqork.
2. Unqork validates the assertion and creates or updates the user.
3. You should be authenticated in the Unqork Designer interface.

If authentication succeeds:

• You will see the Unqork Designer home page.
• Navigate to Administration > Creator Permissions > Creator (User) Administration to verify the user was created.
• Verify the user has the correct Creator role and permissions.

If authentication fails:

• Review the error message (if displayed).
• Check the browser console for errors.
• Proceed to the Troubleshooting section.

Step 4: Verify User Attributes and Permissions

Navigate to Administration > Creator Permissions > Creator (User) Administration in the Unqork IDE.

1. Search for the test user by email.
2. Click the user to view their details.
3. Verify:
   • Email: Matches the Okta user email.
   • Name: Populated with the Okta user's first and last name (if configured).
   • Role: Assigned the default Creator role from your SSO configuration.

Troubleshooting

Issue: "The SAML SSO request could not be processed. Please contact your administrator for assistance."

Cause: The Single sign on URL or Audience URI in Okta does not match the values in the SP metadata XML.

Solution:

1. In Unqork, view the SSO configuration and copy the exact callback URL.

2. Download the SP metadata XML and note the SP Entity ID.

3. In Okta, navigate to Applications > Your application > General tab.

4. Click Edit in the SAML Settings section.

5. Verify the Single sign on URL matches the callback URL from Unqork exactly.

6. Verify the Audience URI (SP Entity ID) matches the SP Entity ID from the metadata XML exactly.

7. Check for:

   • Query Parameter format (?idp= vs. /idp/).
   • Trailing slashes.
   • HTTP vs. HTTPS.
   • Typos in the domain or path.

8. Save changes in Okta and retry.

Issue: "User is not assigned to the client application"

Cause: The user is not assigned to the Okta application.

Solution:

1. In Okta, navigate to Applications > Your application.
2. Navigate to the Assignments tab.
3. Verify the test user or a group containing the test user is assigned.
4. If not assigned, click Assign > Assign to People or Assign to Groups.
5. Assign the user and click Save and Go Back.
6. Click Done.
7. Retry authentication.

Issue: "SAML assertion validation failed: Certificate verification failed"

Cause: The certificate in Unqork does not match the certificate Okta uses to sign assertions.

Solution:

1. In Okta, navigate to Applications > Your application > Sign On tab.
2. Click View SAML setup instructions.
3. Copy the X.509 Certificate content.
4. In Unqork, edit the SSO configuration.
5. Replace the Certificate field with the certificate from Okta.
6. Ensure you include -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----.
7. If the Okta certificate doesn't include these headers, add them manually:

   -----BEGIN CERTIFICATE-----
   [certificate content]
   -----END CERTIFICATE-----
   

8. Save changes and retry.

Issue: User Not Created on First Login

Cause: Require User Exists is enabled in the Unqork SSO configuration, or attribute mapping is incorrect.

Solution:

1. In Unqork, edit the SSO configuration.
2. Verify Require User Exists is unchecked (for automatic user creation).
3. Verify the Match Attribute is set to email.
4. Verify the email claim mapping exists:
   • Claim: email.
   • Attribute: email.
5. In Okta, verify the Name ID format is set to EmailAddress.
6. In Okta, verify the Application username is set to Email.
7. In Okta, verify the test user has an email address in their profile.
8. Save changes and retry.

Issue: Missing User Attributes After Login

Cause: Attribute mappings are incomplete or attribute statements are not configured in Okta.

Solution:

1. In Unqork, verify attribute mappings are configured:
   • Email: email → email
   • First Name: firstName → firstName (if desired)
   • Last Name: lastName → lastName (if desired)
2. In Okta, navigate to Applications > Your application > General tab.
3. Click Edit in the SAML Settings section.
4. Scroll to Attribute Statements and verify the attributes are configured:
   • email → user.email
   • firstName → user.firstName
   • lastName → user.lastName
5. If missing, add the attribute statements.
6. Click Next and Finish.
7. Retry authentication.

Issue: "Invalid issuer in SAML response"

Cause: The Identity Provider Issuer in the SAML assertion does not match the expected issuer.

Solution:

1. In Okta, navigate to Applications > Your application > Sign On tab.
2. Click View SAML setup instructions.
3. Note the Identity Provider Issuer value.
4. In Unqork, edit the SSO configuration.
5. If you manually entered the IdP metadata, verify the issuer matches.
6. If you uploaded metadata, re-fetch the metadata from Okta to ensure it's current.
7. Save changes and retry.

Issue: Okta Login Prompt Displays But Authentication Never Completes

Cause: Browser is blocking cookies or third-party redirects, or there is a network issue.

Solution:

1. Check the browser console for errors (press F12).
2. Look for CORS errors, cookie blocking messages, or network failures.
3. Try the authentication flow in a different browser or private/incognito window.
4. Verify your network can reach to your Okta domain.
5. Disable browser extensions that block trackers or cookies temporarily.
6. If using a corporate network, verify there are no firewall rules blocking SAML traffic.

Issue: Certificate Expired Error

Cause: The SAML signing certificate in Okta has expired.

Solution:

1. In Okta, navigate to Applications > Your application > Sign On tab.
2. Scroll to the Credentials Details section.
3. Check the certificate expiration date.
4. If expired or expiring soon, generate a new certificate:
   • Click Edit in the Sign-On Options section.
   • Update the certificate settings or contact Okta support.
5. Download the new certificate.
6. In Unqork, edit the SSO configuration and replace the Certificate field.
7. Save changes and retry.

Security Best Practices

Rotate Certificates Before Expiration

Okta SAML certificates expire after a configured period. Set a reminder to rotate certificates before expiration:

1. Generate a new certificate in Okta or contact Okta support.
2. Update the Unqork SSO configuration with the new certificate.
3. Test authentication to verify the new certificate works.
4. Remove or archive the old certificate in Okta.

Use Certificate Management for Multi-Environment Deployments

If you manage multiple Unqork environments (development, staging, production), use Unqork's certificate management feature:

1. Upload certificates to Administration > Integration > Certificate Management.
2. Reference certificates by ID in SSO configurations.
3. Update certificates centrally without editing each SSO configuration.

Enable Signed AuthnRequests for Enhanced Security

For additional security, configure Unqork to sign SAML authentication requests:

1. In Unqork, edit the SSO configuration.
2. Check Use Signed AuthnRequest.
3. Save changes.
4. Download the updated SP metadata XML.
5. In Okta, configure the application to require signed requests (if supported).

Limit User Access with Okta Policies

Use Okta sign-on policies to enforce additional security requirements:

1. In Okta, navigate to Security > Authentication.
2. Create a new sign-on policy targeting your Unqork application.
3. Configure rules:
   • Require multi-factor authentication.
   • Restrict access to specific network zones.
   • Require device compliance.
4. Activate the policy.

Monitor Authentication Activity

Okta provides system logs for monitoring authentication attempts:

1. In Okta, navigate to Reports > System Log.

2. Filter by your Unqork application.

3. Monitor for the following:

   • Failed sign-in attempts (potential brute-force attacks).
   • Sign-ins from unexpected locations.
   • High volume of authentication errors.

Use Groups for Role Mapping

Instead of assigning Creator roles individually, use Okta groups and role mappings:

1. Create groups in Okta (for example, Unqork Developers, Unqork Admins).
2. Assign groups to the application.
3. In Unqork, configure role mappings to grant Creator roles based on group membership.
4. Manage user access by adding or removing users from groups in Okta.

Advanced Configuration

Mapping Okta Groups to Creator Roles

To assign different Creator roles based on Okta group membership:

1. In Okta, navigate to Applications > Your application > General tab.
2. Click Edit in the SAML Settings section.
3. Scroll to Group Attribute Statements.
4. Add a group attribute statement:
   • Name: groups.
   • Name format: Unspecified.
   • Filter: Select filter type (for example, Starts with or Matches regex).
   • Filter value: Enter the group name pattern (for example, Unqork).
5. Click Next and Finish.

This adds a groups attribute to the SAML assertion containing the user's group names.

6. In Unqork, edit the SSO configuration.
7. Under Role Mappings, click Add Role Mapping.
8. Configure the mapping:
   • Claim: groups.
   • Value: The exact group name from Okta (for example, Unqork Admins).
   • Role: Select the Creator role to grant (for example, Environment:Admin).
9. Repeat for each group-to-role mapping.
10. Save the SSO configuration.

Note: The group attribute statement can send multiple groups in a single claim. Unqork will evaluate each group value against the role mappings.

Using Custom Attributes

To pass custom user attributes from Okta to Unqork:

1. In Okta, navigate to Applications > Your application > General tab.

2. Click Edit in the SAML Settings section.

3. Scroll to Attribute Statements.

4. Add a custom attribute statement:

   • Name: Choose a custom name (for example, department).
   • Name format: Unspecified.
   • Value: Select the Okta user attribute (for example, user.department).

5. Click Next and Finish.

6. In Unqork, add an attribute mapping:

   • Edit the SSO configuration.
   • Click Add Mapping.
   • Claim: The custom attribute name (for example, department).
   • Attribute: Map to a Unqork user attribute if available, or store as custom data.

Note: Unqork supports a limited set of user attributes. Custom claims may require additional configuration or custom workflows to store and use.

Next Steps

After successfully configuring Okta for Designer SSO:

1. Test with multiple users: Verify that different users authenticate correctly and receive appropriate Creator roles.
2. Configure role mappings: If users should receive different Creator roles based on Okta groups, configure advanced role mappings.
3. Document the configuration: Maintain a record of the SSO setup, including certificate expiration dates and group mappings, for your team and future administrators.
4. Set up monitoring: Configure alerts for certificate expiration and monitor Okta system logs for authentication failures.
5. Plan certificate rotation: Schedule certificate rotation before the current certificate expires.