Connecting Spark to Okta: An Integration Guide

• Single Sign-On to Spark with Okta (OpenID Connect) — SP-initiated sign-in from Spark plus a Spark tile on the Okta End-User Dashboard (IdP-initiated).

• User import into Okta from Spark (SCIM 2.0, import direction) — Spark is the source of truth for employee profiles; Okta reads them in. Okta does not write back to Spark.

• An Okta administrator account.
• A Spark tenant with administrator access. Your Spark workspace URL looks like https://{workspace}.spark.work.
• A Spark user must already exist for anyone who will sign in via Okta (Spark does not auto-create users on sign-in).

1.1 Request activation 

Email the Spark team to enable the Okta integration for your tenant.

To: contact@spark.work
Subject: Enable Okta integration — {your Spark workspace}
Include: our Spark workspace URL ( https://{workspace}.spark.work ) and your
admin contact.

Template:
Hi Spark team, 
Please enable the Okta integration for our tenant {workspace}
( https://{workspace}.spark.work ).
Admin contact: {name} / {email}.
Thank you!

1.2 Connect from the Marketplace

Once Spark confirms the integration is enabled, a tenant administrator:

• Opens the Spark Marketplace
  https://{workspace}.spark.work/marketplace/integrations.
• Finds the Okta integration and clicks Connect.

This unlocks the SSO and SCIM configuration described below.

2. Supported features

• OIDC Single Sign-On — SP-initiated (from Spark) and IdP-initiated (Okta dashboard tile).
• Import New Users — Okta imports employee profiles from Spark (name, email, phone, job title, department, active status).
• Import Profile Updates — subsequent imports bring profile changes from Spark into Okta.
• Import User Schema — the SCIM user schema is discovered from Spark.
• Profile & Lifecycle Sourcing — Spark is the profile source; deactivation/termination in Spark propagates to Okta on the next import.

Limitations

The following features are not supported:

• Create Users (push new users Okta → Spark) — not supported. 

            Reason: user creation is performed in Spark, the system of record.

• Update User Attributes (push profile changes Okta → Spark) — not supported.

            Reason: profile data is mastered in Spark and flows one way (Spark → Okta).

• Deactivate Users as an outbound push (Okta → Spark) — not supported. 

            Reason: deactivation is sourced from Spark and reflected in Okta on import.

• Import Groups — not supported in the current version. 

            Reason: the first release focuses on user-profile import, where Spark is the system of record; it does not yet publish a SCIM /Groups resource, so Okta cannot import groups from Spark at this time. Group and org-structure membership is managed within Spark. Group import is planned for a future release.

• Group Push (push Okta groups → Spark) — not supported today. 

             Reason: same as above; groups are managed in Spark and this release provides user-profile import only.

3. SP-initiated SSO

With SP-initiated SSO, users start at Spark and authenticate through Okta.

1. The user opens https://{workspace}.spark.work and clicks Sign in with Okta.
2. The user is redirected to Okta to authenticate.
3. On success, Okta returns the user to Spark, signed in.

4. Configuration steps

4.1 Configure Single Sign-On (OIDC)

4.1.1 Add the Spark app from the Okta Integration Network catalog

1. Okta Admin Console → Applications → Browse App Catalog.
2. Search for Spark HR and click Add Integration.
3. Accept the defaults and finish adding the app.
4. Assignments: assign the users/groups who should access Spark. For the dashboard
   tile to appear, the app must be assigned to users and Federation Broker Mode must be OFF (General Settings). With Federation Broker Mode ON, sign-in still works but no tile shows.
5. Open the app's Sign On tab and copy the Client ID and Client secret — you will
   enter them in Spark in the next step.

4.1.2 Enter the SSO credentials in Spark

1.  Go to https://{workspace}.spark.work/admin/domain/integrations/authentication.
2. Add an Okta SSO configuration with:

• Org URL: your Okta org URL, e.g. https://{your-org}.okta.com

Use the org URL, NOT the admin console URL. It must NOT contain -admin(e.g. https://acme.okta.com, never https://acme-admin.okta.com).

• Client ID / Client secret from step 4.1.1 (8).

3. Save

4.2 Configure User Provisioning (SCIM 2.0, import)

Okta imports employee profiles from Spark. Spark remains the source of truth — Okta does
not create or edit users in Spark.

4.2.1 Generate a SCIM bearer token in Spark

1. In Spark, go to https://{workspace}.spark.work/my-settings/integrations/okta-scim
2. Click Generate / Mint token. Copy the token — it is shown once.

       3. You can revoke or rotate this token at any time from the same page.

4.2.2 Configure provisioning in Okta

The SCIM connection details (base URL, authentication mode) are pre-configured in the
catalog app — you only need to provide your API token.

1. In the Spark HR application in Okta, open Provisioning → Integration and click Configure API Integration.
2. Check Enable API integration.
3. Paste the bearer token from step 4.2.1 into the token field.
4. Click Test API Credentials — it should succeed — then Save.

4.2.3 Attributes

How the data flows: on import, Okta fills the app user profile (Directory → Profile

• ✅ default — mapped out of the box, nothing to do.

• ⚠ fix mapping — the app template pre-fills this Okta attribute with the placeholder expression appuser.userName (the login email). Left as-is, the field shows  in email address instead of real data. Replace the Value with the one from the table.

• ✅ Username (login) — work email (also the Spark login). Set on the Sign On tab,
  not in the mapping table.
• ✅ First name (firstName) ← appuser.givenName
• ✅ Last name (lastName) ← appuser.familyName
• ✅ Middle name (middleName) ← appuser.middleName
• ✅ Display name (displayName) ← appuser.displayName — full name ("First Last")

• ✅ Primary email (email) ← appuser.email — work email; Okta matches imported users
  by it.
• ✅ Primary phone (primaryPhone) ← appuser.primaryPhone — the employee's mobile phone.
• ⚠ Mobile phone (mobilePhone) ← set to appuser.primaryPhone (same value as above).
• ⚠ Secondary email (secondEmail) — not supplied by Spark; remove the mapping.

• ✅ Title (title) ← appuser.title — position name of the current job.

• ✅ User type (userType) ← appuser.userType — work type (Full Time / Part Time /
  Contractor / …).
• ✅ Employee number (employeeNumber) ← appuser.employeeNumber — employee external ID
  (customer-supplied identifier).
• ✅ Time zone (timezone) ← appuser.timezone — IANA name, e.g. Europe/Warsaw.
• ✅ Department (department) ← appuser.department — org body assigned to the current
  position.
• ⚠ Organization (organization) ← set to appuser.organization — branch / legal entity
  of the current position.
• ⚠ Division (division) ← set to appuser.division — closest org body of type
  Division up the hierarchy.

• ⚠ ManagerId (managerId) ← set to appuser.managerValue — work email of the
  Direct Manager.
• ⚠ Manager (manager) ← set to appuser.managerDisplayName — full name of the Direct
  Manager.
• ✅  Direct managers ← appuser.directManagers — emails of all Direct Manager
  relations.
  • External name: directManagers · type: string array
  • External namespace: urn:ietf:params:scim:schemas:extension:spark:2.0:User
• ✅  Managers ← appuser.managers — emails of all "Manager"-type relations.
  • External name: managers · type: string array
  • External namespace: urn:ietf:params:scim:schemas:extension:spark:2.0:User
• ✅  Other managers ← appuser.otherManagers — emails of all custom-type relations.
  • External name: otherManagers · type: string array
  • External namespace: urn:ietf:params:scim:schemas:extension:spark:2.0:User

How the values are computed in Spark: 

• Manager / ManagerId are populated only when the employee has exactly one Direct
  Manager (Reporting Structure page). With several Direct Managers both fields stay empty —use directManagers, which always carries the full list. managerId = manager's email is the Okta convention that downstream org-chart tools key on.
• Department vs Team vs Body path: all three derive from the org body selected in the
  employee's position. department and team are its name; bodyPath is the full hierarchy
  path (e.g. Operations/Finance/Payroll), which disambiguates same-named sub-bodies.
• Division walks up the org-body tree from the assigned body (including itself) and
  returns the first body whose type is Division; empty when there is none in the chain.
• Active status is not a mapped attribute: Spark sends active (employment status
  Active/Upcoming → true, otherwise false) and Okta applies it via Profile & Lifecycle
  Sourcing (see 4.2.5).
• Optional values (phone, middle name, division, managers…) are sent only when present in Spark; attributes Spark never supplies (honorifics, cost center, address fields) stay
  Not mapped — leave them as-is.
• Set Apply on: Create and update on every mapped row, so later imports keep Okta in sync with Spark. With Create only, changes made in Spark won't reach already-imported users.

The Spark app supports Import User Schema, so Okta already knows all attributes Spark
provides — including the extended ones (for example employeeNumber, userType, timezone, directManagers, managers, otherManagers). There is no need to create attributes manually.

To add any of them to the app user profile:

1. Okta Admin Console → Directory → Profile Editor → select the Spark app's user profile.
2. Click +Add Attribute. The dialog lists the attributes discovered from Spark's schema — select the ones you need and Save.
3. Run an import (Provisioning → Import → Import Now, or wait for the next scheduled import). Okta populates the added attributes with values from Spark.

4.2.5 Import and lifecycle

1. Provisioning → Import → Import Now (or set an import schedule).
2. Map imported users to Okta accounts (confirm assignments).
3. Deactivation / termination: when an employee is deactivated in Spark, the next import sets active=false. Configure the app's Profile & Lifecycle Sourcing so that "When a user is deactivated in the app" → Deactivate (and the reactivation options). This propagates terminations from Spark into Okta.

Notes & Troubleshooting 
If you encounter any issues during the Okta integration, refer to the table below for common symptoms and their resolutions: