Setting Up Okta for SSO in Express (SAML) - Unqork platform

This guide walks you through configuring Okta as a SAML 2.0 identity provider for Express SSO in Unqork. Okta is a cloud-based identity and access management platform that provides authentication, authorization, and user management for applications. By configuring Okta as an SSO provider using SAML, end-users of your Unqork applications can authenticate through your organization's Okta identity platform instead of managing separate Unqork credentials.

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

Prerequisites

Before you begin, ensure you have:

In Okta:

• An Okta account with administrator access.
• Permissions to create and configure applications in Okta.
• An Okta tenant (organization) with at least one test user.

In Unqork:

• Administrator access to the Unqork environment.
• Access to Administration > Environment > Single Sign-On (SSO).
• Access to Administration > Integration > Certificate Management.
• At least one Express Role created in Express Role Administration.

Knowledge:

• Basic familiarity with Okta application configuration.
• Understanding of SAML 2.0 authentication flow.
• Awareness of which Unqork Express Role to assign as the default for SSO users.

How Settings Map Between Okta and Unqork

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

SAML Configuration Fields

User Attribute Mappings

Note: Okta uses standard SAML claims. The NameID claim contains the user's Okta username or email by default, which serves as a unique identifier. Use NameID as the match attribute for reliable user matching.

Setting Up Okta

Step 1: Sign In to Okta Admin Console

1. Navigate to your Okta Admin Console.
   • URL format: https://your-company-admin.okta.com or https://your-company.okta.com/admin.
2. Sign in with administrator credentials.

Step 2: Create a New SAML Application

1. In the Okta Admin Console, navigate to Applications > Applications.
2. Click Create App Integration.

Configure the integration:

Sign-in method:

• Select SAML 2.0.

3. Click Next.

Step 3: Configure General Settings

App name:

• Enter a descriptive name (for example, Unqork Express SSO).
• This name displays in the Okta dashboard.

App logo (Optional):

• Upload a logo if desired (displays in Okta End-User Dashboard).

App visibility:

• Check Do not display application icon to users if you don't want the app to appear in the Okta End-User Dashboard.
• Leave unchecked if users should see the app icon.

4. Click Next.

Step 4: Configure SAML Settings

At this point, you have two options:

Option A: Use Placeholder Values

Enter temporary placeholder values for Single sign on URL and Audience URI:

• Single sign on URL: https://your-environment.unqork.io/placeholder.
• Audience URI (SP Entity ID): https://unqork-placeholder.
• You'll update these later with the actual values from Unqork's SP metadata.

Option B: Wait to Configure

• Skip SAML Settings for now.
• Click Next and finish the app creation.
• Configure Unqork SSO first, then return to complete this section.

Why placeholder values: Okta requires these fields before you can access the IdP metadata. Unqork generates the correct values when you create the SSO configuration, creating a circular dependency. Using placeholders breaks this cycle.

SAML Settings (if using placeholders or final values):

Single sign on URL:

• Enter the Assertion Consumer Service (ACS) URL.
• Placeholder: https://your-environment.unqork.io/placeholder.
• Final format: https://your-environment.unqork.io/auth/saml/consume?idp={name}.

Audience URI (SP Entity ID):

• Enter the Service Provider entity ID.
• Placeholder: https://unqork-placeholder.
• Final format: https://your-environment.unqork.io or custom entity ID.

Default RelayState:

• Leave blank unless you need a custom relay state.

Name ID format:

• Select EmailAddress or Unspecified.
• Common choice: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress.

Application username:

• Select Email or Okta username.
• This determines the value of the NameID claim.

Attribute Statements (Optional):

• Leave blank for now.
• You can add custom attribute mappings later.

Group Attribute Statements (Optional):

• Leave blank for now.
• Configure later if you need to map Okta groups to Express roles.

5. Click Next.

Step 5: Configure Feedback

Are you a customer or partner?

• Select I'm an Okta customer adding an internal app.

App type:

• Select This is an internal app that we have created.

6. Click Finish.

Step 6: Download IdP Metadata

After creating the application:

1. In your Okta application, click the Sign On tab.
2. In the SAML 2.0 section, locate Metadata URL.
3. Right-click the Metadata URL link and copy the link address.

Option A: Download XML directly

• Open the metadata URL in a browser.
• Save the XML file (File > Save Page As).
• Keep this file accessible for configuring Unqork.

Option B: Copy metadata values manually

If you prefer to configure without the full XML file:

1. Click View Setup Instructions.
2. Note these values:
   • Identity Provider Single Sign-On URL: The SAML SSO endpoint.
   • Identity Provider Issuer: The IdP entity ID.
   • X.509 Certificate: Download or copy the certificate.

Step 7: Assign Users or Groups to the Application

