Okta SAML

Connect Valohai to your Okta identity provider using SAML 2.0. Users authenticate with their Okta credentials, and team membership updates automatically based on Okta group assignments.

Prerequisites

• Okta admin account

• ACS URL and Entity ID from Valohai (contact [email protected])

Setup Overview

1. Create SAML 2.0 app integration in Okta

2. Configure SAML settings and attribute mappings

3. Share metadata URL with Valohai

4. Users log in via Okta

Step 1: Create App Integration

1. Log in to your Okta admin dashboard

2. Navigate to Applications → Applications

3. Click Create App Integration

4. Select SAML 2.0

5. Click Next

Step 2: Configure General Settings

App name: Enter a name (e.g., "Valohai ML Platform")

App visibility:

• Enable Do not display application icon to users

• Enable Do not display application icon in the Okta Mobile app

Valohai doesn't support IdP-initiated login (where users start from Okta). Users must initiate login from the Valohai login page.

Click Next to continue.

Step 3: Configure SAML Settings

Basic Settings

Single sign-on URL: Enter the ACS URL provided by Valohai (e.g., https://app.valohai.com/saml/acs/your-org/)

Audience URI (SP Entity ID): Enter the Entity ID provided by Valohai (e.g., https://app.valohai.com/saml/metadata/your-org/)

Name ID format: Select Persistent

Application username: Select Email (recommended)

Attribute Statements

Map Okta user attributes to SAML attributes Valohai expects:

Name	Format	Value
urn:oid:2.5.4.42	URI	user.firstName
urn:oid:2.5.4.4	URI	user.lastName
urn:oid:1.2.840.113549.1.9.1	URI	user.email

Add attribute mappings:

1. Click Add Attribute Statement

2. Enter the name exactly as shown (e.g., urn:oid:2.5.4.42)

3. Select URI as the format

4. Enter the value (e.g., user.firstName)

5. Repeat for all three attributes

Optional: Group Attributes

To enable automatic team mapping based on Okta groups, add group attributes:

Name	Format	Value	Filter
groups	Unspecified	(leave empty)	Matches regex: .*

This sends all Okta group memberships to Valohai. Contact [email protected] to configure which groups map to which Valohai teams.

Click Next after configuring attributes.

Step 4: Feedback

Select feedback options:

• I'm an Okta customer adding an internal app

• This is an internal app that we have created

Click Finish to create the app.

Step 5: Share Metadata URL

After creating the app:

1. In the app's Sign On tab, find the section:

   "Identity Provider metadata is available if this application supports dynamic configuration"

2. Right-click the metadata link

3. Copy the URL (e.g., https://yourcompany.okta.com/app/.../sso/saml/metadata)

4. Email the metadata URL to [email protected]

Valohai will configure your organization using this metadata URL.

Step 6: Assign Users

In Okta, assign users or groups to the Valohai app:

1. Go to the app's Assignments tab

2. Click Assign → Assign to People or Assign to Groups

3. Select users or groups

4. Click Done

Only assigned users can log into Valohai via Okta.

User Login Flow

After Valohai completes configuration:

1. Users navigate to app.valohai.com

2. Click Login with SAML or your organization's SSO button

3. Authenticate using Okta credentials

4. First-time users are automatically added to your Valohai organization

Tell users to use the SSO login button, not email/password login. This ensures they use Okta authentication.

Automatic Team Mapping

Configure team mapping to automatically assign users to Valohai teams based on Okta groups:

Example Configuration

Okta setup:

Group: "ML Engineers"
Members: Alice, Bob, Charlie

Valohai configuration (via support):

Okta group "ML Engineers" → Valohai teams: ml-engineering, production

Result: When Alice logs in via Okta, she's automatically added to "ml-engineering" and "production" teams in Valohai.

Contact [email protected] with your group mappings:

Okta Group Name → Valohai Team Names
-----------------------------------
ML Engineers → ml-engineering, production
Data Scientists → research, experimentation
Platform Team → platform, ops, admins

Advanced Attribute Mapping

Send additional user attributes for sophisticated team assignment:

Custom attributes:

• Department

• Job title

• Cost center

• Project assignments

Configuration:

1. Add custom attribute statements in Okta SAML settings

2. Contact [email protected] with attribute mapping requirements

3. Valohai configures conditional team assignment based on attributes

Example:

If user.department == "Research" → Valohai team: research
If user.department == "Engineering" → Valohai team: engineering
If user.jobTitle contains "Lead" → Valohai team: leadership

Troubleshooting

User Can't Log In

Cause: User not assigned to the Valohai app in Okta.

Fix:

1. Go to Okta admin dashboard

2. Open the Valohai app

3. Go to Assignments tab

4. Assign the user or their group

5. User tries logging in again

SAML Response Error

Cause: Attribute mappings incorrect or missing.

Fix:

1. Verify all three required attributes are configured:

   • urn:oid:2.5.4.42 → user.firstName

   • urn:oid:2.5.4.4 → user.lastName

   • urn:oid:1.2.840.113549.1.9.1 → user.email

2. Ensure format is set to URI for all three

3. Save changes and test login again

User Has No Team Access

Cause: Group-based team mapping not configured, or user not in mapped groups.

Fix:

1. Verify user is in the correct Okta groups

2. Contact [email protected] to confirm group mappings

3. User logs out and logs in again to refresh team membership

Metadata URL Changed

Cause: Okta app was regenerated or settings changed.

Fix:

1. Get new metadata URL from Okta app's Sign On tab

2. Email updated URL to [email protected]

3. Wait for Valohai to update configuration

User Accidentally Created Separate Account

Cause: User used email/password login instead of SSO button.

Fix:

1. User logs in via SAML/SSO (creates correctly-linked account)

2. Contact [email protected] to merge duplicate accounts

Security Best Practices

Assign by groups, not individuals: Manage access by adding/removing users from Okta groups rather than individual assignments.

Enable MFA in Okta: Require multi-factor authentication for all users accessing Valohai.

Review assignments quarterly: Audit which groups and users can access Valohai.

Rotate metadata regularly: Update SAML metadata if you rotate Okta certificates.

Limit admin access: Only grant Valohai admin privileges in access grants to users who need full organizational control.

Monitor login activity: Use Audit Log to track authentication events.

Migration from Email/Password

If your organization currently uses email/password authentication:

1. Set up Okta SAML integration (this guide)

2. Notify users about the change to SSO login

3. Users log in via SSO — Valohai links existing accounts automatically if emails match

4. Optional: Contact [email protected] to disable email/password login entirely

Related Topics

• Azure AD SSO — Alternative SSO provider

• Create Teams — Set up teams for automatic assignment

• Invite Users — Manual user management (alternative to SSO)

• FAQ — Common SSO questions