The CSV directory integration is a lightweight out-of-the-box option that enables you to build custom integrations for on-premises systems using the Okta On-Premises 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..
Organizations commonly use CSV files containing user identities. Using the agent, Okta can ingest these files on a recurring basis, importing users and their attributes into Okta. You can expect all the functionality available in other Okta profile masters such as Workday or Active Directory, which includes scheduled imports, attribute level mastering, matching rules, and a rich profile of user attributes.
- The OPP agent is lightweight and runs on either Linux (CentOS or RHEL) or Microsoft Windows Server (x86/x64), and sits behind a firewall. To find the download link, log into Okta, select Settings > Downloads, and navigate to the OPP Agent section.
- The OPP agent version must be 1.03.00 or higher. If you previously installed an OPP agent, it will not function for this feature. For information about installing the agent, refer to the On-Premises Provisioning Deployment Guide.
- Your CSV file must have a .csv extension and must be saved to an on-premises file folder.
- Your CSV file must be in UTF-8 format.
- The OPP agent must have read permissions for the CSV file.
To ensure the success of your import, your CSV file content and format should conform to these pre-requisites.
Your CSV file is a representation of all active users from your source system. All active users must be present in every CSV import or the user is considered inactive. Okta uses the Unique Identifier that you designated as the primary identifier for each user. The import behaves as follows:
- If a user is missing during the latest import, Okta assumes the user is no longer active and deactivates the user in Okta.
- If a new user appears who did not exist in Okta during a previous import as denoted by their unique identifier, then Okta creates the user.
- If a user is present in Okta and was present in the latest import, Okta treats the current data in the CSV file as the source of truth, and executes any updates to that user’s attributes.
The unique identifier and all attributes marked as Attribute Required in the Okta Profile Editor must be present in the CSV file. If any of the required attributes is missing for a user, the following results:
- For an existing user, the user is deactivated from Okta
- For a new user, the import fails
- Use only variable names, not display names as CSV headers.
- Do not use white spaces surrounding the headers within the CSV—they are not ignored.
- The Profile Editor ignores any column within the CSV with a header attribute not previously configured.
If an attribute is optional, and there is no header in the CSV file for the optional attribute, Okta does not update that attribute, but it updates all other attributes.
- In Okta, go to Directory > Directory Integrations > Add Directory
- Select Add CSV Directory
- In the Add CSV Directory page, enter a name for the CSV Directory application and click Done.
- Go to Settings > Downloads.
- Scroll to the Okta Provisioning Agents section, and download the correct agent based on your operating system.
- Open the agent installer and follow the instructions. For more information about the agent, refer to the On-Premises Provisioning Deployment Guide.
- Select the Provisioning tab for the new CSV Directory application.
- Select Settings > API Integration from the left-side panel.
- Complete these tasks on the API Integration page.
- The Connect to these agents check boxes are preselected for all active agents. Select only the relevant agents . Note the agents must be version 01.03.00 or greater. You cannot use OPP agents that were previously installed, such as versions earlier than 01.03.00.
- Define the local file path and the .csv file name. This must be the absolute path, for example:
- For Windows: C:\Users\Administrator\Desktop\csv\test.csv
- For Linux: /opt/OktaProvisioningAgent/csv/test.csv
- In the Unique User Field Name, enter a name for the field you want to use as the unique user identifier within the CSV file. For example, employeeid.
- This should be the variable name for the attribute—not the display name.
- This unique identifier is the sole identifying attribute for new or existing users and it must be enforced to be both unique and immutable.
- Save your choices.
- Go to Directory > Profile Editor.
- Find your CSV application and select Mappings.
- Map the CSV application's user profile attributes to user attributes in the Okta User Profile. For an import to be successful, the following fields are mandatory:
You can also use the following default mappings by entering them as your headers within the CSV file (CSV 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. user => Okta user).
- userName => login
- firstName => firstName
- lastName => lastName
- email => email
As an 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., you can update the attributes you want to map by using the Okta Expression Language.
- Optionally, you can use the Profile Editor to map alternative attributes from your CSV file instead of using the Okta default attributes, or you can import additional fields as custom attributes. In either case, complete these steps:
- Find your CSV application in the Profile Editor page and select Profile.
- Select Add Attribute, add the new attribute, and save.
- Select Map Attributes, and map the new attribute which will replace the Okta default.
- You can delete the Okta default attribute.
- Save your changes.
The new attribute appears under Filters > Custom.
- Okta queries the name you specify when determining which headers in the CSV file correspond to the attribute.
- Okta only supports non-array attributes (i.e., string, boolean, integer, number).
- You must add the attribute that corresponds to your Unique User Field Name. This is required.
- Mapping a Unique Identifier from the CSV file is not required. If you would prefer that the Unique Identifier be populated on the user profile, access the mappings and configure it there.
- If there are additional attributes you want to import from the CSV file, they must be added to your schema. If your CSV file has attributes or headers that are not configured within your user profile, Okta ignores them and their associated values for each user.
- If a CSV column is not included as an attribute in a CSV user profile, the data from that column is ignored. For example, if you’ve configured userName, firstName, lastName, email, and employeeId within the Profile Editor, but your CSV includes an additional attribute with the Address header, Okta will not import Address or any values populated for a user with an address.
For example, to change the lastName attribute in Okta with your CSV file's familyName header, you would do the following:
- Create a new attribute on the CSV Directory app user profile with a variable name of familyName.
- In the Profile Editor, map appuser.familyName to the lastName attribute on the Okta user profile.
- You can delete the default attribute, appuser.lastName. However, if you choose to retain it, it is no longer mapped.
You can set up regular imports on the CSV Directory app page.
- Make sure that your CSV file is properly formatted, and corresponds with the attributes you configured in Profile Editor.
- Comma is the only delimiter that is currently supported. If a value for a specific field has a comma present (for example, 1 Main Street, Boston, MA), those comma values can be ignored by placing neutral quotes (" ") around them (1 Main Street"," Boston"," MA).
- The Unique Identifier must be included within your set of attributes imported from the CSV file. The headers within your CSV must be an exact match with the variable names that correspond to those attributes you want to map from the CSV file to the Okta user.
You can configure matching rules, configure username generation rules, and determine if you want these users mastered from the CSV Directory app. You can also schedule recurring imports.
- Create a sample .csv file, or use a file that reflects an existing store of users within your organization. Make sure the file is saves as UTF-8.
The file should have a Unique Identifier, and values that correspond to the login, firstName, lastName, and email Okta user attributes.
- Place a .csv file in the file path you entered into the API Integration settings.
- Go to the CSV Directory app's Import tab and select Import Now.
Users are imported into Okta, and you can see them in the import queue if the confirmation and activation settings are set up accordingly.