This guide will explain how to set up your Okta integration with FMX. These instructions are for users who have purchased the Okta integration and have already been added to prismatic. If you are interested in adding this integration please reach out to your account manager at FMX. Once an FMX team member reaches out you can begin the process with the below steps. 

Create Integration User

You will need to create an account in your FMX site for the integration to sync with. Name the account "Okta Syncer" this will make it easier to track the users brought over to FMX. Use the email "okta-syncer@gofmx.com". In order to do this you will need to create a new user type that will not be updated. If the integration’s user type is updated this can cause the integration to not work.

To create a new user type click the “Admin Settings" in the left sidebar then select the” User Types" tab at the top of the page. You can either select add “User Type” at the top of the page or click the vertical 3 dots next to a user type that may have full access like “FMX Administrator” and click “copy”. Name the user type “FMX Integration”. For more information on user types go to this support center article.

Next go to the following setting and make sure the user type has at least the following permissions:

  • Building & Resource Access
    • Read - Any
  • User & Contact Access
    • Administer
    • Read Users
    • Read Contacts
    • Delete
  • Permitted Access to All Desired Custom Fields

You will use this information in the configuration step below.

Create Custom Fields

Add the required custom fields in your FMX site before starting the integration steps. The custom fields need to be in FMX prior to the steps being completed so that you will be able to map the correct Okta field to correct FMX field. 

Add the following field:

  • Link to Okta  - add this custom field for Users & Contacts, that is a text field. Make sure that you do not limit the permitted user types for this field so that the integration can work properly. 

Additionally, there are optional custom fields you can map over from Okta to FMX. It is recommended that you add these fields before setting up the integration. However, these fields can be added later and the integration can be updated. The field mapping section of the article will explain more. The required field above is needed for the integration to work properly. See below for optional fields you can add. These custom fields need to be set for "Users & Contacts" and made to be text fields. 

  • Activated date
  • Created date
  • Last login date
  • Last updated date
  • Status
  • Okta user type

**See this support center article for how to add custom fields in FMX**

Okta Authentication Setup

Create a new application for FMX

  1. Sign in to your Admin Console as a user with administrative privileges (Super admin role).
  2. Go to Applications > Applications
  3. Click Create App Integration.
  4. On the Create a new app integration page, select OIDC - OpenID Connect as the Sign-in method, and Web Application as the Application type. Click Next.
  5. Enter a name for your app integration, preferably something related to FMX.
  6. For the Grant type, leave the default of Authorization Code grant flow.
  7. In the Sign-in redirect URIs box, Add URI and enter https://oauth2.prismatic.io/callback.
  8. In the Assignments section, choose the appropriate controlled access. In the purpose of allowing SSO, choose Allow everyone in your organization to access. 
  9. Click Save.

Configuring your new application

  1. In the General tab, make note of the Client ID and Client Secret. You will need this to authenticate the Okta connection in the integration. 
  2. Click on the Assignments tab. This page will need to be configured if you chose to allow limited control to specific groups, selected during step #8 when creating a new application. If you’ve selected to allow all, skip this step.
    1. See this link for instructions on how to assign app integrations.
  3. Click on the Okta API Scopes tab and apply Grant to the following scopes. Added scopes can be viewed in the Granted page which can be found under the Consent column.
    1. okta.groups.read
    2. okta.userTypes.read
    3. okta.users.read

Find Okta domain name

  1. Log in to your Okta admin console.
  2. Find your email or username in the top right corner of the page. 
  3. Click on the down arrow next to your email address in the top right corner of the page.
  4. The text displayed under your email address is your Okta organization name. The domain name typically follows the format https://<your-org-name>.okta.com.

Go to the Integrations Settings

In your FMX site go to your admin settings. Then go to the tab that says “Integrations”. In this section you will see all of the integrations you have on your FMX site through Prismatic. Prismatic is a platform that you will use to set up the integration between Okta and FMX. The platform is embedded into FMX and you will use it via the integrations tab. To access your integration to begin the setup process select the integration you would like to work on. If you do not see the Okta integration reach out to your primary contact at FMX.

To set up the Okta integration for your users select  “Okta" in this tab. In order to start this process click the “Reconfigure” button.

1. Initial Configuration

There is nothing that you need to do for this first section. Select the "Next" button to move on to the "Configuration" section. 

2. Configuration

Next fill out the fields in the "Okta Connection" section

  1. Authorize URL: Insert your domain name into the URL where it says your-domain-name. You can find your domain name by following these the steps in "Find Okta doman name" section of this guide. Okta domains usually end with ‘.okta.com`.
  2. Token URL: Insert your domain name into the Token URL where it says your-domain-name.
  3. Client ID: Enter the client id from the configuring your new application step.
  4. Client Secret: Enter the client secret, also from the configuring your new application step.

Next, fill out the following fields in the FMX API Connection section:

  • Hostname - this is your FMX hostname. This can be found in the URL of your site and it is the text before “.gofmx.com”. For example: https://fmxschool.gofmx.com/. The bolded text is your hostname.
  • Password - this is the password of the FMX integration user you added earlier
  • API User Email - this is email address of the integration user you added earlier

Select the "Next" button when you are finished.

3. Status Syncing

Select one or more statuses below to sync Okta users with those statuses to FMX. Active Okta users will automatically sync to FMX and do not need to be added. All other users with unselected statuses will not sync, or will be deleted from FMX. 

To do this select the "+ Add to Status Mapping" button and choose from the list. When you are finished select the "Next" button to move on to the next. 

4. Group Mapping

In this section you will select which groups from Okta you want to include in the integration, as well as their respective user type in FMX, and whether they should be added as a user or contact. Only groups selected below will be synced with FMX.

In the type mapping section select the "+ Add to Okta Group Mapping" button and choose a "Okta Group" from the first drop down, then select corresponding FMX user type from the "FMX User Type" dropdown. Then choose whether you want them to be a user or contact in FMX. 

Choose to "Override Existing User Permissions" or not. When the box is checked the above user type and user/contact selection will be applied to existing users in FMX belonging to this Okta Group. Otherwise, they will only be applied to new users.

Choose to "Override Existing Accessible Building" or not. When the box is checked the accessible building mapped in the next step will be applied to existing users in FMX belonging to this Okta Group. Otherwise, it will only be applied to new users.

Repeat this process to map your Okta groups. Then select next when you are done. 

5. Accessible Building Mapping

In the section you will map Okta Groups to their accessible building in FMX. To do this select the "+ Add to Accessible Building Mapping." 

Each Okta Group can be mapped to multiple accessible buildings in FMX. This mapping is ONLY for users with at least one permission set to "accessible buildings" in FMX. If an Okta group has multiple accessible buildings, please add each additional building as a new line. 

Next choose a default FMX building for when a user requires an accessible building but none is mapped specifically for their user group, the default accessible building will be used instead. Select "Next" when you are finished. 

5. Field Mapping

In the first field choose the "Link to Okta" custom field you created in FMX earlier. This is the only field you are required to map. 

Lastly choose from the optional Okta fields listed in the drop down to map to an FMX custom field by matching the fields in each drop down menu. If you did not create custom fields for these prior to configuration in FMX you can reconfigure the integration to map these later.  Select finish when you are done. 

Updating the Integration

If changes need to be made to your integration, you can update it at any time. To do this go back to the Integration Settings tab in FMX. Then find the integration and select "reconfigure". You can use the "Next" button to get to the section you would like to update. 

Was this article helpful?

  • 0 out of 0 found this helpful