Configuring On Premises Provisioning Skip to main content
https://support.okta.com/help/oktaarticledetailpage?childcateg=&id=ka0f0000000ay2nkaw&source=documentation&refurl=http%3a%2f%2fsupport.okta.com%2fhelp%2fdocumentation%2fknowledge_article%2f29448976-configuring-on-premises-provisioning
How satisfied are you with the Okta Help Center?
Thank you for your feedback!
How satisfied are you with the Okta Help Center?
1
2
3
4
5
Very Dissatisfied
Very satisfied
Enter content less than 200 characters.
Average Rating:
Configuring On Premises Provisioning
Published: Jan 12, 2015   -   Updated: Feb 9, 2017

How On-Premises Provisioning Works
Connecting to On-Premises Apps Using SCIM
Installing the On-Premises Provisioning Agent
     Using the Linux Installer
     Using the Windows Installer
Creating an On-Premises App Instance on Okta
Connecting to Your SCIM Connector
     Configuring the Timeout Period for Your API Calls
Installing Additional Provisioning Agents
Configuring Your On-Prem App as a Profile Master
Upgrading Your Provisioning Agent
     Upgrading Your Provisioning Agent on a Linux Server
     Upgrading Your Provisioning Agent on a Windows Server
Configuring High Availability
Uninstalling and Reinstalling a Provisioning Agent
     Uninstalling a Provisioning Agent on Linux
     Uninstalling a Provisioning Agent on Windows
     Reinstalling the Provisioning Agent


On-premises provisioning enables you to provision users from Okta to on-premises applications that are installed behind a corporate firewall. It also enables you to use other provisioning features that are available from Okta including profile push, password push, user deactivation, group push, user import, and group import.

The on-premises provisioning architecture consists of the following components: Okta, the On-Premises Provisioning Agent, a SCIM server or custom connectors, and on-premises applications. As shown in the figure below, all components except Okta sit behind a firewall.

opp1a.png

The following is a list terms that appear frequently in this article, along with their definitions:

Okta: An identity management service that runs in the cloud. Okta generates provisioning instructions (for example, provision, update, and import) and the provisioning agent generates SCIM requests. 

On-Prem Provisioning Agent: A lightweight agent that runs on Linux (CentOS or RHEL) or Windows (x86/x64) server and sits behind a firewall. The On-Prem Provisioning Agent gets provisioning instructions from Okta and sends SCIM messages to the appropriate SCIM endpoint or connector.

SCIM Server: An end point that can process SCIM messages sent by the provisioning agent. This can be an application that natively supports SCIM or a SCIM connector that acts as an intermediary between the provisioning agent and the on-prem application.

SCIM Connector: A custom-coded SCIM connector or a connector created using the Okta Provisioning Connector SDK. The SCIM connector processes SCIM messages from the provisioning agent, acting as a SCIM server. SCIM connectors are built using the Okta Provisioning Connector SDK. This connector implements Okta’s SCIMService interface to integrate with the provisioning agent and the API of the on-prem application to establish connectivity with the on-prem application. 

On-Premises App: An application (web app or thick app) installed behind your firewall.

top

How On-Premises Provisioning Works

This section describes the provisioning of a new user from Okta to an on-premises application using a SCIM server. Refer to Provisioning SCIM Messages Sent by Okta to a SCIM Server for a complete list of provisioning flows. 

In the following example, MySQL database is the on-prem app.

  1. An Okta admin creates an app instance in Okta to represent the MySQL on-prem app.

  2. The admin attempts to provision a new user by assigning an Okta user to the MySQL app on Okta. Okta creates a provisioning event (create new user).

  3. The provisioning agent polls Okta and finds the provisioning event (create new user). The provisioning agent translates the provisioning event (create new user) to a SCIM request: HTTP POST to the /Users endpoint of the SCIM server.

  4. When the SCIM server receives a POST made to /Users with a JSON-formatted SCIM representation of the user, it receives the list of users from the on-prem application using the integration mechanism available from that on-prem application (e.g., an API).

  5. The SCIM server responds to the provisioning agent with the SCIM response message as mandated by SCIM protocol.  

