Okta Active Directory
Deployment Guide
(Agent version 3.0.4 and
above)
Okta Inc.
400 2nd Street Suite 350
San Francisco CA, 94107
[email protected]
1-888-722-7871
Table of Contents
1
Introduction
1
System Requirements
1
Installing Active Directory Agent
1
Before you Begin
2
AD Agent Permissions
2
Okta Administrative user permissions
3
User permissions required to install the agent
3
Okta Service Account options
4
Installing and Configuring the AD Agent
5
Ensuring High Availability
6
Registering Multiple Domains on one Agent
6
Enabling Delegated Authentication
7
Allowing users to Reset AD password in Okta
8
Importing Users
9
Setting up Desktop SSO - Installing IWA Agent
10 Installing IWA Web App on a server with multiple Applications
11 Okta Service IWA authentication completion
12 Desktop SSO Configuration
12 Just in Time (JIT) Provisioning
13 Troubleshooting Login and App Access
13 Troubleshooting AD Agent issues
14 Troubleshooting IWA and Known Issues
Okta Active Directory Deployment Guide | 2
Introduction
Okta offers the industry’s most complete, robust and easy to use Active Directory integration that spans
authentication as well as user provisioning and de-provisioning. Like the core service itself, Okta’s AD
integration is also very easy to set up, manage and architected for high availability.
Active Directory Integration will automatically have the following default settings enabled.
•
Delegated Authentication will be enabled
•
Just in Time Provisioning will be enabled
•
The import schedule default will be set to 60 minutes.
How this works?
During the AD Agent install, you simply enter your OKTA URL and AD Administrative credentials and the
agent creates a low privileged, read only integration account and then securely establishes a connection
with your Okta instance - no network or firewall configuration required.
System Requirements
Minimum System Requirements
Windows Server 2003 R2 or later
20Mb memory for service
AD Service Account created upon agent installation
Suggested System Requirements
256 Mb of memory for Service
Dedicated AD Service Account with Domain users permissions
Separate server for Domain Controller (can be shared)
Installing Active Directory Agent
Before You Begin
1. Prior to running the AD Integration wizard, you need to create a non AD-mastered admin user to
login to Okta, which means that their password is Okta-specific and not tied to Active Directory.
2. If you are using a 3rd party service’s Delegated Authentication (Del Auth) Functionality, such
as Salesforce.com’s Del Auth functionality, where your Salesforce.com service is delegating
authentication into the service to another service (like Okta, or AD via Okta) then you should always
have a Salesforce.com admin login that is not assigned to a Del Auth-enabled profile. For example,
a Salesforce.com admin user whose password is Salesforce.com - specific, not their Active Directory
or other password.
Before installing the AD agent, make sure to review the following:
•
Install on Widows Server 2003 R2 or later - You need access to a Windows server to install the Okta
Active Directory Agent. You do not need to install the agent on the domain controller itself.
•
Must to be a member of your Active Directory Domain- The agent host server must be a member of
the same windows domain your Active Directory users belong to.
Okta Active Directory Deployment Guide | 1
•
Consider the Agent a part of your IT infrastructure- The windows server where the agent resides
must be on at all times. In other words, don’t install it on your laptop. The agent host server must
have a continuous connection to the internet so it can communicate with Okta.
•
Run AD setup wizard from the host server -We recommend running this setup wizard in a web
browser on the Windows server where you want to install the agent. Otherwise, you will need to
transfer the agent installer to the agent host server, then run the installer.
AD Agent Permissions
There are three accounts that you’ll need permissions for:
•
Okta Administrative user in the Okta Service (created within Okta)
•
An AD user account to run the AD Agent installer
•
Okta Service Account (created by the installer) - A Service account that the service runs as after
installation. This account can be created automatically by the installer, or you can select an existing
account. If you select an existing account, it will need to have the permissions detailed in this
section.
Okta administrative user permissions
You need to create a dedicated Administrative account within Okta before you begin installing the AD
Agent - this user should have an Okta specific password and not an Active Directory password. The AD
Agent connects to Okta using this account
1. From the People tab, click on Add person to create a user (e.g. [email protected])
2. Go to Security > Administration and click on the Add Administrators button.
Okta IWA Web Application Installation & Configuration | 2
3. Select which type of Administrator you’d like to make this new user. We recommend making them
organization or application administrators.
User Permissions required to Install the agent
If you are installing the AD Agent and letting the installer create the Okta Service account, then you will
need the following permissions:
•
Must be a member of the domain admins group.
•
Must have local administrator privileges
We need you to be a member of the domain admins group because we need to be able to create a new
AD user in AD that will act as the AD Agent service account.
If you are installing the AD agent, but using an existing user account to run as the service account, then
you will need the following permissions:
•
Local administrator privileges only
Regardless of which option you choose, the installer will grant “logon as a service” to the domain user
you select.
Okta Service Account Options
The Agent runs under the account you specified (either the Okta service account the installer created
or the domain user you selected). Depending on the configuration of your integration, the agent will
perform the following actions:
•
Read users, OUs, and security groups - Requires read access on the accessed objects. By default, a
domain user had sufficient permission to do this. We recommend read access on the entire domain
(s) but it is not required.
•
Authenticate users - Doesn’t require any special permissions
•
Change users passwords (by supplying the current password) - Doesn’t require any special
permissions.
•
Set user passwords (administratively, without the current password) - requires permissions to set
passwords on users.
Okta IWA Web Application Installation & Configuration | 3
Installing and Configuring
1. Make sure you created a non-AD mastered user described in the Before you Begin section.
2. Login to your Okta org (i.e. acme.okta.com) and go to People > Directories
3. From the Add Directory pulldown, select Add Active Directory.
4. On the Set up Active Directory page, click on the Set up Active Directory button.
5. This begins the Active Directory Set up wizard. Click on the Download Agent button to get started
6. Run the installer. On the Installation options screen, choose an installation destination
7. On the Select AD Domain screen, select which Active Director Domain you’d like to manage with
this agent.
8. On the Okta AD Agent Windows Service account screen, select Create or use the Okta Service
account (recommended) and complete the prompts to set a password.
Note: Select use an alternate account that I specify if you want to use an existing domain user for
the Okta AD Agent to run as.
9. On the Register Okta AD Agent Screen, enter your Okta credentials to register the AD agent with
the Okta service.
Run the installer. You’ll be prompted to enter the Active Directory domain you’d like to manage
with this agent and then create a new domain user for the Okta AD agent to run as and set a
password (the Okta service has no access to the password you set). This user will be used by all
agents managing the domain.
10. Enter your Okta credentials to register the AD Agent with Okta and follow the prompts to finish
the installation
11. On the Okta AD Agent Proxy configuration screen, you can specify a proxy server for your AD
Agent to connect through (optional)
12. Click Finish
13. You’ll need to go back to your browser page where you downloaded the Okta AD Agent from and
on the import settings tab, select with OU’s you’d like to import from, import frequency, and
what username you’d like to use for your users to login to Okta. You can make changes to these
import settings at anytime. Click Next.
14. On the Done! tab, click Done to complete the setup. This will begin the import process
That’s it! You have successfully integrated your active directory with Okta and your users will be able
to login to Okta with their active directory credentials.
Okta IWA Web Application Installation & Configuration | 4
Ensuring High Availability
You can install as many agents on separate servers/vms as you like for redundancy purposes - we
recommend setting up 2 or more agents per domain. The install instructions are the same as when you setup your first agent. If you created the Okta service
account with the first AD agent, then you’ll just be prompted to enter the password during the second
agent install. You can quickly check the status console on your dashboard in the administrative app to make sure the
second agent installed. If you see a green circle, it means the agent is connected and healthy.
How does AD agent handle request when HA is setup?
Each agent connects to the Okta service independently. When the service needs to talk to AD, for
example to authenticate a user, it picks one of the available agents and sends it a task to complete. If one
of the agents becomes unavailable, it is automatically removed from the queue and not given additional
tasks.
How does the service determine if an agent is available?
Agents send periodic messages to the services. If the service does not receive any messages for 120
seconds, it is marked as unavailable.
How does the AD Agent select a domain controller to talk to? The AD Agent relies on the underlying OS to select which domain controller to talk to.
Okta IWA Web Application Installation & Configuration | 5
Registering Multiple Domains on one Agent
Okta’s AD integration support also allows you to set up multiple domains from one AD agent, reducing
the number of VMs/machines you need to connect to multiple domains.
Registering multiple domains from one agent:
1. After you’ve installed the agent, you can add multiple domains in the OKTA AD Agent Management
Utility.
2. In the domain section, you’ll see a drop-down box marked with greyed out text “choose another
domain”. When you select the drop-down arrow, the trusted domains will begin to populate. You
can also type the domain directly in the drop-down field.
3. Select the desired domain and click Register.
Note: If you haven’t entered your Okta administrator credentials, you’ll be prompted to do so. You’ll
only need to enter these once.
4. That’s it! You’ll see a message indicating your new domain has been registered and asking you to
restart the agent. You can continue registering additional domains and restart once your finished.
Enabling Delegated Authentication Overview
Okta’s AD integration automatically turns on delegated authentication. That is, user login attempts to
mycompany.okta.com will be checked against Active Directory for authentication. Users can then easily
log into Okta using their Okta username and active directory password.
More specifically, the process is:
1. The user types username and password in the Okta end user home page. This login page is
protected with SSL and a security image to prevent phishing; multi-factor authentication (extra
security question or smartphone soft token) can be enabled as well.
2. The username and password are transmitted to an Okta AD Agent running behind the firewall over
the SSL connection that had previously been established during setup.
3. The Okta AD agent passes those credentials to the AD Domain Controller for authentication.
4. The AD Domain Controller responds with yes/no answer, validating the username and password.
5. The yes/no response is transmitted back to the Okta service by the Okta AD Agent. If yes, the user is
authenticated and sent to their Okta homepage
Okta Active Directory Deployment Guide | 6
Because this feature governs user access into Okta, the architecture supports multiple Okta AD Agents
running in your environment to provide higher throughput and redundancy. If one of the Okta AD Agents
stops running or loses network connectivity, the authentication requests are automatically routed to the
other Okta AD Agents.
With this authentication mechanism, the user’s password is never stored in the Okta service and Active
Directory is maintained as the immediate and ultimate source for credential validation. Because AD is
always relied upon for user authentication, changes to the user’s status (such as password changes or
deactivations) are reflected immediately in the Okta service.
Allowing users to reset AD password in Okta
Once you’ve integrated AD and enabled Delegated authentication, you can allow your users to change
their Active Directory password in Okta. Here’s how it works:
•
When their password has expired, they will be prompted to change it when they attempt to
login to Okta.
•
Users can also change their password from the account tab on their homepage.
To enable, go to Security > Authentication > Delegated Authentication, click edit and select Users can
change their Active Directory password in Okta.
Okta Active Directory Deployment Guide | 7
Importing Users
Once the Okta AD Agent is installed and the initial user import takes place, Okta intelligently
processes the results of the user import. Matching algorithms are applied to analyze the incoming
AD users and to determine if there is a match to existing Okta users or to accounts that you have
imported from other cloud systems (e.g., Google Apps). During import and account creation, a
duplicate account is created in the native Okta store that mirrors (field mapping and data) and
is associated with the imported AD account. Future user imports can be set to a schedule or
performed on demand.
Adding a User
When a user is added to Active Directory, the new object is detected by the Okta AD Agent and
automatically added to the Okta service. Only necessary fields are transmitted, including name, UPN,
SAMAccountName, email address, and security group membership. The Okta AD Agent never sends
passwords to Okta’s cloud service. Existing accounts in managed apps such as Salesforce.com or WebEx
can be imported and automatically matched against Active Directory users based on explicit rules or
heuristic matching.
Security Groups
Okta’s AD agent supports AD provisioning by security groups. When you import, all groups within
selected OU’s will be imported automatically. Groups imported into Okta are flattened, so all members
are listed as direct members rather than in a hierarchy. As such, each group that a person is a member of
in Active Directory, whether directly or via a parent, is listed as a direct parent in the Okta user interface.
Once imported, Active Directory security groups can be used as any other group in Okta, including
application assignments and multifactor authentication policies.
Okta IWA Web Application Installation & Configuration | 8
Setting up Desktop SSO
Installation Requirements
• The Okta IWA Web Application installs on a Windows Server 2008 R2 or Windows Server 2008
server.
•
The Web Application requires that IIS7.5 (Windows Server 2008 R2) or IIS7 (Windows Server 2008)
be installed on the server. If it is not installed, the installer will quit and you will see a message
informing you of this error.
•
We recommend that you install the IWA agent on a virtual machine or server that doesn’t have
any additional web applications installed. However, see the Installing on a server with multiple
applications section for additional steps you will need to complete.
•
AD Agent 3.0.4.x and above - This does not need to be on the same server that hosts the IWA Web
Application.
Installation
1. Login to your Okta org (i.e. acme.okta.com) and go to Security > Authentication > Active
Directory.
2. In the Desktop Single Sign-On section, click on the Download the Desktop SSO installer link
3.
Run OktaSsoIwa.exe .
4. Enter your Okta user credentials to register this IWA web application with Okta.
5. If you are installing the IWA web application on a virtual machine with other web applications,
there are a few additional steps you need to complete. Click on Installing iwa web app on virtual
machine with other web apps and follow the steps. If this doesn’t apply to you, continue to step 6.
6. Return back to your browser and reload the page.
7. In the Desktop Single Sign-on section, click Edit and select Test. Before testing, review the
following browser configuration posts that matches your OS: Configuring Desktop SSO Settings for Firefox, Internet Explorer, Chrome (Windows OS)
Configuring Desktop SSO Settings for Safari, Firefox, , Chrome (Mac OS)
8. After making any necessary browser configuration modifications, return back to the Desktop
Single Sign-on page and click on the provided test URL - if you are authenticated successfully
continue to step 9. If you are not authenticated, double check your browser settings in step 7.
9. After you have completed the test, return back to the same section and select On.
10. Click Save
That’s it - you have successfully installed the IWA web application and enabled Desktop SSO for your
organization.
Okta Active Directory Deployment Guide | 9
Installing IWA App on a server with multiple
applications
If you are installing the agent on a virtual machine with other web applications, there are a few
additional steps you will need to complete. If you are not installing the agent on a server with
multiple applications, you can skip to the Okta Desktop SSO configuration section.
1. Open IIS manager, right click on sites in the connection pane and select Add Web Site. You can name
it anything you’d like and make sure your settings match the following:
Application Pool Field - select DefaultApppool. This puts the new site into its own application pool
which should default to “Integrated” mode using .net 2.0.
Physical path field - make sure the site is pointed to where the main iis site file lives:
?:\inetpub\wwroot
The site will be created and you will see the directories underneath it, including the iwa directory.
2. In the connection pane, right click on Application Pools and select Add Application pool. You can
name it anything you want. Make sure your settings match the following:
•
.NET Framework version field - select .NET Framework v2.0 50727
•
Managed Pipeline Mode field - select classic
3. Expand the new site you created in step 1.
4. Right click on IWA directory underneath your new site and select convert to web application. Name
the web app and in the Application pool field, select the application pool you created in step 2 (.net
2.0 CLASSIC mode).
Note: The app pool should not be assigned to any other web app.
IIS begins the conversion and when you see the IWA update from a folder icon to a web app, you
know the conversion worked.
5. Click on the new site you created in step 1 and click on the authentication icon - Only anonymous
Authentication should be enabled and all other options be disabled.
6. Click on IWA underneath the new site and click on the authentication icon and make sure the options
match the following
Anonymous - Disabled
ASP .NET Impersonation - Enabled
Forms Authentication - Disabled
Windows Authentication - Enabled
7. Restart IIS
That’s it! You’re good to go!
Okta Active Directory Deployment Guide | 10
Okta Service IWA Authentication Completion
When the HTML form is received by the Okta service, the service decodes both base-64 encoded form
input elements.
The XML data structure is deserialized and the base-64 encoded encrypted limited lifetime token is
extracted from the data structure. This value is base-64 decoded and symmetrically decrypted using the
same secret key used by the service to encrypt the value. If more than 30 seconds has elapsed since the
creation of this token, the IWA authentication request will fail and the browser is redirected to the URL
https://mycompany.okta.com/login/default, which always displays the Okta login form, even when IWA
is enabled for mycompany.com and the request is originating from within one of the mycompany.com
gateway IP address ranges.
If less than 30 seconds has passed since the creation of the token, the validity of the signature of the XML
data structure is verified using the public key for mycompany.com stored in the Okta service.
Once the validity has been established, the user’s Active Directory identity is extracted from the XML data
structure, and the user’s matching Okta identity is determined.
If the user’s Okta account is valid, ( i.e. not deactivated or pending activation), an Okta session is
then created in the identity of the Okta userid, a cookie is returned to the browser, and the Okta IWA
authentication process completes successfully.
Okta IWA Web Application Installation & Configuration | 11
Okta Desktop SSO Configuration
After the IWA Web Application installation is complete, the admin needs to complete the following tasks:
1. Login to the Okta service, and from the administrative dashboard, select Security > Authentication.
2. In the Desktop Single Sign-on section, you can choose from the following:
Off - Disables Desktop Single Sign On for all users.
Test - Choosing this option gives you a URL (i.e. https://mycompany.okta.com/login/sso_iwa to test
your IWA Web Application. Users accessing Okta through other URLs, including the standard login
URL (i.e. https://mycompany.okta.com) will continue to see the standard login form.
On - This option enables SSO for users coming from authorized gateway IP address, enabling
them to automatically single sign on into Okta when they load the standard login URL (i.e. https://
mycompany.okta.com)
Note: You can always sign into Okta using the https://mycompany.okta.com/login/default sign-in
page, regardless of your selected Desktop SSO mode.
3. In the Settings section, you’ll see the Integrated Web Authentication Redirect URL. This is the
URL of the IIS Server where the Okta Single Sign on web application is running. The host and URL
attributes (port number, http versus https) are editable.
4. In the Gateway IPs field, you can enter one or more gateway IPs you want the Okta service to
use during the authentication process. There is already an initial value displaying from the Okta
IWA Web Application Installation. You can also specify one or more IP address ranges, with each
range entered as <IpAddressRangeLowBound> - <IpAddressRangeHighBound> (e.g. 192.168.0.1 192.168.0.255). Also, make sure each range is separated by a comma or specified on a separate line.
5. Click Save.
That’s it! Now your users can access the Okta service after logging into their windows network, from a pc
or a mac.
Just in Time Provisioning
By default, Just in Time (JIT) provisioning is enabled when you install the Okta AD agent and a user
account is automatically created in Okta the first time a user authenticates with Okta using one of
the following authentication methods: AD Delegated Authentication, Desktop Single Sign-on, or
Inbound SAML. In this way, valid AD users can provision themselves automatically into Okta and to the
appropriate cloud applications.
1. Login to the Okta service, and from the administrative dashboard, select Security > Authentication.
2. Click the JIT Provisioning tab and click Edit. Select Enable Just In Time Provisioning and click Save.
The process when Just in Time provisioning is enabled is:
1. A user who previously was not provisioned in the Okta service, attempts to log in to mycompany.
okta.com
2. Okta and the Okta AD agent check the user credentials against Active Directory
3. If the user is active in AD, a new user account is automatically created in Okta. The new user account
leverages their existing AD credentials.
4. Depending on their AD security group attributes, the user is automatically provisioned to
Okta Active Directory Deployment Guide | 12
to downstream cloud and web applications via the Okta service.
Troubleshooting Login and App Access
If users are having trouble signing into Okta, we recommend trying these:
1. Ask the user for the error message they see.
2. Try to login with your own okta user - this will confirm if the problem is specific to a user account or if
it is a general system issue.
3. Make sure that in the Administration area at least 1 AD agent is working (green status).
4. Check user status in Okta to make sure they show up as an Active Okta user.
5. If the user is entering credentials, please make sure they are typing in the same credentials as they
use to log into their corporate computer (domain credentials) . For example, if logging into computer
as vsedov with passwords xyz, their okta login should be vsedov with password xyz.
6. You can test if IWA is working by pointing your browser to http://<IWAURL>/IWA/authenticated.
aspx. If that page renders and shows your user information, it implies IWA functioning.
7. Check the Okta system Log for errors.
Trouble signing into Applications
1. The okta plugin is required for access to SWA applications. Please make sure the plugin is installed on
the user’s machine. The plugin can always be installed from the Okta home screen using the link in
the bottom right hand corner.
•
In Chrome, you can check for the plugin under the wrench menu, then tools, and then
extensions submenu.
•
In Firefox, you can check for the Okta plugin via the tools > Addons
•
In Internet Explorer, you can go to Tools > Manage Addons menu.
Troubleshooting AD Agent Issues
We recommend the following checks within the okta web interface, before looking at the servers in
detail:
1. Try to login yourself and reproduce the error. Try alternative browsers (i.e. firefox, Chrome, or safari)
2. If there is no error in the UI, check the Okta system log, accessible through the Administration area
for errors in the same time period
3. If the user is having trouble logging into the Okta system from the remote location, it is likely related
to the okta AD agent.
4. If the user is having trouble logging into okta from within the office it is likely related to IWA.
5. In either scenario, capture the error from the user. Check the Okta system log with the user
experience). The following details will help the Okta ops team.
Okta IWA Web Application Installation & Configuration | 13
If AD agent related - the name of the AD Agent will tell you which agent failed to authenticate the user.
The agent name can be seen in the system log, when you correlate the user error with a log entry. Copy/
paste the error and time stamp from the log so you don’t forget the values when looking in the server
logs.
IF IWA related a screenshot from the user will help greatly - the screenshot will show which one of the 2
IWA servers serviced the request. In this case, try and identify the server name in the url and note the
timestamp.
Troubleshotting on-prem: General and AD Agent
Before Troubleshooting the servers it helps to have the following information available:
1. Check if it is the AD Agent or IWA experiencing problems.
2. Name of server which serviced the request
3. Timestamp of error
4. Error messages or screenshot of the error message
Once you receive this information there are a few places on the server you can check to get more
information about the error:
For AD Agent related issues:
1. Check the Agent console status by opening the Okta Agent console from the Start menu of the
server hosting the agent. The agent console window presents errors directly on screen if the agent is
not running or is having trouble connecting.
2. The AD Agent writes a log to c:\program files x86\okta ad agent\logs\agent.log. The log is time
stamped and logs every action the agent takes.
3. Correlate the log time stamps with the input from the user’s help request.
4. The primary dependency for the AD Agents is internet connectivity and that the server hosting the
agents is connected to a domain controller to authenticate credentials.
5. You can safely restart these machines, our AD Agent service starts up automatically at server startup
as a service. If you suspect AD connectivity was interupted, try rebooting the server.
Troubleshooting Logins: IWA and known issues
On the server hosing IWA - check the Event Viewer under Application and Service logs > Okta Single Sign
on log. The log will reveal any problems specific to the IWA web app.
If the Okta single sign on event viewer log does not have entries, check the event viewer for Windows
Systems and Windows applications for general server or IIS problems
The primary dependency is that the IWA mahcine must be able to connet to the domain controller to
authenticate users.
If needed it is perfectly ok to restart these machines, IIS and our web app will restart automatically.
General Known Issue: Lack of connectivity to Domain or Internet. Reboot tends to fix this issue.
Okta IWA Web Application Installation & Configuration | 14