1. In your Okta application, click the Assignments tab.
2. Click Assign > Assign to People or Assign to Groups.
3. Select the users or groups who should have access to Unqork.
4. Click Assign for each user or group.
5. Click Done.

Note: Only users assigned to the Okta application can authenticate through SAML SSO.

Configuring SSO in Unqork

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 Express.
2. On the configuration form, select SAML as the protocol.

Step 2: Configure Basic Information

SSO Name:

• Enter a unique name (for example, Okta Express).
• This name identifies the configuration in Unqork.

Default Role:

• Select an Express Role to assign to users who authenticate through Okta.
• Common choice: Create a role like Authenticated User with appropriate permissions.
• Important: Users will receive this role automatically on first login.

Default Groups (Optional):

• Select any Express Groups to assign to SSO users.
• Leave blank if you don't use groups.

Step 3: Upload or Configure IdP Metadata

Option A: Upload IdP Metadata XML (Recommended)

1. Click Upload Metadata or the file upload field.
2. Select the IdP metadata XML file you downloaded from Okta.
3. Unqork parses the XML and auto-populates:
   • Identifier Format: The NameID format from the metadata.
   • Entry Point: The SAML SSO URL.
   • Certificate: The X.509 certificate for verifying SAML assertions.

Option B: Manual Configuration

If you prefer to enter values manually:

Identifier Format:

• Enter the NameID format from Okta.
• Default: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress.

Entry Point:

• Paste the Identity Provider Single Sign-On URL from Okta.
• Format: https://your-company.okta.com/app/{app-id}/sso/saml.

Certificate:

• Upload the X.509 certificate from Okta to Certificate Management.
• Select the uploaded certificate from the drop-down.

Step 4: Configure Advanced SAML Settings (Optional)

Issuer (Entity ID):

• Leave blank to use Unqork's default entity ID.
• Optionally specify a custom entity ID if required by your organization.

Callback URL:

• Unqork displays the callback URL (Assertion Consumer Service URL).
• Format: https://your-environment.unqork.io/auth/saml/consume?idp={name}.
• Copy this URL for Step 6.

Use HTTP-POST Binding:

• Check this if your IdP requires HTTP-POST binding instead of HTTP-Redirect.
• Okta supports both, but HTTP-POST is more common for SAML responses.

Use Signed AuthnRequest:

• Check this if Okta requires signed authentication requests.
• Requires uploading a certificate to Unqork for signing requests.

Expect Encrypted Assertions:

• Check this if Okta sends encrypted SAML assertions.
• Requires additional certificate configuration for decryption.

Disable Requested AuthnContext:

• Check this if Okta does not support RequestedAuthnContext in SAML requests.
• Typically not needed for Okta.

Step 5: Configure Attribute Mappings

Attribute mappings connect Okta SAML claims to Unqork user attributes.

Default mappings:

1. User ID mapping:.

   • Claim: {{ NameID }}.
   • Attribute: userId.
   • This maps the SAML NameID (typically username or email) to the Unqork user ID.

2. Email mapping (Optional):.

   • Claim: {{ email }}.
   • Attribute: email.
   • This populates the user's email address from the email attribute statement.

To add a mapping:

1. Click Add Mapping.
2. In the Claim field, enter the claim in template format.
   • For NameID: {{ NameID }}.
   • For attribute statements: {{ email }}, {{ firstName }}, {{ lastName }}.
3. In the Attribute drop-down, select the Unqork attribute.
4. Repeat for each attribute you want to map.

Available Unqork attributes:

• userId: Unique user identifier
• email: User email address
• name: User display name
• phone: User phone number

Match Attribute:

• Select userId or email as the match attribute.
• This determines how Unqork identifies returning users.
• Recommendation: Use userId with the {{ NameID }} claim for stable matching.

Require User Exists:

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

Step 6: Save and Copy SP Metadata

1. Review all settings.
2. Click Save Changes.
3. Unqork creates the SSO configuration and displays the message: "SSO configuration created successfully".
4. After saving, Unqork generates SP (Service Provider) metadata.

Copy SP Metadata URL or XML:

Unqork provides SP metadata in two formats:

Option A: SP Metadata URL

• Unqork displays a metadata URL.
• Format: https://your-environment.unqork.io/auth/saml/metadata.xml?idp={name}.
• Copy this URL to provide to Okta.

Option B: Download SP Metadata XML

• Download the SP metadata XML file from Unqork.
• You'll upload this to Okta in the next section.

Providing Okta With SP Metadata XML

After creating the SSO configuration in Unqork, you must provide Okta with Unqork's Service Provider metadata to complete the trust relationship.

Step 1: Return to Okta Admin Console

1. Navigate to Applications > Applications.
2. Click your application (for example, Unqork Express SSO).
3. Click the General tab.

