Install the Active Directory agent on the host
server
Navigation;
Okta
Admin UI->Directory->Groups
Important: To ensure that you have up-to-date functionality
and get optimum performance from your Okta AD agent(s), we strongly recommend
that you download and install the
latest version of the
agent on your designated host server(s). If you are running multiple Okta
AD agents, make sure that all of them are the same version.
Running
different versions within a domain can cause all agents in that domain to
function at the level of the oldest agent. This does not affect other
domains.
Note: If you want to download the agent from
another computer, you will need to copy the AD Agent installer to the host
server.
To install the AD agent:
1.
On the host server, sign in to Okta with your Okta
admin account that has a minimum role of Super Admin and
clicks Admin to access the Admin dashboard.
2.
Select Directory > Directory
Integrations.
a.
Click Add Directory and then
select Add Active Directory.
b.
Click Set Up Active Directory.
c.
Click Download Agent.
3.
On the host, the server locates the downloaded file
and double click the file to launch the installer.
a.
Click Yes at the message Do
you want to allow the following program to make changes to this computer?.
b.
Choose an installation destination. Click Next.
c.
Select the AD domain you want to manage with
this agent. Click Next.
d.
Select a domain user for the Okta AD agent
to run as and click Next:
·
Select Create or use the Okta Service
account (recommended) and complete the prompt to set a password. Okta
recommends using a complex password for security.
·
Select Use an alternate account that I
specify if you want to assign the Okta AD Agent to run as an existing
domain user.
e.
Optional — If appropriate for your
environment, specify a proxy server through which your AD agent will connect.
Click Next.
Note: If you are
installing an AD agent version 3.4.11 or later, in environments where internet
traffic is required to go through a proxy, the sign-in flow for the AD agent
installer uses the proxy settings specified within the installer. If no proxy
settings are specified, the machine defaults are used.
f.
To register the AD Agent with the Okta service,
enter your Okta subdomain name. This is the <mycompany> part
of the example: <mycompany>.okta.com. Click Next.
g.
On the Okta Sign In page, enter
your admin username and password, and then click Sign in.
h.
The Okta AD agent requires several permissions.
Click Allow Access. The agent installation completes.
Note: If the error
message displays:
The underlying connection was closed. Could not establish
trust relationship for the SSL/TLS service channel, see
Troubleshooting.
i.
Click Finish.
4.
When the Active Directory agent has started,
return to the browser and click Next. On the following screens, you
will select some basic configuration options. You can change these and other
settings at a later time.
a.
(First
time installations for this domain only) At the Connect an Organization Unit to Okta
screen, select the OUs from which you want to import users and groups.
b.
Select the Okta Username format that you want AD-imported end users to
use when logging in to Okta and then click Next.
Choose from:
·
Email address
·
SAM Account Name
·
User Principal Name (UPN)
Important: It is critical that the username format selected
here be the correct format when you first import users. Changing the value can
cause errors for existing users.
c.
On the Import
AD Users and Group dialog, click Next.
Note: To reconfigure
OU and import settings, as well as other settings, return to the
Settings tab
(
Directory > Directory Integrations > Active Directory >
Settings). For details, see
Configure import and
account settings.
5.
On the Build User Profile tab,
select the attributes that you want to use to build your Okta user profiles.
You can modify these attributes at a later time if you want to accept the
defaults at this time. Click Next.
To learn more about how Okta uses
profiles and attributes, see
Work with Active Directory
user profiles and attributes
6.
Click
Done. Agent setup is complete.
Your AD domain is now integrated with Okta. You are taken to the Settings tab
where you can configure your import and provisioning settings as described
in
STEP 2: Configure import and account settings
Troubleshooting:
Error when
installing the agent
During agent installation, if the error message displays,
The underlying connection was closed. Could not
establish a trust relationship for the SSL/TLS service channel
. . . then you are probably
attempting to install a version of the AD agent in which SSL pinning
is enabled by default and your environment is one in which the agent's support
for SSL certificate pinning prevents communication with the Okta server. This
is most likely to occur in environments that rely on SSL proxies. To allow
installation to complete in this case, Okta recommends that you bypass
SSL proxy processing by adding the domain okta.com to
a whitelist.
Alternatively, if SSL certificate
pinning is enabled you can choose to disable it as described below.
To disable
SSL certificate pinning if it is enabled
2.
Instead of double-clicking the file as directed
in step 5, open a command line terminal and enter the following:
OktaADAgentSetup.exe OktaDisableSslPinning=1
3.
Press Enter.
4.
Complete the installation as described in
Installing and
Configuring the Agent.
To
re-enable support for SSL certificate pinning if it is disabled
1.
Locate and open the AD agent configuration file:
C:\Program Files (x86)\Okta\Okta AD
Agent\OktaADAgentSetup.exe.config
2.
Change the SSL pinning enabled setting
to True:
"SslPinningEnabled" value="True"
3.
Save the configuration file and restart the
agent.
