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

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 guide.