Configure on-premises provisioning

On-premises provisioning enables you to provision users from Okta to on-premises applications that are installed behind corporate firewall. It also enables you to use Okta provisioning features like 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-Prem Provisioning AgentA 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., a SCIM serverAn 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. or custom connectors, and on-premises applications. As shown in the figure, all components except Okta sit behind a firewall.

How on-premises provisioning works

In the following scenario, a new user is provisioned from Okta to an on-premises application (MySQL database) using a SCIM serverAn 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.. Refer to Provisioning SCIM Messages Sent by Okta to a SCIM Server for a complete list of provisioning flows.

  1. An Okta adminAn abbreviation of administrator. This is the individual(s) who have access to the Okta Administrator Dashboard. They control the provisioning and deprovisioning of end users, the assigning of apps, the resetting of passwords, and the overall end user experience. Only administrators have the Administration button on the upper right side of the My Applications page. creates an appAn abbreviation of application. Essentially, it is a web-based site used to perform any number of specific tasks, and requires authentication from end users by signing in. 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 agentA software agent is a lightweight program that runs as a service outside of Okta. It is typically installed behind a firewall and allows Okta to tunnel communication between an on-premises service and Okta's cloud service. Okta employs several agent types: Active Directory, LDAP, RADIUS, RSA, Active Directory Password Sync, and IWA. For example, users can install multiple Active Directory agents to ensure that the integration is robust and highly available across geographic locations. polls Okta and finds the provisioning event. The provisioning agent translates the provisioning event to a SCIMSystem for Cross-domain Identity Management (SCIM) is an open standard that allows for the automation of user provisioning. It was created in 2011 as it became clear that the technology of the future would be cloud-based. SCIM communicates user identity data between identity providers (such as companies with multiple individual users) and service providers requiring user identity information (such as enterprise SaaS apps). In short, SCIM makes user data more secure and simplifies the user experience by automating the user identity lifecycle management process. 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 attempts to create that user in the on-premises application.
  5. The SCIM server responds to the provisioning agent with the SCIM response message as mandated by SCIM protocol.

Connect to on-premises apps using SCIM

You must have a SCIM server to process the provisioning requests sent by your provisioning agent. The SCIM server can be the connector you build using the Okta ProvisioningProvisioning is the enterprise-wide configuration, deployment, and management of multiple types of IT system resources. Specifically, provisioning provides users access to equipment, software, or services. This involves creating, maintaining and deactivating required business process automation objects and attributes in systems, directories, and applications. Connector SDK or your own program than can process SCIM-based REST calls.

The Okta Provisioning Connector SDK package contains an example connector that you can use to test on-premises provisioning and to help you build your own connectors. Do not attempt to use the example connector without modifying it for your deployment.

Enable the TLS 1.2 Protocol

Okta requires the TLS v1.2 protocol for Linux and Windows agent installation. If you've already enabled TLS.1.2 protocol, proceed to Install the on-premises provisioning agent.


To enable TLS version 1.2, you must access the Java Control Panel to change the JRE.

  1. Navigate to …/opt/OktaProvisioningAgent/conf/settings.conf
  2. In settings.conf, change the arguments passed to the agent by adding:

    Dhttps.protocols=TLSv1.2 to JAVA_OPTS.

    JAVA_OPTS="-Xmx4096m -Dhttps.protocols=TLSv1.2


To enable TLS version 1.2, you must access the Java Control Panel and enable TLS 1.2.

  1. Navigate to C:\Program Files\Okta\OktaProvisioningAgent\current\jre\bin and double-click javacpl to open the Java Control Panel.
  2. On the Java Control Panel, click the Advanced tab.
  3. In Advanced Security Settings, select TLS 1.2.

Install the on-premises provisioning agent

Before configuring on-premises provisioning for an app, install the provisioning agent with either Linux or Windows. You can connect your provisioning agent to multiple on-premises apps, but you must provide a unique SCIM server URL for each app.