Step 2: Update SAML Settings

1. In the SAML Settings section, click Edit.
2. Click Next to skip General Settings.
3. Update the SAML Settings section.

Option A: Enter Values from SP Metadata

Single sign on URL:

• Enter the callback URL from Unqork.
• Format: https://your-environment.unqork.io/auth/saml/consume?idp={name}.
• Example: https://your-environment.unqork.io/auth/saml/consume?idp=okta-express.

Audience URI (SP Entity ID):

• Enter Unqork's entity ID from the SP metadata.
• Format: https://your-environment.unqork.io or custom entity ID.

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

4. Click Next.
5. Click Finish.

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 SAML configuration in the Express tab.
2. Click the three-dot menu for the configuration.
3. Select Preview.

Doing so opens the Okta-hosted 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 in your Okta organization.
2. Click Sign In.
3. If this is the user's first login, Okta may prompt for:
   • MFA enrollment (if required by your Okta policies).
4. Complete any required prompts.

Step 3: Verify Successful Authentication

After successful authentication:

1. Okta generates a SAML assertion.
2. Okta posts the assertion to Unqork's callback URL.
3. Unqork validates the assertion and authenticates the user.
4. You should be authenticated in the Unqork environment.

If authentication succeeds:

• You'll see the Unqork interface.
• Navigate to Administration > Environment > User Management to verify the user was created.
• Verify the user has the correct default role and attributes.

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

1. Navigate to Administration > Environment > User Management.
2. Search for the test user by email or username.
3. Click the user to view their details.
4. Verify:
   • Email: Matches the Okta user email.
   • User ID: Populated with the NameID value (typically username or email).
   • Role: Assigned the default role from your SSO configuration.
   • Groups: Assigned default groups (if configured).

Troubleshooting

Issue: "The SAML response signature validation failed" Error

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

Solution:

1. In Okta, navigate to your application > Sign On tab.
2. In the SAML Signing Certificates section, verify the correct certificate is active.
3. Click Actions > Download certificate for the active certificate.
4. In Unqork, navigate to Administration > Integration > Certificate Management.
5. Upload the new certificate.
6. Edit the SSO configuration and select the updated certificate.
7. Save changes and retry.

Issue: "The ACS URL does not match" Error

Cause: The Single sign on URL in Okta does not match Unqork's callback URL.

Solution:

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

2. In Okta, navigate to your application > General tab > SAML Settings > Edit.

3. Verify the Single sign on URL matches the Unqork callback URL exactly.

4. Check for:

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

5. Save changes in Okta and retry.

Issue: "The Audience URI does not match" Error

Cause: The Audience URI (SP Entity ID) in Okta does not match Unqork's entity ID.

Solution:

1. In Unqork, check the entity ID in the SP metadata or SSO configuration.
2. In Okta, navigate to your application > General tab > SAML Settings > Edit.
3. Verify the Audience URI (SP Entity ID) matches Unqork's entity ID.
4. Update the value if needed.
5. 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 userId or email.
4. Verify the corresponding claim mapping exists:
   • If match attribute is userId, ensure {{ NameID }} maps to userId.
   • If match attribute is email, ensure {{ email }} maps to email.
5. 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:
   • {{ NameID }} → userId
   • {{ email }} → email (if needed)
2. In Okta, navigate to your application > General tab > SAML Settings > Edit.
3. In the Attribute Statements (optional) section, add attribute statements:
   • Name: email.
   • Name format: Unspecified.
   • Value: user.email.
4. Save changes in Okta.
5. Test with a user who has those attributes populated in Okta.
6. Verify the attribute displays in the SAML assertion in browser developer tools.

Issue: "The certificate is expired or not yet valid" Error

Cause: The X.509 certificate used to sign SAML assertions has expired or the system clock is incorrect.

Solution:

1. In Okta, navigate to your application > Sign On tab.
2. Check the SAML Signing Certificates section for expired certificates.
3. If the active certificate is expired:
   • Click Actions > Generate new certificate for a new certificate.
   • Set the expiration date (default is 2 years).
   • Click Generate.
   • Click Actions > Activate on the new certificate.
   • Download the new certificate.
4. Upload the new certificate to Unqork's Certificate Management.
5. Update the SSO configuration to use the new certificate.
6. Retry authentication.

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

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

Solution:

1. In Okta, navigate to your application.
2. Click the Assignments tab.
3. Verify the user is listed.
4. If not, click Assign > Assign to People.
5. Search for the user and click Assign.
6. Click Done.
7. Retry authentication.

Issue: NameID Format Mismatch

Cause: The NameID format in the SAML request does not match what Okta is configured to send.

Solution:

