This document provides guidance for configuring Okta to integrate with the Uplynk CMS using SAML-based Single Sign-On (SSO). It is intended for Okta administrators who are preparing their Okta environment for integration with Uplynk.

At this time, SAML/SSO configuration in Uplynk is completed in coordination with the Uplynk team. Customers are not yet able to self-service all SSO settings directly in the Uplynk CMS. Instead, this guide is designed to help you:

Prepare your Okta configuration in advance
Understand what information and settings Uplynk will need from you
Reduce setup time during working sessions with the Uplynk team
Avoid common configuration and group-mapping issues

In addition to the Okta setup steps, this document includes recommendations for organizing and managing Okta groups that will be used to control access and map users to roles within Uplynk. These recommendations are intended to keep your integration simple, maintainable, and scalable as your organization grows.

By following this guide, you will:

Configure and prepare an Okta SAML application for Uplynk CMS
Have the required information ready for coordination with the Uplynk team
Establish a clear approach for using Okta groups with Uplynk’s access model

Who Should Read This

This guide is intended for:

Okta Administrators responsible for configuring identity integrations
IT or Identity administrators who manage users and groups in Okta
Technical administrators participating in SSO setup working sessions with Uplynk

You should be comfortable navigating the Okta Admin Console and managing applications, users, and groups.

Prerequisites

Before starting, make sure you have:

Administrator access to Okta with permission to create and configure applications
An active Uplynk CMS account and a point of contact with the Uplynk team for SSO setup
Basic familiarity with SAML concepts, such as:
- Identity Provider (IdP) and Service Provider (SP)
- Assertions and attributes
- ACS (Assertion Consumer Service) URLs and Entity IDs
A plan for how you want to organize users and groups in Okta for Uplynk access (this guide includes recommendations)

What This Guide Covers

This guide covers the Okta-side configuration required to enable SAML login to Uplynk CMS, including:

Preparing and configuring the Okta application for Uplynk SAML integration
Collecting the required SAML metadata and configuration details to share with Uplynk
Validating the Okta-side configuration during integration working sessions
Recommended patterns for:
- Structuring Okta groups for Uplynk access
- Mapping users and groups to Uplynk roles
- Keeping your configuration maintainable over time

This guide is written for administrators and focuses on the practical setup steps rather than protocol details.

What This Guide Does Not Cover

Self-service SSO configuration inside the Uplynk CMS (this will be available in a future release)
General Okta administration outside of this specific integration
Deep SAML troubleshooting beyond common configuration issues
Detailed design of Uplynk roles and permissions (only how to integrate with them)

How the Integration Works Today

Uplynk CMS supports SAML-based Single Sign-On (SSO) using Okta as the Identity Provider (IdP). At this time, SSO configuration in Uplynk is completed in coordination with the Uplynk team rather than through a self- service UI.

The current integration flow works as follows:

You configure Okta

You create and configure a SAML application in Okta for Uplynk CMS, including the required endpoints and attributes.
You provide SAML details and supported email domains to Uplynk

After configuring the Okta application, you share a small set of SAML values and/or metadata with the Uplynk team (for example: IdP metadata, Entity ID, and certificate information).

📘
Uplynk configures the integration using your Okta IdP metadata (SAML Entity Descriptor). In most cases, providing the Okta metadata URL is the fastest path because it includes the signing certificate and SAML endpoints needed for configuration.
Uplynk configures the CMS side

The Uplynk team uses the information you provide to complete the Service Provider (SP) configuration on the Uplynk CMS side.
We test the integration together

You and the Uplynk team validate the end-to-end login flow from Okta into Uplynk CMS and confirm that users and groups are being handled as expected.

📘
A self-service SSO configuration experience in Uplynk is planned for a future release. This guide focuses on preparing your Okta configuration and streamlining the current coordination process.

Step-by-Step: Okta Configuration

1. Create the Okta OIDC application

In Okta Admin Console, create a new application integration.
Choose SAML 2.0 as the sign-in method.
Name the app (example: Uplynk CMS).
If not explicitly stated, unlisted configuration fields can be left as default.

2. Configure SAML settings (values provided by Uplynk)

Configure the SAML application with the following values:

📘
Uplynk will provide you with an orgAlias value that identifies your organization. This value is used to construct your Okta configuration URLs when applicable. Replace {orgAlias} with the value provided by Uplynk (do not include the {} braces in the final URL).

Single sign-on URL (ACS URL): https://cms.uplynk.com/?idp_hint={orgAlias}-okta
- Ensure Checked: Use this for Recipient URL and Destination URL
Audience URI (SP Entity ID): https://id.uplynk.com/realms/uplynk
Name ID format: Persistent
Application username: Okta username

Advanced Settings