top

Connecting to On-Premises Apps Using SCIM

You must have a SCIM server to process the provisioning requests sent by your provisioning agent. This SCIM server can be the connector you build using the Okta Provisioning Connector SDK or your own program that can process SCIM-based REST calls. Refer to Creating SCIM Connectors for more information.

The Okta Provisioning Connector SDK package contains two example connectors. Use the example connectors to test on-prem provisioning and to help you build your own connectors. Do not attempt to use the example connectors without modifying them for your deployment.

top

Installing the On-Premises Provisioning Agent

When you want to configure on-premises provisioning for an app, the first thing you do is to install the provisioning agent. You can install the provisioning agent with either Linux or Windows. You can connect your provisioning agent to multiple on-prem apps but you must provide a unique SCIM server URL for each app. Proceed to the appropriate section below.

top

Using the Linux Installer

To install the provisioning agent using the Linux installer, do the following:

  1. Click the Provisioning tab and then click the Download Provisioning Agent button.

    Alternatively, you can go to your Administrator Dashboard, select Settings > Downloads, and then click the Download button for Okta Provisioning Agent (x64 RPM) to download the installer file.
  2. After you download the provisioning agent, you must install it on a Linux server. Sign in as root to your Linux server, copy the provisioning agent .rpm file to a scratch directory, and then cd to that directory.
  3. Install using yum by entering the following:

    yum localinstall <package name>

    For example, yum localinstall OktaProvisioningAgent*.rpm
  4. The installation process tells you the total size and installed size of the installation and asks you if it is okay to continue. Enter y to continue.

    You should receive a message indicating that the installation succeeded. Note that the instructions on how to run your provisioning agent configuration script appear on your screen.
  5. Copy the command on your screen and run the script as root:

    sudo /opt/OktaProvisioningAgent/configure_agent.sh
  6. When prompted, enter the URL of your org. For example:

    https://mycompany.okta.com

    Your provisioning agent is configured and you are given a URL to sign into.
  7. Go to the URL in your browser and sign in with your username and password. 
  8. To enable the provisioning agent to access the Okta API, click the Allow Access button and then confirm by clicking the Continue button.
  9. Return to the command line. You should receive a message indicating that your configuration was successful and a command that you can use to start your provisioning agent. Copy and enter the command:

    service OktaProvisioningAgent start
  10. To confirm that the agent is running, enter the following:

    service OktaProvisioningAgent status

    This completes the installation and configuration procedure. Proceed to the next section to configure your provisioning connector and enable provisioning.

top

Using the Windows Installer

To install the provisioning agent using the Windows installer, do the following:

  1. From your Administrator Dashboard, select Settings > Downloads, and then click the Download button for the appropriate Windows Okta Provisioning Agent.
  2. Launch the installer and then click the Next button.
  3. Click Next on the License Agreement dialog box.
  4. Optionally change the installation folder on the Installation options dialog box and then click the Install button.
  5. Enter your Okta Customer Domain URL and then click the Next button to register. 
  6. Go to your browser and sign into your org. You are asked to grant permission to access the Okta API. Click the Allow Access button. 
  7. Go back to the installation wizard and click Finish to complete the installation.
  8. Sign into Okta and, from your Administrator Dashboard, select Agents. Make sure that the on-premises agent that you configured is displayed in the list.

    This completes the installation and configuration procedure. Proceed to the next section to configure your provisioning connector and enable provisioning.

top

Creating an On-Premises App Instance on Okta

  1. From your Administrator Dashboard, verify that your on-prem provisioning agents are connected to Okta by selecting Dashboard > Agents and verifying that the circle is green.
    User-added image

  2. Enable on-premises provisioning configuration on General tab.
  3. Select Applications and select your on-prem app.
  4. Click the General tab.
  5. Click the Edit button under Settings.
  6. Select the checkbox for Enable on-premises provisioning configuration.
  7. Click the Save button. This enables the provisioning tab for the application.

top

