A comprehensive guide to setting up and using the Okta integration to sync users with FMX.

How the Integration Works

The FMX-Okta integration connects your Okta users and Okta-mapped fields to your FMX site. This integration creates, updates, and deletes users according to the user information provided from Okta on a scheduled basis.

User Sync

Okta provides the ability to create application-specific credentials and share selected users and groups with that application. Customers can even choose to create custom fields and map those fields to applications as needed. This integration will connect to the provided credentials and pull the associated users and groups (and their fields) according to your configurations.

Setup Guide for Administrators

This section provides step-by-step instructions for configuring the integration for the first time.

Prerequisites

Before starting the configuration wizard, you must complete the following setup steps in both FMX and Okta.

1. Configure FMX

  • Create a dedicated User Type: Configure a new user type with the required permissions. For more information, see How to Customize User Access. The permissions needed are:
    • Building & Resource Access:
      • Read: Any
    • User & Contact Access:
      • Administer: Checked
      • Read users: Checked
      • Read contacts: Checked
      • Delete: CheckedCreate nee
  • Create a dedicated User: Create a new user and assign it to the user type you just configured. For more information, see Adding and Editing Users & Contacts.
    • Assign an identifiable name (e.g., “Okta Integration”).
    • Use an email address where you want to receive notifications (e.g., “email+okta@domain.com”).
    • Securely document this user’s password for use in the configuration steps.
  • Create needed Custom Fields:
    • Create a custom field called "Okta Id" which will be used to map synced users in FMX to Okta users.
    • If you plan to map other user details from Okta, create these as Custom Fields for Users now.
    • Custom fields must be assigned across all synced FMX User Types to be mapped from Okta and be allowed to be modified by the dedicated sync user.
    • For more information, see Form Builder: How to create custom fields.

2. Create Okta Integration Application

Create the Application

  1. Log in to your Okta Admin Console and go to Applications > Applications.
  2. Click Create App Integration and select API Services. Name it as desired.

Configure General Settings

  1. Click your newly created Application and copy and store the Client ID for later.
  2. Under Client Credentials click Edit and select Public key / Private key.
  3. Click Add Key > Generate new key and click the PEM tab.
  4. Copy and store the private key for later. Click Done, then click Save. Click Save again if prompted.
  5. Under General Settings click Edit and uncheck Require Demonstrating Proof of Possession (DPoP) header in token requests.
  6. Click Save.

Configure Okta API Scopes

  1. Click the Okta API Scopes tab.
  2. Grant the following scopes:
    • okta.apps.read
    • okta.groups.read
    • okta.schemas.read
    • okta.users.read
    • okta.userTypes.read

Configure Admin roles

  1. Click the Admin roles tab.
  2. Click Edit Assignments.
  3. Use the dropdown menus to add the Read-only Administrator role.
  4. Click Save Changes.

Assign Users to the Application

  1. Navigate to Directory > Groups.
  2. Click the group containing users you want to sync to FMX (e.g., "Everyone").
  3. Click the Applications tab, Assign applications, and select your newly created application.

Configuration Wizard

Step 1. Initial Configuration

  1. In FMX, navigate to Admin Settings > Integrations.
  2. Locate the Okta integration and click Reconfigure.
  3. Click Next on the first screen.

Step 2. Okta and FMX Connection

  1. Okta API Connection: Enter the Okta Domain, Client ID, and Private Key (PEM).
    • To determine your Okta domain, sign in to Okta and click the dropdown arrow next to your username in the top right corner. You can copy the domain (e.g., "example.okta.com").
    • The Client ID and Private Key (PEM) were recorded during the prerequisite steps earlier. If you have lost your Private Key (PEM) you will need to create a new one in Okta.
  2. FMX API Connection: Enter the Hostname, Username, and Password for the dedicated integration user you created.
  3. Click Next.

Step 3: User Type Mappings

Map your Okta Groups to FMX User Types. Settings are applied from top to bottom with the last applicable group winning. Specify broad groups first and more specific groups last. Use Override Existing to overwrite User Types of matched users.

Step 4: Building Mappings (Optional)

This section can set the Accessible Building setting on synced users. Select the Okta group and any number of buildings. If a user is a member of multiple mapped groups, they will gain the buildings from each mapping.

Step 5: User Field Mappings

  1. FMX System Field Mappings: Set which fields are used for creating users with the sync.
  2. User Status Handling: Select Okta statuses that qualify for deleting the user in FMX.
  3. Okta Field Mappings: Map Okta User ID to the "Okta Id" FMX Custom Field created earlier. The list includes all Okta fields associated with the earlier created Okta Application. Each field can be mapped to a single custom field in FMX.
    • Okta allows you to create additional fields for your users via the Profile Editor and map those fields to any application. Please review Okta's documentation for steps on doing this. Any mapped fields in Okta to this application will appear in this list and can be linked to a custom field in FMX.

Step 6: Validation

If any validation fails, use the previous button to go back and correct any issues. Otherwise, click Finish to save your changes. The initial data sync will begin and may take some time to complete.

Was this article helpful?

  • 0 out of 0 found this helpful