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

  • Features
  • Prerequisites
  • Configuration Steps
  • Troubleshooting Tips


Features

Okta is able to 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 in 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



Prerequisites

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 that display 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 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 on via Okta.



User Provisioning (via SCIM 2.0) Configuration Steps

Add the nomorePAPER App Integration

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


Configure General Settings:

  • Specify a description 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 nomorePAPER, then click Next to complete the configuration


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



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



Assigning Website Access to Okta Users

By default, users that 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.



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 token's issuer will then match the domain specified in your Okta connector configuration on our platform, resulting in a successful login.