# 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 <support@valohai.com>)

## 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 <support@valohai.com> 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 <support@valohai.com>

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](https://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 <support@valohai.com> 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 <support@valohai.com> 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 <support@valohai.com> 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 <support@valohai.com>
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 <support@valohai.com> 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](/observability/audit-log.md) 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 <support@valohai.com> to disable email/password login entirely

## Related Topics

* [Azure AD SSO](/user-and-organization-management/single-sign-on/azure-ad.md) — Alternative SSO provider
* [Create Teams](/user-and-organization-management/getting-started/create-teams.md) — Set up teams for automatic assignment
* [Invite Users](/user-and-organization-management/getting-started/invite-users.md) — Manual user management (alternative to SSO)
* [FAQ](/user-and-organization-management/getting-started/faq.md) — Common SSO questions


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.valohai.com/user-and-organization-management/single-sign-on/okta-saml.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.