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

At this time, OIDC configuration in Uplynk is completed in coordination with the Uplynk team. Customers cannot yet self-service all SSO settings directly in the Uplynk CMS. Instead, 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

In addition to the Okta setup steps, this document 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 OIDC 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, ensure you have:

• Administrator access to your Okta tenant
• Permission to create or manage OIDC applications in Okta
• Permission to configure claims in your Okta Authorization Server
• List of the email domains your users will use to sign in to Uplynk CMS
• List of Okta groups that should map to Uplynk CMS groups
• Secure method for sharing the client secret with Uplynk

What This Guide Covers

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

• Creating the Okta application integration
• Configuring the OIDC sign-in flow
• Setting the required scopes
• Configuring a groups claim
• Assigning users and groups to the application
• Collecting the values Uplynk needs to complete the connection

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 (available in a future release)
• General Okta administration outside of this specific integration
• Deep JWT/OIDC 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 OIDC-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:

1. You configure Okta

   You create and configure an OIDC application in Okta for Uplynk CMS, including the required endpoints and attributes.

2. You provide OIDC related details and supported email domains to Uplynk

   After configuring the Okta application, you share a small set of OIDC values and/or metadata with the Uplynk team (for example: Well-Known URL, Okta Client ID, Okta Client Secret).

   📘

   Uplynk configures the integration using your Okta OIDC discovery document URL typically
   https://{yourOktaDomain}/oauth2/default/.well-known/openid-configuration. In most cases,
   providing the Okta discovery well-known is the fastest path because it includes all the OIDC endpoints
   needed for configuration.

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.

Step-by-Step: Okta Configuration

1. Create the Okta OIDC application

1. In Okta Admin Console, create a new application integration.
2. Select OIDC – OpenID Connect as the sign-in method w/ Web Application as the Application Type. If not explicitly stated, unlisted configuration fields can be left as default.

2. Configure OIDC base settings (values provided by Uplynk)

Configure the OIDC application with the following values:

• App integration name: Uplynk CMS
• Grant type (Core grants): Authorization Code
• Sign-in redirect URI: https://id.uplynk.com/realms/uplynk/broker/{orgAlias}-okta/endpoint
• Sign-out redirect URIs: Remove default, not used
• Assignments: Skip group assignment for now

3. Configure additional Okta Application Settings

General: General Settings

• Proof Key for Code Exchange (PKCE): Checked
• Login initiated by: Either Okta or App
• Application Visibility: Check – Display application icon to users
• Initiate login URI: https://cms.uplynk.com?idp_hint={orgAlias}-okta

Sign On: Token claims

Uplynk requires the following claims from Okta. Configure the following expressions exactly as shown:

Rules: uplynk_username (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:
user.profile.login.toLowerCase()

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: user.profile.login.toLowerCase() + "@your.domain"
-Or- if you have more than one email domain administered by your system…
Use: user.profile.login.toLowerCase() + "@" + user.profile.email.substringAfter("@")

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 Authorization Server (Scopes and Groups Claim)

Authorization Server

1. In Okta Admin Console, go to Security → API → Authorization Servers.
2. Select your Authorization Server (commonly default).
3. Go to the Scopes tab and verify openid, email, profile scopes exist.
4. In the Scopes tab, select Add Scope / Create with the following values:
   • Name: uplynk
   • Display phrase: Access Uplynk
   • Description: Used for Uplynk CMS group claims
   • User Consent: Implicit
5. Go to the Claims tab, select Add Claim / Create with the following values:
   • Name: uplynk_groups
   • Include in token type: ID Token/Always
   • Value type: Groups
   • Filter: Starts with Uplynk
   • Include in: The following scopes: uplynk
6. Go to Access Policies, select Add New Access Policy / Create with the following values:
   • Name: Uplynk Access Policy
   • Description: Policy of Uplynk CMS integration.
   • Assign to: Uplynk CMS (name of the OIDC app created in step 1).
7. Within the policy created in the previous step, select Add Rule:
   • Rule Name: Uplynk OIDC Login
   • Grant Type: Authorization Code should be the only option checked
   • User: Any user assigned to this app
   • The following scopes: openid email profile uplynk

5. Group creation/configuration

Group Naming Convention (Strongly Recommended)

We strongly recommend using a dedicated naming convention for all Okta groups intended to grant access to Uplynk. The above configuration was created under this assumption. Adapt any configurations based on your chosen group naming convention.

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 OIDC/JWT claim token.

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, this was already configured using the custom uplynk_groups claim, which sends groups in the authentication token.

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 OIDC/JWT claim token
• Uplynk only evaluates relevant groups
• Access mapping stays predictable and easy to manage

6. Gather Information to Send to Uplynk

Okta IdP Well-Known URL (Required)

Provide the Okta Well Known URL for your Okta application.

Typically: https://{yourOktaDomain}/oauth2/{authorizationServerId}/.well-known/openid-configuration

Where authorizationServerId is mostly default: https://{yourOktaDomain}/oauth2/default/.well-known/openid-configuration.

This allows Uplynk to automatically configure much of the integration on our side.

---

Client ID/Client Secret

Client ID: Applications → Your Uplynk App → General

Client Secret: Applications → Your Uplynk App → General → Client Credentials

---

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 our multi-tenant environment

7. Assign users/groups for testing

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

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.