Assertion Encryption: Encrypted
Encryption Algorithm: AES256-CBC
Key Transport Algorithm: RSA-OAEP
Encryption Certificate: Load provided crt file (rsa_oaep_uplynk.crt)
Other Requestable SSO URLs → +Add Another
- URL: https://id.uplynk.com/realms/uplynk/broker/{orgAlias}-okta/endpoint
- Index: 0

✳️
If you see unexplained upload or save errors in Okta, refresh the page and confirm you are still logged in. Expired sessions can produce misleading validation errors.

3. Configure attribute statements

Sign On → Settings: Uplynk requires the following SAML attributes to be sent from Okta. These attributes must be configured using Okta’s Legacy Attribute Statement configuration (or equivalent logic using Expression Language).

Required Attributes

Configure the following attributes exactly as shown:

Attribute Name	Name Format	Value (Okta Expression)
`email`	Basic	`toLowerCase(user.email)`
`firstname`	Basic	`user.firstName`
`lastname`	Basic	`user.lastname`
`username`	Basic	(see rules below)

📘
Only include attributes required for Uplynk authentication and authorization.

Username Rules (Important)

Uplynk is a multi-tenant system, so usernames must be globally unique across all customers. In addition, usernames must be lowercase.

Choose one of the following options for the username attribute:

Option A: Your usernames are already globally unique (recommended if true)

If your Okta usernames are already globally unique (for example, email addresses or unique IDs), use: toLowerCase(user.login)

Option B: Your usernames are NOT globally unique (for example: rsmith, jsmith, etc.)

If your usernames are short or not globally unique, you must append a domain to make them unique. We recommend using the same domain you use for email addresses.

Use: toLowerCase(String.append(user.login, "@your.domain"))

Example:

If a user’s login is: rsmith

And your domain is: example.com

Then the resulting username sent to Uplynk will be: [email protected]

4. Configure group attribute statements (you must use Okta Groups, which will be configured and mapped to the Uplynk side)

Group Naming Convention (Strongly Recommended)

We strongly recommend using a dedicated naming convention for all Okta groups that are intended to grant access to Uplynk.

Recommended Pattern

Use a consistent prefix, for example:

Uplynk_Admin
Uplynk_Editor
Uplynk_Viewer

In general:

Uplynk_<RoleName>

You may choose a different prefix if needed, but it should be:

Unique to Uplynk
Consistent across all Uplynk-related groups

Why This Matters

Using a dedicated prefix allows Okta to be configured to only send groups that start with that prefix (for example, Uplynk*) in the SAML assertion.

This has several important benefits:

Security:
Only Uplynk-related groups are sent to the application, reducing accidental exposure of unrelated internal group names.
Performance:
Prevents sending and processing every group in your identity system, which can be slow and unnecessary in large organizations.
Reliability:
Reduces the risk of accidental group name collisions or unexpected matches.

How This is Used

On the Okta side, configure the group attribute statement to:

Include only groups that start with your chosen prefix (for example, Uplynk)
Exclude all other groups

Group Attribute Name	Name Format	Filter	Value
`groups`	Basic	Starts with	`Uplynk`

On the Uplynk side:

Each group you want to map must still have a corresponding SSO Hint value that exactly matches the Okta group name, per groups configured in Okta and Uplynk CMS.

Example

If you use the prefix Uplynk, your configuration might include:

Okta groups:

Uplynk_Admin
Uplynk_ReadOnly
Uplynk_Operations

Group filter in Okta:

Starts with: Uplynk

Result:

Only these groups are sent in the SAML assertion
Uplynk only evaluates relevant groups
Access mapping stays predictable and easy to manage

5. Gather Information to Send to Uplynk

Okta IdP Metadata URL (Required)

Provide the SAML IdP Metadata (Entity Descriptor) URL for your Okta application.

This metadata allows Uplynk to automatically configure:

SAML endpoints
Signing certificates
Protocol details required to trust your Okta IdP

In most cases, this is the only artifact needed to establish SAML trust from Okta to Uplynk.

Supported Email Domains for Your Organization (Required)

Provide a list of email domains used by your organization for users who should authenticate into Uplynk.

This list is used by Uplynk to:

Correctly route users to your organization during login
Associate users with the correct tenant in our multi-tenant environment

6. Assign users/groups for testing

Assign at least one test user to an assigned group for the Okta application.

📘
You can complete Step 6 to finish the configuration, however, the integration will not be functional until Uplynk has received and configured the Uplynk side with this information.

First-Time Login via Okta (Important)

For the initial SSO login, users must start the flow by clicking the Uplynk application icon in Okta.

This first launch is required to complete the SSO onboarding and establish the initial account linkage in Uplynk. Once this has been done successfully:

The user does not need to click the Okta application icon for every login
Subsequent logins can use the normal Uplynk login flow or direct links
This step is only required once per user during initial SSO onboarding

If a user attempts to access Uplynk before completing this first Okta-initiated login, they may see an access or authorization error.