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 who are preparing their Okta environment for integration with Uplynk.

At this time, OIDC 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 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, make sure 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 that 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 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 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:

You configure Okta

You create and configure an OIDC application in Okta for Uplynk CMS, including the required endpoints and attributes.
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.
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 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:

📘
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).

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 to be sent from Okta. Configure the following expressions exactly as shown:

Name	Expression
`firstname`	user.profile.firstName
`lastname`	user.profile.lastName
`uplynk_email`	user.profile.email.toLowerCase()
`uplynk_username`	(see rules below)

📘
Only include claims required for Uplynk authentication and authorization.

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

In Okta Admin Console, go to Security → API → Authorization Servers.
Select your Authorization Server (commonly default).
Go to Scopes tab and verify openid, email, profile scopes exist.
In Scopes tab, click Add Scope / Create with the following values.
- Name: uplynk
- Display phrase: Access Uplynk
- Description: Used for Uplynk CMS group claims
- User Consent: Implicit
Go to Claims tab, click 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
Go to Access Policies, click 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).
Within the policy just created on the previous step, click Add Rule.
- Rule Name: Uplynk OIDC Login
- Grant Type: Authorization Code Should be the only thing 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 that are intended to grant access to Uplynk. The above configuration was created under this assumption, please 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 customer uplynk_groups claim, which will send 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 configuration on our side.

Client ID/Client Secret

Client ID: Applications → Your Uplynk App → General

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

📘
Follow your company best practices when transferring a client secret.

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

7. Assign users/groups for testing

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

📘
You can complete Step 7 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.