Connecting to Your SCIM Connector  

If your on-premises application does not support SCIM natively, you must create a SCIM connector. As mentioned above, a SCIM connector acts as a SCIM server and an intermediary between Okta and on-prem application. The SCIM connector can be a connector built using the Okta Provisioning Connector SDK or any custom app or connector that can process SCIM messages. Typically you should install your SCIM connector on a web server that is accessible to your provisioning agent.

Before you proceed, you must install your connector. You can test your deployment using one of the example connectors packaged with the Okta Provisioning Connector SDK. For more information, refer to the "Example Connector" section in Creating SCIM Connectors. After you have built and installed your connector, proceed to the next step to configure your app instance on Okta which communicates with your SCIM connector.

To configure your SCIM connector and enable provisioning, do the following:

  1. Click the Provisioning tab. Your system should detect the presence of the provisioning agent you installed and the text on the Provisioning page informs you that you must configure your SCIM connector.

  2. Click the Configure SCIM Connector button to continue. The Connector Configuration section appears.

  3. Complete the following fields:

Field

Description

SCIM connector base URL

The URL of the SCIM connector to which the provisioning agent forwards SCIM data.

Authorization type

Choose one of the following:

- Basic Auth: Username and password.

- HTTP Header: HTTP header name and value.

- None

Credentials

The username and password of the web server that is hosting the SCIM connector.

Unique user field name

The SCIM property name of the Okta user that can be used to uniquely identify a user on the on-premises system (e.g., userName).

Connect to these agents

Select the provisioning agents with which you want to connect.

  1. Click the Test Connector Configuration button to test your settings.

  2. If the test fails, change your settings and test your configuration again. If the test is successful, you receive a report of the provisioning features detected on your connector, and you can click the Save button to save your settings.

    Note: If your SCIM connector has not implemented the UserManagementCapabilities method, Okta assumes all provisioning functions have been implemented. If you have implemented your own SCIM end point without using the Okta Provisioning Connector SDK, it is assumed that your SCIM connector or end point has implemented all provisioning functions. For the complete list of provisioning functions, refer to Building SCIM Connectors.

This completes your configuration. Your on-premises system is now connected to Okta. You can now provision users and perform provisioning tasks.

If you disable provisioning, you disable all the features, but the boxes remain checked for you to reenable it.

top

Configuring the Timeout Period for Your API Calls

You can specify how long your org waits for an API call to complete before a timeout occurs. The minimum setting is 30 seconds. The timeout value you select is applied to all requests (GET, PUT, and POST) that are sent to the SCIM server. Do the following:

  1. From your Administrator Dashboard, select Applications > your on-prem app, and then select the Provisioning tab.
  2. Click the Edit button in the Connector Configuration section.
  3. Click the Timeout for API Calls drop-down menu to select the desired period of time.

    scim_timeout.png
  4. Click the Save button.

top

Installing Additional Provisioning Agents

You can install additional provisioning agents by going to the Downloads page. To download another provisioning agent, do the following:

  1. From your Administrator Dashboard, select Settings > Downloads.
  2. In the Admin Downloads section, click the Download button for the Provisioning Agent Installer.
  3. Proceed from Step 5 of the Installing the On-Premises Provisioning Agent section, above. Make sure to install the agent on a different server from your primary agent. 

top

Configuring Your On-Prem App as a Profile Master

You can configure your on-premises app as a profile master. Profile mastering enables you to configure your on-prem app as the identity authority for assigned users. When enabled, user profiles are not editable in Okta and changes are synchronized to Okta during provisioning events. Do the following:

  1. From your Administrator Dashboard, select Applications, and then select the desired on-prem app.
  2. Select the Provisioning tab.
  3. Click the Edit button in the Provisioning section.
  4. Check the Enable button in the Profile Master section and then click the Save button.

 

top

Upgrading Your Provisioning Agent

Okta periodically provides upgrades to the provisioning agent. Note that the upgrade process does not automatically start the service. It stops the service if it is already running. The upgrade echoes the exact command needed to start the service. 

top

