---
updatedAt: 2026-08-07T01:15:20.000Z
agentTools:
  projectIndex: https://docs.uplynk.com/llms.txt
---

# Uplynk SAML Integration with Okta

Configure Okta for SAML-based single sign-on integration with the Uplynk CMS.

This document helps **Okta administrators** configure **Okta** to integrate with the **Uplynk CMS** using **SAML-based Single Sign-On (SSO)**.

Currently, **SAML/SSO** configuration in Uplynk is completed **in coordination with the Uplynk team**. Customers cannot yet self-service all SSO settings directly in the Uplynk CMS. This guide helps you:

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

This document also includes recommendations for **organizing and managing Okta groups** that control access and map users to roles within Uplynk. These recommendations 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 focuses on 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). Currently, SSO configuration in Uplynk is completed **in coordination with the Uplynk team** rather than through a self-service UI.

The integration flow works as follows:

1. **You configure Okta**

   You create and configure a SAML application in Okta for Uplynk CMS, including the required endpoints and attributes.
2. **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).

   <Callout icon="📘" theme="info">
     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.
   </Callout>
3. **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.
4. **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 handled as expected.

<Callout icon="📘" theme="info">
  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.
</Callout>

# Step-by-Step: Okta Configuration

## 1. Create the Okta OIDC application

1. In the Okta Admin Console, create a new application integration.
2. Select **SAML 2.0** as the sign-in method.
3. Name the app (example: **Uplynk CMS**).
4. Leave unlisted configuration fields at their default values unless explicitly stated otherwise.

## 2. Configure SAML settings (values provided by Uplynk)

Configure the SAML application with the following values:

<Callout icon="📘" theme="info">
  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).
</Callout>

* **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

<Callout icon="✳️" theme="default">
  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.
</Callout>

## 3. Configure attribute statements

**Sign On → Settings:** Uplynk requires the following **SAML attributes** from Okta. Configure these attributes 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)*       |

<Callout icon="📘" theme="info">
  Only include attributes required for Uplynk authentication and authorization.
</Callout>

### 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: <rsmith@example.com>

## 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 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 **only send groups that start with that prefix** (for example, `Uplynk*`) in the SAML assertion.

This provides 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 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.

Uplynk uses this list to:

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

## 6. Assign users/groups for testing

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

<Callout icon="📘" theme="info">
  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.
</Callout>

### First-Time Login via Okta (Important)

For the **initial SSO login,** users must start the flow by selecting 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 select 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.