Integrating with Okta

This article explains how to connect your Okta org to Valven for single sign-on over SAML 2.0. In Okta, Valven is registered as a SAML 2.0 App Integration.

You'll need administrator access to your Okta org, and permission to change SSO settings in Valven.

Connect Your Application

Visit Settings → Single Sign-On on the Valven sidebar, and open the Okta tab. Every provider tab uses the same layout — a form on the left, and a “Set these in Okta” panel on the right that gives you the Identifier (Entity ID), Reply URL (ACS), and Sign on URL you'll need below.

Create a SAML App Integration

Step 1: In the Okta admin console, go to Applications → Applications → Create App Integration.

Step 2: Choose SAML 2.0 as the sign-in method, click Next, and give the integration a name.

Configure SAML Settings

Fill in the General Settings using the values from the Valven panel:

• Single sign-on URL = Reply URL (ACS)
• Audience URI (SP Entity ID) = Identifier (Entity ID)
• Name ID format = EmailAddress
• Application username = Email

Under Advanced Settings, leave Signed Requests unchecked — Valven does not currently sign its authentication requests:

Click Next, choose “I'm an Okta customer adding an internal app” on the following screen, then Finish.

Add Claims for Email, Name, and Groups

Okta manages custom claims from the app's Sign On tab. Under Attribute Statements, add expressions for email, firstName, and lastName, then add one more for group membership:

Important: this expression only returns groups that are also assigned to this specific application — a group the user belongs to, but that hasn't been assigned to the app, will not appear, and Okta silently omits the groups attribute rather than sending it empty.

Import the Identity Provider Metadata into Valven

On the Sign On tab, find Metadata details and copy the Metadata URL. Open it in your browser, copy the full XML content, and paste it into the Federation metadata XML box on the Valven Okta tab.

Create a Test User, Role, and Assignment

Step 1: Go to Directory → Groups → Create group, and create a group whose name matches a role configured in Valven.

Step 2: Go to Directory → People → Add person and create a test user.

Step 3: Open the group you created and add the test user to it.

Step 4: Go back to the app's Assignments tab, click Assign → Assign to Groups, and assign the same group to the application:

The Assignments → People view shows everyone who currently has access, whether assigned directly or through a group:

If you skip the group-to-application assignment, the group expression from Step 3 will return nothing even though the user is a member — this is the most common cause of missing role information in the SAML response.

Test-Friendly Settings (optional)

Okta's default authentication policy may prompt for a second factor (e.g. Okta Verify) on every sign-in, which can interrupt testing. This is controlled from Security → Authentication Policies, not from the Authenticators/Enrollment screen shown below (that screen only controls which factors are available, not whether they're required for a given app):

Open the policy assigned to your app and adjust the rule's factor requirement — e.g. from “password + another factor” to “password only” — for testing purposes. Revert this before using the configuration in production.

Verifying the Connection

Back in Valven, turn on Single sign-on enabled and Use this provider for sign-in, then click Save Changes. Test SSO Configuration confirms the connection details were read correctly.

From the Valven sign-in page, enter the test user's email address and choose “Sign in with SSO” — you should land on Okta's login screen. Signing in with the test user should bring you back to Valven with the correct name and role.

Common Errors

• “User is not assigned”: the user must be assigned to the application, either directly or (recommended) through a group assignment.
• “Username must be an email” when creating a person: this is an org-wide policy under Security → General, not a per-app setting — look for a username format option there.
• Role or group information doesn't reach Valven: confirm the group is assigned to the application itself, not just to the user.