# Okta SSO

This guide walks you through setting up SAML Single Sign-On between Okta and the platform.

## Prerequisites

- Okta administrator access
- the platform organization administrator access
- Your the platform domain (e.g., `probo.example.com`)
- Access to your DNS settings for domain verification

## Prepare the platform Information

Before configuring Okta, gather these the platform service provider details:

| Field         | Value                                                            |
| ------------- | ---------------------------------------------------------------- |
| **ACS URL**   | `https://your-probo-domain.com/api/connect/v1/saml/2.0/consume`  |
| **Entity ID** | `https://your-probo-domain.com/api/connect/v1/saml/2.0/metadata` |

Replace `your-probo-domain.com` with your actual the platform domain.

## Domain Verification

Before configuring anything else, you must verify domain ownership:

1. Log in to the platform as an organization administrator
2. Go to **Organization Settings** → **Authentication** → **SAML**
3. Click **Verify Domain** (if no configurations exist yet, this option will be available)
4. Copy the provided TXT record value
5. Add a TXT record to your domain's DNS settings:
   ```
   Type: TXT
   Name: _probo-domain-verification.your-company.com
   Value: [Verification token from Probo]
   TTL: 300 (or your DNS provider's default)
   ```
6. Wait for DNS propagation (usually 5-15 minutes)
7. In the platform, click **Complete Verification**
8. If successful, the domain status will show as "Verified"

## Configure Okta

1. Sign in to your [Okta Admin Console](https://your-domain-admin.okta.com)
2. Go to **Applications** → **Applications**
3. Click **Create App Integration**
4. Select **SAML 2.0**
5. Click **Next**
6. Configure the general settings:

   | Field              | Value                        |
   | ------------------ | ---------------------------- |
   | **App name**       | `Probo`                      |
   | **App logo**       | Upload the platform logo (optional) |
   | **App visibility** | Check desired options        |

7. Click **Next**
8. Configure the SAML settings:

   | Field                                              | Value                                                            |
   | -------------------------------------------------- | ---------------------------------------------------------------- |
   | **Single sign on URL**                             | `https://your-probo-domain.com/api/connect/v1/saml/2.0/consume`  |
   | **Use this for Recipient URL and Destination URL** | ☑️ (Check this box)                                              |
   | **Audience URI (SP Entity ID)**                    | `https://your-probo-domain.com/api/connect/v1/saml/2.0/metadata` |
   | **Default Relay State**                            | `[SAML Configuration ID]` (optional - see note below)            |
   | **Name ID format**                                 | `EmailAddress`                                                   |
   | **Application username**                           | `Email`                                                          |

   **Important**: The **Default Relay State** is optional but if you want to support IdP-initiated login flows, it MUST be set to your exact SAML configuration ID (not a placeholder). If set incorrectly, SSO will not work. You'll get this ID after creating the SAML configuration in the platform. You can initially leave this empty and update it later with the exact configuration ID.

9. Add the following attribute statements:

   | Name        | Name format | Value                  |
   | ----------- | ----------- | ---------------------- |
   | `email`     | Unspecified | `user.email`           |
   | `firstName` | Unspecified | `user.firstName`       |
   | `lastName`  | Unspecified | `user.lastName`        |
   | `role`      | Unspecified | `user.role` (optional) |

10. Click **Next**
11. Select **I'm an Okta customer adding an internal app**
12. Set **App type** to: Internal app for employees
13. Click **Finish**
14. Go to the **Sign On** tab of your the platform app
15. Click **View SAML setup instructions**
16. **Save these values** for the platform configuration:
    - **Identity Provider Single Sign-On URL**
    - **Identity Provider Issuer**
    - **X.509 Certificate**
17. Go to the **Assignments** tab
18. Click **Assign** → **Assign to People** or **Assign to Groups**
19. Select users/groups that should have access to the platform
20. Click **Assign** and **Done**

## Configure the platform

1. Log in to the platform as an organization administrator
2. Go to **Organization Settings** → **Authentication** → **SAML**
3. Click **Add SAML Configuration**
4. Configure the basic settings:

   | Field                  | Value              | Notes                            |
   | ---------------------- | ------------------ | -------------------------------- |
   | **Email Domain**       | `your-company.com` | Your organization's email domain |
   | **Enforcement Policy** | `OPTIONAL`         | Recommended for initial setup    |

5. Configure the Identity Provider settings with values from Okta:

   | Field               | Value                                    | Notes                |
   | ------------------- | ---------------------------------------- | -------------------- |
   | **IdP Entity ID**   | `[Identity Provider Issuer]`             | Copy from Okta setup |
   | **IdP SSO URL**     | `[Identity Provider Single Sign-On URL]` | Copy from Okta setup |
   | **IdP Certificate** | `[X.509 Certificate]`                    | Copy from Okta setup |

6. Configure the attribute mappings:

   | Field                    | Value       | Notes                   |
   | ------------------------ | ----------- | ----------------------- |
   | **Email Attribute**      | `email`     | Maps to user email      |
   | **First Name Attribute** | `firstName` | Maps to user first name |
   | **Last Name Attribute**  | `lastName`  | Maps to user last name  |
   | **Role Attribute**       | `role`      | Optional; values `OWNER`, `ADMIN`, `EMPLOYEE`, or `VIEWER` |

7. Configure user settings:

   | Field           | Value     | Notes                                             |
   | --------------- | --------- | ------------------------------------------------- |
   | **Auto Signup** | `Enabled` | Allows new users to sign up automatically via SSO |

8. Click **Save Configuration**
9. **Copy the SAML Configuration ID** that appears after saving (e.g., `saml_config_1a2b3c4d`)

## Update Okta Relay State

Return to Okta to enable IdP-initiated login:

1. Go to your the platform app in Okta Admin Console
2. Click **General** tab → **Edit** SAML Settings
3. In the **Default Relay State** field, enter your SAML configuration ID
4. Click **Next** → **Next** → **Finish**

## Troubleshooting

### "SAML assertion audience mismatch" Error

- **Cause**: Audience URI mismatch between Okta and the platform
- **Solution**: Ensure Audience URI in Okta exactly matches your Entity ID:
  - Should be: `https://your-probo-domain.com/api/connect/v1/saml/2.0/metadata`

### "User not assigned to application" Error

- **Cause**: User not assigned to the platform app in Okta
- **Solution**: Assign user to the application in Okta's Assignments tab

### Attributes Not Mapping

- **Cause**: Incorrect attribute statement names in Okta
- **Solution**: Verify attribute statement names match exactly: `email`, `firstName`, `lastName`

### "Invalid RelayState" Error

- **Cause**: Incorrect Default Relay State configuration
- **Solution**: Ensure Default Relay State is either empty or set to the exact SAML configuration ID from the platform

### Debugging Steps

#### Check Okta System Log

1. Go to Okta Admin Console → **Reports** → **System Log**
2. Filter by application name (the platform)
3. Look for authentication failures and error details

## Advanced Configuration

### Custom Attributes

To map additional Okta user attributes:

1. In Okta, add custom attributes to user profiles
2. Add attribute statements in the SAML app configuration
3. Map these attributes in the platform SAML configuration

### Group-Based Access

Control access using Okta groups:

1. Create groups in Okta for the platform access
2. Assign users to appropriate groups
3. Assign the the platform app to groups instead of individual users
4. Use group filters for fine-grained access control

For detailed troubleshooting and advanced configuration options, see the [SSO Overview](/docs/product/sso/overview) guide.