Okta service account permissions

Before adjusting the permissions on your directory, ensure that you understand how Active Directory (AD) permissions are set and plan how to manage permissions within your environment. For information about the account requirements needed to perform this task, see Active Directory integration prerequisites.

This topic is split into three parts. They describe the required permissions for service accounts, optional use cases, and a reference.

Required permissions

If you don't select an existing account, the Okta AD agent installer creates a default Okta service account called OktaService. This account inherits the permissions of the Domain Users group. OktaService is also a member of the Authenticated Users and Everyone special identity groups when the agent is running. By default, the Authenticated Users group is a member of the Pre-Windows 2000 Compatible Access group. Removing the Authenticated Users group from the Pre-Windows 2000 Compatible Access group can cause issues with incremental imports. The recommended approach to resolve issues with incremental imports is to make one of the following changes:

  • Add the Okta service account to the Pre-Windows 2000 Compatible Access group.
  • Make sure the Okta service account has Read all permissions for all synchronized AD objects.

The Okta AD agent Management Utility also includes the option of adding the OktaService account to the Domain Admins group. If you require the functionality listed here but don't want to make your service account a full admin, make sure that the permissions are set for your appropriate use cases.

Use cases

These are the permissions that are needed for some optional use cases.

Provision user

The following permissions are required for a service account to provision users.

  • Requires Create Child permission for user objects on the target Organizational Unit (OU).
  • Requires Delete Child permission for user objects on the target OU.
  • Requires the Reset Password control access right for user objects within your target OU.
  • Requires write property permissions on user objects within your target OU for the following attributes:
    • mail
    • userPrincipalName
    • SAMaccountName
    • givenName
    • sn
    • userAccountControl
    • pwdLastSet
    • lockoutTime
    • cn
    • name
  • Requires write property permissions on user objects within your target OU for all other attributes mapped on the AD user profile in Okta. Mappings are listed under Directories at https://<org>/admin/universaldirectory.

Use the following commands in PowerShell to set the permissions for this use case.

dsacls "OU=targetOU,DC=domain" /G domain\agentserviceaccount:CCDC;user dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;mail;user dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;userPrincipalName;user dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;sAMAccountName;user dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;givenName;user dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;sn;user dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;userAccountControl;user dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;pwdLastSet;user dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;lockoutTime;user dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;cn;user dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;name;user

Update user attributes

The following permissions are required for a service account to update user attributes.

  • Requires write property permissions on user objects within your target OU for the following attributes:
    • mail
    • userPrincipalName
    • SAMaccountName
    • givenName
    • sn
    • userAccountControl
    • pwdLastSet
    • lockoutTime
    • cn
    • name
  • Requires write property permissions on user objects within your target OU for all other attributes mapped on the AD user profile at https://<org>/admin/universaldirectory.

Use the following commands in PowerShell to set the permissions for this use case.

# include other attributes that are mapped in your org within Okta dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;mail;user dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;userPrincipalName;user dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;sAMAccountName;user dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;givenName;user dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;sn;user dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;userAccountControl;user dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;pwdLastSet;user dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;lockoutTime;user dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;cn;user dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;name;user

Group push or Bidirectional Group Management

The following permissions are required for a service account to perform group push or Bidirectional Group Management. See Group Push and Bidirectional Group Management with Active Directory.

  • Requires create child permissions for group objects on the target OU.
  • Requires delete child permissions for group objects on the target OU.
  • Requires write property permissions on group objects within your target OU for the following attributes:
    • sAMAccountName
    • description
    • groupType
    • member
    • cn
    • name

Use the following commands in PowerShell to set the permissions for this use case.

dsacls "OU=targetOU,DC=domain" /I:T /G domain\agentserviceaccount:CCDCDT;group # If your use case requires that you grant the preceding permission only for child objects, you can replace /I:T with /I:S. dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;sAMAccountName;group dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;description;group dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;groupType;group dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;member;group dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;cn;group dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;name;group

Reset password, forgot password, and sync password

The following permissions are required for a service account to handle password resets, sync, and forgotten password use cases.

  • Requires write property permissions on user objects within your target OU for the following attributes:
    • lockoutTime
    • pwdLastSet
  • Requires Reset Password Control Access Right permission for user objects within your target OU.

Use the following commands in PowerShell to set the permissions for this use case.

dsacls "OU=targetOU,DC=domain" /I:S /G "domain\agentserviceaccount:CA;Reset Password;user" dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;pwdLastSet;user dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;lockoutTime;user

Activate and deactivate user

  • Requires write property permissions on user objects within your target OU for the following attributes:
    • userAccountControl

Use the following commands in PowerShell to set the permissions for this use case.

dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;userAccountControl;user

Command reference

Use the listed commands to add permissions. Save them to a batch file and change the target OU and service account information for your environment. Remember to remove permissions you don't need and add any attributes you have mapped for provisioning within Okta. You can get the complete list of user attributes from your directory user profile on https://<org>/admin/universaldirectory. Run dsacls commands from a PowerShell with admin privileges. To gain these privileges, use the Run as administrator option when launching PowerShell.

# Create and Delete User dsacls "OU=targetOU,DC=domain" /G domain\agentserviceaccount:CCDC;user # Create or Update User # include other attributes that are mapped in your org within Okta dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;mail;user dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;userPrincipalName;user dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;sAMAccountName;user dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;givenName;user dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;sn;user dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;userAccountControl;user dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;pwdLastSet;user dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;lockoutTime;user dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;cn;user dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;name;user # Create user/Password Reset dsacls "OU=targetOU,DC=domain" /I:S /G "domain\agentserviceaccount:CA;Reset Password;user" dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;pwdLastSet;user dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;lockoutTime;user # Group Push dsacls "OU=targetOU,DC=domain" /I:T /G domain\agentserviceaccount:CCDCDT;group # If your use case requires that you grant the preceding permission only for child objects, you can replace /I:T with /I:S. dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;sAMAccountName;group dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;description;group dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;groupType;group dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;member;group dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;cn;group dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;name;group