External User Connector – Okta

External User Connector – Okta

This guide provides the steps required to configure SCIM 2.0-based user provisioning and OpenID Connect-based single sign-on via Okta.

Features

Okta can perform the following actions automatically against our platform:

  • Add new users
  • Update selected details on users
  • Deactivate users
  • Authenticate users when they log in via our web portal or apps.

The following provisioning features are supported:

  • Users created through OKTA will also be created on our platform.
  • Updates made to the user’s profile through OKTA will be pushed to us.
  • Deactivating the user or disabling the user’s access to the application through OKTA will deactivate the user on our platform.
  • Users can be imported from our platform into Okta

Pre-requisites

Before you configure provisioning, check the following in your platform account: 

  • Ensure you have added our Enterprise Toolkit option to your account since this unlocks our Okta integration options. Enterprise Toolkit can be enabled via your Billing page in the platform.
  • Go to the Menu > Organization Setup page and find the section titled External User Authentication & Provisioning. Click the Add Connector link and select the Okta option from the list of available connectors – this will save the Organization Setup page and reload it.
  • Make note of the SCIM URL, User Name, Password, and OpenID Connect Login Redirect URI values displayed on the Okta connector details. You will need these for the Okta configuration steps below.

Single Sign-On (via OpenID Connect) Configuration Steps

Currently, Okta does not support having OIDC and SCIM on the same application as found in the Okta Application Network (OAN). Hopefully, Okta will allow the combination of OIDC and SCIM on a single OAN application in the future.

Until then, you will need to use the Okta App wizard to create a separate OIDC app.

Create an OpenID Connect application

  • Go to the Admin > Applications area of your Okta account, then click Add Application.
  • Click the Create New App button, then select Native from the list of Platform options.
  • Ensure OpenID Connect is the selected Sign-on Method, then click Create
  • Enter an Application Name – preferably use our platform name
  • Upload an option Application Logo – you can get ours by right-clicking on our login page logo and using Save Image As.
  • Enter all Login Redirect URIs as noted from your Organization Setup page
  • Leave Logout Redirect URIs blank
  • Click the Save button to create your OIDC application.

This will take you to more detailed configuration options.

General settings

  • Application Name – preferably use our platform name
  • Application Type – must be Native
  • Allowed Grant Types – only Authorization Code should be selected
  • Login Redirect URIs – enter all Login Redirect URIs as noted from your Organization Setup page
  • Logout Redirect URIS – leave blank
  • Make note of the Client ID value as seen under the Client Credentials section. You will need to input this into the given field on our platform to enable Single Sign-On later.
  • Client Authentication – ensure PKCE is selected

Sign On

  • Sign On Methods – OpenID Connect should be the only option selected
  • Signing Credential Rotation – should be left as Automatic
  • Make note of the Issuer url seen under the OpenID Connect ID Token section. You will need to input this into the given field on our platform to enable Single Sign-On later
  • Claims – should be Claims for this token include all user attributes on the app profile
  • Group Claim options should be left as the default

Assignments

  • Assign users as desired – any user that requires login access on our platform or apps must be assigned to your OIDC app in Okta.

After creating and configuring your OIDC app in Okta, you must update the Okta connector configuration in our platform:

  • Go to the Organization Setup page in our platform
  • Under the Manage Users with Okta option, input the Issuer URL and Client ID as noted during your Okta application setup process above.
  • Save your changes.

At this point, all users registered on our platform will now be required to sign in via Okta.

User Provisioning (via SCIM 2.0) Configuration Steps

Add the Appenate App Integration

  • In your Okta account, go to Admin > Applications > Add App > Search for “Appenate”.

Configure General Settings

  • Specify a description for the Application Label, then hit Next

Configure Sign-On Options

  • Okta does not currently support OpenID Connect as part of standard app integrations, so simply configure this section as seen in the screenshot below, then click Next.  You can set up sign-on via OpenID Connect as a separate integration – see the Single Sign-On section above.

Configure Provisioning Settings

  • Check the Enable provisioning features box
  • Enter SCIM URL, Company ID, and Integration Passkey values that you noted from our platform into the relevant fields
  • Click the Test API Credentials button and check that your credentials were verified successfully
  • Under User Import, ensure that the following are set:
    • Schedule Import: never
    • Okta username format: Email Address
  • Ensure that Profile Master is NOT enabled.
  • Ensure Create Users is enabled. 
  • Ensure Update User Attributes is enabled. 
  • Ensure Deactivate Users is enabled.
  • Ensure that Sync Passwords is NOT enabled.