1. In Okta, navigate to your application > General tab > SAML Settings > Edit.
2. Note the Name ID format value.
3. In Unqork, verify the Identifier Format matches the Okta format.
4. Common formats:
   • urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
   • urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
   • urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
5. Update the Unqork configuration if needed and retry.

Security Best Practices

Rotate SAML Signing Certificates Regularly

Okta SAML signing certificates can be rotated for security:

1. Monitor certificate expiration dates in SAML Signing Certificates section.
2. Before expiration, generate a new certificate in Okta.
3. Download the new certificate and upload to Unqork.
4. Update the Unqork SSO configuration to use the new certificate.
5. Test authentication with the new certificate.
6. After confirming it works, deactivate the old certificate in Okta.

Recommendation: Set calendar reminders 30 days before certificate expiration.

Use Signed AuthnRequest

Enable signed authentication requests for enhanced security:

1. Upload a signing certificate to Unqork's Certificate Management.
2. In the Unqork SSO configuration, check Use Signed AuthnRequest.
3. Select the signing certificate.
4. In Okta, signed requests are accepted by default (no configuration needed).

Require Encrypted Assertions

For sensitive environments, require encrypted SAML assertions:

1. Upload an encryption certificate to Unqork's Certificate Management.
2. In the Unqork SSO configuration, check Expect Encrypted Assertions.
3. Select the encryption certificate.
4. In Okta, configure assertion encryption (requires Advanced Settings).

Assign Users and Groups Explicitly

Always use Okta's Assignments feature to control which users can access Unqork through SSO:

• Assign users individually for fine-grained control.
• Assign groups for easier management of large user populations.
• Review assignments regularly and remove users who no longer need access.

Enable MFA in Okta

Require multi-factor authentication for all users authenticating through Okta:

1. Navigate to Security > Authentication Policies.
2. Create or edit a policy.
3. Add a rule that requires MFA for your Unqork application.
4. Choose MFA factors (Okta Verify, SMS, hardware tokens).
5. Save and apply the policy.

Monitor Sign-In Logs

Okta provides detailed logs for SAML authentication attempts:

1. Navigate to Reports > System Log.

2. Filter by application to see SSO authentication events.

3. Monitor for the following:

   • Failed login attempts.
   • Unusual sign-in locations or times.
   • SAML assertion validation failures.

4. Configure alerts for suspicious activity.

Use Session Policies

Configure session lifetime and re-authentication policies:

1. Navigate to Security > Authentication Policies.
2. Configure session timeout and idle timeout.
3. Set maximum session lifetime for sensitive applications.
4. Require re-authentication after a period of inactivity.

Advanced Configuration

Mapping Okta Groups to Express roles

If you want to assign different Express roles based on Okta group membership:

1. In Okta:.

   • Navigate to your application > General tab > SAML Settings > Edit.
   • In the Group Attribute Statements (optional) section, add a group statement:
     • Name: groups.
     • Name format: Unspecified.
     • Filter: Choose groups to include (for example, Matches regex: .*).
   • Save the configuration.

2. In Unqork:.

   • Add an attribute mapping:
     • Claim: {{ groups }} or for first group: {{ groups[0] }}.
     • Attribute: Custom attribute for role mapping logic.
   • Note: Advanced role mapping based on groups may require custom implementation.

Custom NameID Format

If your organization requires a specific NameID format:

1. In Okta, navigate to your application > General tab > SAML Settings > Edit.
2. Change the Name ID format to your required format:
   • Email address: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress.
   • Persistent: urn:oasis:names:tc:SAML:2.0:nameid-format:persistent.
   • Unspecified: urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified.
3. Change the Application username if needed (Email, Okta username, Custom expression).
4. Save the configuration.
5. Update the Unqork SSO configuration to match the new NameID format.

Custom Attribute Statements

If your organization uses custom attributes in Okta user profiles:

1. In Okta, ensure custom attributes are populated in user profiles.
2. Navigate to your application > General tab > SAML Settings > Edit.
3. In the Attribute Statements (optional) section, add custom statements:
   • Name: Custom attribute name.
   • Name format: Unspecified.
   • Value: Okta user profile attribute (for example, user.department).
4. Save the configuration.
5. In Unqork, add a mapping for the custom attribute.

Next Steps

After successfully configuring Okta SAML SSO for Express:

1. Test with multiple users: Verify that different users authenticate correctly and receive appropriate roles.
2. Enable MFA: Configure authentication policies in Okta for enhanced security.
3. Set up group-based role assignment: Map Okta groups to different Express roles (if needed).
4. Update application modules: Ensure your Unqork applications reference the correct Express roles for RBAC.
5. Document the configuration: Maintain a record of the SSO setup, including certificate expiration dates.
6. Set up monitoring: Configure alerts for failed authentications and certificate expiration.