Okta Developer Setup Guide: SAML SSO and SCIM Provisioning

This guide walks you through configuring Okta Developer as your Identity Provider (IdP) for CRA Evidence, covering both SAML 2.0 Single Sign-On (SSO) and SCIM 2.0 user provisioning.

---

Overview

What Okta Developer Offers

Okta Developer (https://developer.okta.com/) provides a free tier suitable for testing and small deployments:

For production environments with more users, consider Okta Workforce Identity.

What You Will Configure

When combined, SAML and SCIM provide:

• Single Sign-On: Users authenticate once in Okta to access CRA Evidence
• Automated Provisioning: No manual user creation in CRA Evidence
• Lifecycle Management: Deactivate CRA Evidence access when employees leave
• Centralized Control: Manage all access from your IdP

---

Prerequisites

Before starting, ensure you have:

1. Okta Developer Account

Sign up at https://developer.okta.com/signup/ if you do not have an account:

1. Visit the signup page
2. Enter your email and create a password
3. Verify your email address
4. Note your Okta domain (e.g., dev-123456.okta.com)

2. CRA Evidence Access

• CRA Evidence instance running and accessible (e.g., https://app.craevidence.com or your self-hosted URL)
• Organisation admin access in CRA Evidence
• Professional or Enterprise plan (SSO features require a paid plan)

3. Domain Information

• Your company email domain(s) (e.g., company.com)
• DNS access to add TXT records for domain verification

---

Part 1: SAML SSO Setup

Step 1.1: Gather CRA Evidence SP Information

Before configuring Okta, collect the Service Provider (SP) information from CRA Evidence:

1. Log in to CRA Evidence as an organisation admin
2. Navigate to Settings > Single Sign-On
3. Note the following values:

Replace app.craevidence.com with your actual CRA Evidence domain.

Step 1.2: Create SAML Application in Okta

1. Log in to your Okta Admin Console (https://your-domain.okta.com/admin)
2. Navigate to Applications > Applications in the left sidebar
3. Click Create App Integration
4. Select the following options:
   • Sign-in method: SAML 2.0
5. Click Next

Step 1.3: Configure General Settings

Click Next to proceed to SAML settings.

Step 1.4: Configure SAML Settings

General SAML Configuration

Attribute Statements (Required)

Configure these attribute mappings so CRA Evidence receives user information:

Group Attribute Statements (Optional)

If you want to pass group information:

Click Next to proceed.

Step 1.5: Complete Feedback Section

• Select I'm an Okta customer adding an internal app
• Check This is an internal app that we have created
• Click Finish

Step 1.6: Download IdP Metadata

After creating the application:

1. On the application page, go to the Sign On tab
2. Scroll down to SAML Signing Certificates
3. For the active certificate, click Actions > View IdP metadata
4. Save this metadata URL, or download the XML file

Alternatively, manually note these values:

Step 1.7: Configure CRA Evidence with Okta IdP

1. In CRA Evidence, navigate to Settings > Single Sign-On
2. Click Add Identity Provider
3. Fill in the form:

JIT Provisioning Settings

1. Click Add Identity Provider

Step 1.8: Add and Verify SSO Domain

Link your email domain to the Okta IdP:

1. In CRA Evidence SSO settings, go to the Domains tab
2. Click Add Domain
3. Enter your email domain (e.g., company.com)
4. Select the Okta IdP you created
5. Click Add Domain

Domain Verification

CRA Evidence requires domain ownership verification:

1. After adding the domain, note the verification token displayed
2. Add a DNS TXT record to your domain:

Host: _craevidence-verification.company.com
Type: TXT
Value: craevidence-verify=<your-verification-token>

1. Wait for DNS propagation (typically 5-30 minutes, up to 48 hours)
2. Click Verify Now in CRA Evidence

The domain status will change from "Pending" to "Verified" upon successful verification.

Step 1.9: Assign Users in Okta

Before testing, assign users to the CRA Evidence application:

1. In Okta Admin Console, go to your CRA Evidence application
2. Click the Assignments tab
3. Click Assign and choose either:
   • Assign to People: Select individual users
   • Assign to Groups: Select entire groups (recommended)
4. Click Save and Go Back

Step 1.10: Test SSO Flow

1. Open a new incognito/private browser window
2. Navigate to your CRA Evidence login page (e.g., https://app.craevidence.com/login)
3. Enter an email address from your verified SSO domain
4. Click Continue
5. You should be redirected to Okta's login page
6. Authenticate with your Okta credentials
7. Upon successful authentication, you should be redirected back to CRA Evidence, logged in

If JIT provisioning is enabled and this is your first login, a new user account will be created automatically.

---

Part 2: SCIM Provisioning Setup

SCIM enables automatic user provisioning from Okta to CRA Evidence, eliminating manual user management.

Step 2.1: Enable Provisioning in Okta

1. In Okta Admin Console, go to your CRA Evidence application
2. Click the Provisioning tab
3. Click Configure API Integration
4. Check Enable API Integration

Do not fill in the credentials yet - you need to create a SCIM client in CRA Evidence first.

Step 2.2: Create SCIM Client in CRA Evidence

1. In CRA Evidence, navigate to Settings > SCIM Provisioning
2. Click Add SCIM Client
3. Configure the client:

Provisioning Settings

1. Click Create Client

Important: A bearer token will be displayed only once. Copy and securely store this token immediately. You cannot retrieve it later.

Example token format:

scim_xK9mN2pQ5rT8vW3y...

Step 2.3: Configure SCIM Connector in Okta

Return to Okta and complete the API integration:

1. In the API Integration section, enter:

1. Click Test API Credentials to verify the connection

If the test fails:

• Verify the SCIM client is enabled in CRA Evidence
• Check the bearer token is correct
• Ensure the base URL is correct (no trailing slash)

1. Click Save once the test succeeds

Step 2.4: Configure Provisioning Options

After saving API credentials, additional tabs appear:

To App Settings

Click Provisioning > To App and click Edit:

Click Save.

Attribute Mappings

Click Provisioning > To App then scroll to Attribute Mappings.

Verify these mappings (most should be automatic):

Step 2.5: Assign Users and Groups

Trigger provisioning by assigning users:

1. Go to the Assignments tab
2. Click Assign and select users or groups
3. For each assignment, you can customize attributes (optional)
4. Click Save and Go Back

Okta will automatically provision assigned users to CRA Evidence via SCIM.

Step 2.6: Verify Provisioning

Check that users were created in CRA Evidence:

1. In CRA Evidence, go to Settings > Members
2. Verify the provisioned users appear
3. Check their Provisioned Via field shows "SCIM"

In Okta, check provisioning status:

1. Go to your CRA Evidence application
2. Click Provisioning > To App
3. Scroll down to see Provisioning Troubleshooting or recent operations

---

Part 3: Testing Checklist

Use this checklist to verify your configuration:

SSO Login Flow

• [ ] User with SSO domain email is redirected to Okta from CRA Evidence login
• [ ] After Okta authentication, user is redirected back to CRA Evidence
• [ ] User is logged in and sees their dashboard
• [ ] User attributes (name, email) are correct in CRA Evidence

JIT Provisioning (SAML)

• [ ] New user authenticating via SSO for the first time gets account created
• [ ] New user is assigned the configured default role
• [ ] User's provisioned_via field shows "saml_jit"

SCIM User Sync

• [ ] User assigned in Okta appears in CRA Evidence within minutes
• [ ] User's provisioned_via field shows "scim"
• [ ] User attributes match what is configured in Okta

SCIM User Updates

• [ ] Changing user's name in Okta updates it in CRA Evidence
• [ ] Changing user's email in Okta updates it in CRA Evidence (if allowed)

SCIM User Deactivation

• [ ] Unassigning user in Okta deactivates them in CRA Evidence
• [ ] Deactivated user cannot log in to CRA Evidence
• [ ] User record remains in CRA Evidence (for audit purposes)

Combined SAML + SCIM

• [ ] SCIM-provisioned user can log in via SAML SSO
• [ ] User attributes are consistent between SCIM and SAML assertions

---

Part 4: Troubleshooting

SAML SSO Issues

"Invalid SAML Response" Error

Symptoms: Error message after Okta authentication, user not logged in.

Solutions:

1. Verify the ACS URL matches exactly (including https and no trailing slash)
2. Ensure the X.509 certificate in CRA Evidence matches Okta's active certificate
3. Check the certificate has not expired
4. Verify Name ID format is set to EmailAddress in Okta

"User Not Being Created" (JIT)

Symptoms: User authenticates successfully but no account is created.

Solutions:

1. Confirm JIT Provisioning is enabled in the IdP settings
2. Verify the email attribute statement is configured in Okta
3. Check CRA Evidence logs for attribute parsing errors
4. Ensure the user's email domain matches a verified SSO domain

"Domain Not Configured" Message

Symptoms: User enters email but is not redirected to Okta.

Solutions:

1. Verify the domain is verified (not just added) in CRA Evidence
2. Check domain spelling matches exactly (case-insensitive)
3. Ensure the domain is linked to the correct IdP
4. Wait for DNS propagation if domain was recently verified

Clock Skew Errors

Symptoms: SAML assertion rejected due to timing.

Solutions:

1. CRA Evidence allows up to 2 minutes of clock drift by default
2. Ensure your Okta tenant has accurate time
3. Check server time synchronization if self-hosting CRA Evidence

SCIM Provisioning Issues

401 Unauthorized

Symptoms: Okta test connection fails, no users provisioned.

Solutions:

1. Verify the bearer token is correct (regenerate if unsure)
2. Check the SCIM client is enabled in CRA Evidence
3. Confirm SCIM_ENABLED=true in CRA Evidence configuration
4. Ensure there are no extra spaces in the token

429 Too Many Requests

Symptoms: Provisioning operations fail intermittently.

Solutions:

1. SCIM clients have rate limits (default 1000/hour)
2. Wait for the rate limit window to reset
3. Contact support if you need higher limits

409 Conflict

Symptoms: User creation fails with conflict error.

Solutions:

1. User may already exist with a different external ID
2. Check if user was previously created via JIT provisioning
3. Review SCIM provisioning logs in CRA Evidence for details

User Not Created

Symptoms: Okta shows success but user does not appear in CRA Evidence.

Solutions:

1. Verify userName attribute is a valid email address
2. Check the auto_activate setting in SCIM client
3. Review CRA Evidence SCIM provisioning logs
4. Check Okta provisioning logs for detailed errors

Okta-Specific Issues

Certificate Rollover

Okta periodically rotates signing certificates:

1. Okta sends email notifications before rotation
2. Download the new certificate from Okta
3. Update the certificate in CRA Evidence IdP settings
4. Test login before the old certificate expires

Rate Limiting from Okta Side

If Okta is rate-limited when calling CRA Evidence:

1. Okta will retry with exponential backoff
2. Check Okta System Log for SCIM-related events
3. Monitor CRA Evidence rate limit headers in responses

---

Optional: Advanced Configuration

SSO Enforcement

Once SSO is working reliably, enforce it for all users:

1. In CRA Evidence, go to Settings > Single Sign-On > Enforcement
2. Enable Require SSO for all users
3. Optionally enable Allow admins to bypass SSO (for emergency access)
4. Click Save Settings

With enforcement enabled, password login is disabled for non-admin users.

Multiple Okta Tenants

If you have separate Okta environments (e.g., dev, staging, production):

1. Create separate IdP configurations in CRA Evidence
2. Link different email domains to different IdPs
3. Create separate SCIM clients for each Okta tenant

Linking SCIM Client to SAML IdP

Linking your SCIM client to a SAML IdP provides:

• Unified view in CRA Evidence settings
• Consistent user tracking across SSO and provisioning

To link:

1. When creating or editing a SCIM client, select the SAML IdP in the "Link to IdP" field

---

Support

If you encounter issues not covered here:

1. Review the detailed architecture documentation:

   • SAML SSO Architecture (contact support for details)
   • SCIM Provisioning Architecture (contact support for details)

2. Contact CRA Evidence support:

   • Email: support@craevidence.com
   • Include:
     • Screenshots of error messages
     • Okta application configuration (mask sensitive data)
     • CRA Evidence IdP/SCIM client configuration
     • Relevant log entries

3. For Okta-specific issues:

   • Okta Support: https://support.okta.com/
   • Okta Developer Forums: https://devforum.okta.com/

---

Quick Reference

CRA Evidence URLs

Required Okta Settings

Attribute Mappings

---

Other identity providers

CRA Evidence supports SAML SSO with any compliant identity provider:

• Azure AD / Microsoft Entra
• Google Workspace
• Auth0
• OneLogin
• JumpCloud

Related documentation

• SCIM Provisioning — Automated user management
• Team Management — Manual user management
• Organisation Settings — General configuration