Upgrading Your Provisioning Agent on a Linux Server

To upgrade to the latest agent, do the following:

  1. Sign in as root to your server, copy the OktaProvisioningAgent*.rpm and okta-jre*.rpm to a scratch directory, and then cd to that directory.
  2. Determine if you have a previous version of the provisioning agent on your server by entering the following command:

    rpm -q OktaProvisioningAgent

    If it is present on the server, your command returns the name and version of the currently installed provisioning agent.
  3. Use yum to upgrade the provisioning agent by entering the following command:

    yum localupdate <package name>

    For example, yum localupdate OktaProvisioningAgent*.rpm
  4. The installation process tells you the total size of the installation and asks you if it is okay to continue. Enter y to continue.

    You should receive a message indicating that the upgrade succeeded.
  5. To restart your provisioning agent, enter the following command:

    service OktaProvisioningAgent start
  6. To confirm that the provisioning agent is running, enter the following command:

    service OktaProvisioningAgent status

This completes the upgrade procedure. The process automatically restarts after the upgrade is complete.

top

Upgrading Your Provisioning Agent on a Windows Server

To upgrade your provisioning agent on a Windows server, perform the installation procedure described above, in Using the Windows Installer. You do not have to uninstall the old version first. Installing the new version replaces the old one.

top

Configuring High Availability

You can configure high-availability on-premises provisioning by installing an additional provisioning agent and SCIM connector on another server. Start the provisioning agent, configure your SCIM connector, and enable provisioning on your backup server just as you did for your primary server. That way, if your primary server goes down, the agent and the processes run by your SCIM connector continue to operate.

top

Uninstalling and Reinstalling a Provisioning Agent

You can remove provisioning agents from your system. Before you remove a provisioning agent, we recommend that you have one or more additional agents configured so there is no interruption of service. See Installing Additional Provisioning Agents for more information. When you uninstall and reinstall your provisioning agent, you must decide whether or not you also want to remove the old Okta API token from your system. If you are performing an upgrade, you are not required to do so. To remove the API token, you must delete the Okta Provisioning Agent folder, and deactivate and remove your old AD agent.

top

Uninstalling a Provisioning Agent on Linux

Do the following:

  1. Sign into your Linux server as root.
  2. Enter yum remove OktaProvisioningAgent.

top

Uninstalling a Provisioning Agent on Windows

Do the following:

  1. On your Windows desktop, select Start > Control Panel > Programs > Programs and Features
  2. Select the Okta Provisioning Agent, and then select Uninstall.
  3. Uninstalling your provisioning agent leaves the agent configuration data on your hard drive. To remove the configuration data, go to \Program Files (x86)\Okta and delete the Okta Provisioning Agent folder. Deleting this folder removes the agent configuration data and the API Token from your hard drive. The API token for the server is still valid in Okta so it is important to remove the configuration data.

top

Reinstalling the Provisioning Agent

Installing the provisioning agent does not overwrite the configuration data in the Okta Provisioning Agent folder. If you want to reinstall and create a new API token, make sure you delete the Okta Provisioning Agent folder (as described above) before you reinstall the provisioning agent. Then perform the following steps to reinstall your provisioning agent and deactivate and remove the old provisioning agent in Okta:

  1. Perform the provisioning agent installation procedure described in Installation and Configuration
  2. From your Administrator Dashboard, select Dashboard > Agents
  3. Confirm that your reinstalled provisioning agent is connected to Okta and appears in the list. You should always make sure to have at least one provisioning agent online. Its status should be Active.

    If you are performing an upgrade or reinstallation and you do not want to revoke the Okta API token of the old provisioning agent, you are finished. Otherwise, proceed to the next step.
  4. Under On-Premises Agents, select the Active drop-down menu for the old provisioning agent and select Deactivate. The status of the agent now changes to Inactive
  5. Select the Inactive drop-down menu for the agent you want to remove and select Delete.
  6. Make sure you go through all of your on-prem provisioning apps and set your new agent as one of the provisioning agents that serve that app or connector.

Post a Comment