Install the provisioning agent using the Linux installer

  1. On your okta-admin app instance page, go to the Provisioning tab and then click Download Provisioning Agent.
  2. Or

    In Admin Console, go to SettingsDownloads, and then click Download for the Okta Provisioning Agent (x64 RPM).

  3. After the provisioning agent is downloaded, sign in as root to your Linux server.
  4. Copy the provisioning agent .rpm file to a scratch directory, and then cd to that directory.
  5. Install using yum by entering the following:
  6. yum localinstall <package name>

    For example, yum localinstall OktaProvisioningAgent*.rpm

  7. When you are prompted to continue, enter y.
  8. After the installation succeeds, copy the command on your screen and run the script as root:
  9. sudo /opt/OktaProvisioningAgent/

  10. Enter the URL of you orgThe Okta container that represents a real-world organization. at the prompt (for example:
  11. In your browser, go to the URL that you are provided, and sign in with your username and password.
  12. To enable the provisioning agent to access the Okta API, click Allow Access.
  13. Note: If you haven't enabled TLS 1.2 protocol or are using an earlier version, see Enable the TLS 1.2 Protocol.

  14. Return to the command line. After you receive a successful configuration message, copy and enter the command:
  15. service OktaProvisioningAgent start

  16. To confirm that the agent is running, enter the following:
  17. service OktaProvisioningAgent status

Your installation and configuration procedures are complete. Next, configure your provisioning connector and enable provisioning.

Install the provisioning agent using the Windows installer

  1. In Admin Console, go to SettingsDownloads.
  2. Click Download for the Windows Okta Provisioning Agent.
  3. Launch the installer, and then click Next.
  4. In the License Agreement dialog box, click Next.
  5. Optional. Change the installation folder, and then click Install.
  6. Enter your Okta Customer DomainA domain is an attribute of an Okta organization. Okta uses a fully-qualified domain name, meaning it always includes the top-level domain (.com, .eu, etc.), but does not include the protocol (https). URL, and then click Next.
  7. In your browser, sign in to your org.
  8. Grant permission to access the Okta API by clicking Allow Access.
  9. Return to the installer, and then click Finish.
  10. Sign in to Okta.
  11. Note: If you haven't enabled TLS 1.2 protocol or are using an earlier version, see Enable the TLS 1.2 Protocol.

  12. In Admin Console, select Agents. Verify that the configured on-premises agent is in the list.

Your installation and configuration procedures are complete. Next, configure your provisioning connector and enable provisioning.

Create an on-premises app instance on Okta

  1. In Admin Console, go to DashboardAgents, and verify that your on-premises provisioning agents are connected to Okta (a green circle means that the agent is connected).
  2. On the General tab, enable on-premises provisioning configuration.
  3. On the Applications page, select your on-premises app.
  4. On the application's General tab, go to SettingsEdit.
  5. Select the Enable on-premises provisioning configuration check box.
  6. Click Save.

Connect to your SCIM connector

Create a SCIM connector if your on-premises application does not support SCIM natively. A SCIM connector acts as a SCIM server and an intermediary between Okta and the on-premises application. The SCIM connector can be 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.

First, install your connector. You can test your deployment using one of the example connectors that are packaged with the Okta Provisioning Connector SDK. For more information, refer to the Example Connector section in Create 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:

  1. In Admin Console, go to ApplicationsApplications.
  2. Select the on-premises app you want to connect, and then click the Provisioning tab. Your system should detect the presence of the provisioning agent and instruct you to configure the SCIM connector.
  3. Click Configure SCIM Connector.
  4. Complete the following fields:
    • SCIM connector base URL: The URL of the SCIM connector to which the provisioning agent forwards SCIM data.
    • Authorization type: Basic Auth (username and password), HTTP Header (HTTP header name and value), or None.
    • Credentials: The username and password of the web server that is hosting the SCIM connector.
    • Unique user field name: The SCIM property name o the Okta user who can be used to uniquely identify a user on the on-premises system (userName).
    • Connect to the these agents: Select the provisioning agents with which you want to connect.
  5. Click Test Connector Configuration.
  6. If the test passes, click Save to save your settings. If the test fails, change your settings and try again.
  7. 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 endpoint without using the Okta Provisioning Connector SDK, it is assumed that your SCIM connector or endpoint has implemented all provisioning functions. For the complete list of provisioning functions, refer to Build SCIM connectors using SDK.

Your on-premises system is now connected to Okta, and you can provision users and perform provisioning tasks. If you disable provisioning, the provisioning features will also be disabled, but you can re-enable it any time.