Configure People Assignment

  • Lastly, choose which people should be assigned to have access to Appenate, then click Next to complete the configuration

You can now assign people to the app (if needed) and finish the application setup.

Assigning Website Access to Okta Users

By default, users who are provisioned via Okta will only be granted app login access. If you wish to assign web portal access, then you must specify one of the following Role values on the Okta user’s application profile:

  • ReadOnly
  • User
  • Admin
  • EnterpriseAdmin

The capabilities of the above roles can be seen on the hints for Access Roles as found on the Edit User page of our platform.

Assigning Metadata to Okta Users

Within the Okta portal, go to the application user for the application that is used to sync between the platform and Okta. This can be found under Directory > Profile Editor.

Click on + Add attribute.

Fill in the details for the attribute. The important values are:

  • Data type: string (You can set others but we will convert it to a string on your platform, which could result in the value changing)
  • Variable name: This is how the attribute will appear in Okta’s mapping screen. We recommend making this the same as the external name for simplicity.
  • External name:  This will become the key for the metadata on our platform.
  • External namespace: urn:ietf:params:scim:schemas:extension:2.0:Metadata

Below is an example:

Click Save when you’re done.

Next, you need to set the mapping between an attribute on the actual user’s profile to this attribute on the application’s user profile. Open up the Okta application that is used to sync with our platform. This is found under Applications > Applications in the menu.

Ensure you are on the To App tab, and then scroll down to the Attribute Mappings.

Click on Show Unmapped Attributes and then on the pencil to edit the attribute you want to map. In the modal that appears, set the property on the user that you want to map. We recommend setting Apply on to Create and update so that any changes made to the user’s metadata in Okta sync through to our platform.

When Okta does its next synchronization with our platform, the attributes will be populated into the user’s metadata.

Troubleshooting and Tips

Required Values for Provisioning

The following values must be specified on Okta users in order for them to successfully provision on our platform:

  • First Name
  • Last / Family Name
  • Email (this must be unique per user, since it is used as our username

Login Errors with Vanity/Custom SSO URLs

If you have setup your Okta SSO against an Okta domain – e.g. myorg.okta.com – and then decide to use a custom domain for this Okta setup, the app may fail to complete logins when your Okta connector is configured with the custom domain as the Authority/Issuer URL.

The reason for this is that the Okta service, after the user successfully logs in, sends an invalid token back to the app.  
The invalid aspect being that the token’s Issuer value will reflect the Okta domain instead of the custom domain, which thus fails security checks on the app side. As a result, the user will see an app error message such as “Please verify your login credentials”, despite successfully logging in on the Okta SSO page.

The solution is to change your Okta configuration. Configure the Okta OpenID Connect token to send back the issuer as your custom/vanity URL instead of the default Okta domain issuer. This means that the token’s issuer will then match the domain specified in your Okta connector configuration on our platform, resulting in a successful login.

Toggle User Authentication Method

Once Okta is enabled, all users will be authenticated externally unless disabled. However, for temporary or external users that are not registered in Okta, you can choose to use our platform’s built-in authentication instead.

Toggling between Okta and Built-In authentication for a user can be achieved when editing a user’s details (Organization&Users > Users&Groups), under Access&Security > Login Method dropdown.

    • Related Articles

    • External User Connector – Azure

      This guide provides the steps required to configure SCIM 2.0-based user provisioning and OpenID Connect-based single sign-on via Azure Active Directory (Entra ID). Note: Azure AD is being renamed to Microsoft Entra ID Features Azure Active Directory ...

    • External User Connector – Ping Identity

      This guide provides the steps required to configure OpenID Connect-based single sign-on via Ping Identity. IMPORTANT NOTE: User logins may become disrupted during the steps below. We strongly recommend that you create a “testing SSO” environment (via ...

    • Single Sign On (SSO)

      Single Sign-On (SSO) is an authentication method that allows users to sign in to multiple independent software systems using one set of credentials. If your organization has the Enterprise Toolkit add-on enabled, you can choose from various SSO ...

    • eForms Mobile Replicate – User-Level Data Filtering

      By default, eForms Mobile Replicate sends every row in a table to every user. To ensure users only see the data relevant to them, you can implement User-Level Filtering. This article is an extract from the Replicate Installation Guide (PDF). For full ...

    • Email-less Login with SSO

      Enable users to log in with a non-email identifier like an SSO username or ID when using Okta or Ping Identity, when Enterprise Toolkit is activated on an account. Navigate your account to Organization & Users > Organization Setup > Integrations > ...