Install and configure the Okta IWA Web agent for Desktop Single Sign-on

Okta IWA is a lightweight Internet Information Services (IIS) web 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. that enables Desktop Single Sign-on (DSSO) on the Okta service. DSSO allows users to be automatically authenticated by Okta and any apps accessed through Okta, whenever they sign into your Windows network. The Okta IWA Web agent uses Microsoft's IWA and ASP.NET to authenticate users from specified gateway IPs. 

Okta strongly recommends that you transition to using Secure Sockets Layer (SSL) with the on-premises agent. This is not only an important security provision, but it is also a hard requirement for application authentication (in particular, Windows 10 Universal Applications such as OneNote, Mail).

Note: The latest builds of Office 2016 and Windows 10 are incorporating their Web Account Manager (WAM) for sign-in workflows (see this Microsoft article). WAM requires https — it blocks non-https traffic during auth workflows. Refer to Configure SSL for details about how to configure IWA for this use case.

When re-enabling IWA DSSO, Identity Provider (IDPAn acronym for Identity Provider. It is a service that manages end user accounts analogous to user directories such as LDAP and Active Directory, and can send SAML responses to SPs to authenticate end users. Within this scenario, the IdP is Okta.) routing rules must be manually reactivated.

Prerequisites

• You must have installed and configured the Okta AD agent and Delegated AuthenticationAuthentication is distinct from authorization, which is the process of giving individuals access to system objects based on their identity. Authentication merely ensures that the individual is who he or she claims to be, but says nothing about the access rights of the individual. Authentication methods and protocols include direct auth, delegated auth, SAML, SWA, WS-Fed, and OpenID Connect. must be enabled before you can configure IWA DSSO. For details, see Install and configure the Okta Active Directory agent
• Make sure that Port 80 (for http) and Port 443 (for https) are open for inbound traffic on the same server that hosts the Okta IWA Web agent.

  Note: Okta strongly recommends that you enable SSL.

• Windows Server 2008 R2, Windows Server 2012, Server 2016 or Windows Server 2019 and higher. Although the IWA Web Agent will also work with Windows Server 2008, for best results, Okta recommends Windows Server 2008 R2 and Windows Server 2012.

  If you use Windows Server 2008 R2, keep in mind the following:

  • Microsoft requires Windows Server 2008 R2 users to have an extended support agreement. Also, Microsoft plans to EOL Windows Server 2008 R2 by 2020.
  • Additional security configuration is required if your IWA Web agent is installed on a server running Windows Server 2008 R2. For more information, see Enabling TLS 1.2 on Windows Server 2008 R2.
• .NET 4.5.2 (minimum) up to  .NET 4.6.x  and ASP .NET 4.5.  If you have a lower version of .NET, upgrade to 4.5.2 or higher.

• To improve the security of our integrations, we now only communicate using TLS 1.2 security protocol. Ensure you are running .NET framework 4.5.2 or later so the AD agent installs correctly. For Windows 2008 R2 TLS 1.2 is disabled by default and must be enabled through the registry. If you have Windows 2008 R2, ensure the following regkeys are set correctly:

  [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Server] "Enabled"=dword:00000001

  [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Server] "DisabledByDefault"=dword:00000000

  [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\ClientEssentially, a client is anything that talks to the Okta service. Within the traditional client-server model, Okta is the server. The client might be an agent, an Okta mobile app, or a browser plugin. ] "Enabled"=dword:00000001

  [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Client] "DisabledByDefault"=dword:00000000

• IIS 7.5 or higher must be installed on the server. If the required IIS version is not installed, the installer quits and you receive an error message.
• AD Agent 3.0.4.x or higher. The Okta AD agent does not have to be on the same server that hosts the Okta IWA Web agent. 
• If your enterprise has more than one 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)., see the topic Configuring UPN Transformation.
• If your IWA Web agent is installed on a Virtual Machine (VM) with other web apps, see this topic.

• The IWA agent doesn't require any extra privileges beyond the default permissions the user inherits from the Domain Users group. However, note the following:

  • The installer configures some additional local permissions for the service account to allow it access the web-application files.
  • The IWA agent requires read and execute permissions for files in C:\inetpub\webroot\IWA.
  • If you want to use an existing account, then ensure:
    • the account is active and the password never expires
    • the account has permissions to read and execute for the C:\inetpub\wwwroot\IWA directory and its content

Just-in-Time provisioning

When you implement on premises or agentless Desktop Single Sign-on (DSSO) in your environment, this is the process flow when users are imported using Just-in-Time (JIT) provisioning:

• For on premises DSSO, IWA sends Okta the Universal Principal Name (UPN). Okta uses the UPN to locate a user. Okta does not perform user authentication because KerberosKerberos is a computer-network authentication protocol that works on the basis of tickets to allow nodes communicating over a non-secure network to prove their identity to one another in a secure manner. validation is done on the IIS side.

• For agentless DSSO, the web browser sends the Kerberos ticket to Okta, and relies on the AD agent to look up the UPN. Kerberos validation is done in the cloud in Okta.

When a user signs in using DSSO:

• If their information is already imported and active in Okta: Okta uses the UPN to look up the user. If Okta finds the user, the profile reloads from Active Directory (AD) and the user signs in successfully.
• If their information has been imported but is not yet active in Okta: Okta uses the UPN to look up the user. If Okta finds the user, the user profile loads from AD, the user is activated, and the user signs in successfully.
• If their information has not been imported into Okta and JIT is enabled: Okta can only validate the user by the UPN. So the Okta user name format must be the UPN in order for the user to be successfully imported with JIT enabled. If the user name format is something other than the UPN, for example the email address or SamAccountName, the search cannot locate the user.
• If the their information has not been imported into Okta and JIT is off: Sign in fails.

---

Install the Okta IWA Web agent

The Okta Administrative Account that will be used during IWA Agent installation must have Super adminThe super admin receives full access to every item in the Administrative Console and is the only role that can assign administrator roles to other user accounts. Accounts with other administrator role assignments have reduced functionalities to different permission sets. Contact Okta support to create an Okta Mastered account with Super Admin rights. permissions.

Note: When you install the IWA agent the IP address of the client is added to the LegacyIPZone. For details, see Network Zones and IWA.

1. While signed in with the 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. count for the IWA agent, navigate to the Administrator console > Security > Delegated Authentication > Active Directory. 
2. In the Desktop Single Sign-On section, click the Download Agent link.
3. Double-click the installation file OktaSsoIwa-x.x.x.
4. Click Run.
5. Click Next.
6. At the Web Application Pool Identity dialog box, select Create or use the OktaService account, then click Next.
7. (Optional) When prompted, you can specify a proxy server for your IWA Web agent to connect through.
8. On the Register Okta Desktop Single Sign-On screen, select an environment (Production, Preview, or Custom), enter your Okta customer subdomain name, and then click Next.
9. On the Okta Sign In page, enter your Super admin username and password, and then click Sign In.
10. To grant permission to access the Okta API, click Allow Access.
11. At the message Installation completed, click Finish.
12. Return to your browser and reload the Security > Delegated Authentication > Active Directory page.

Configure browsers for SSO

How you configure your browsers will depend on the OS being used.

Note: The Microsoft Edge browser is not supported.

Configure browsers for SSO on Windows

Recommendation: Although IWA SSO may work if you choose not to configure your browser as described in this section, Okta strongly recommends that you review the relevant information for your browser type and then configure your browser as described if appropriate for your environment.

1. Add your Okta tenant URL and the URL of the server that hosts your Desktop SSO IWA Web agent to your trusted zone:

   Note: The URL hostname.companyname.com is the fully qualified domain name of the server in question.  For example,  my-iis7-host.corp.acme.com. It is not sufficient for this URL to be listed as a Trusted Site in the Trusted Sites zone.

   Most organizations set up a Group Policy to configure this setting in their users' Internet options.

   1. On your Windows Control Panel, select Network and Internet > Internet Options > Security > Local intranet > Sites > Advanced.
   2. In the Add this website to the zone field, enter:

      https://hostname.companyname.com or http://hostname.companyname.com

      and

      https://_subdomain_.okta.com or https://_subdomain_.okta-emea.com or https://_subdomain_.oktapreview.com as appropriate.

   3. Click Add.
   4. Click OK twice to close Internet Options.
2. Configure your browser.

   Setting up IWA is different for each browser. See the setup instructions below for your browser.

   Windows Internet Explorer (Windows)

   1. In Internet Explorer select Tools > Internet Options.
   2. Click the Advanced tab, scroll down to the Security settings, and select Enable Integrated Windows Authentication.
   3. Click OK.

   Note: Make sure that Internet Explorer can save session cookies (Internet Options > Privacy tab). If it cannot, neither SSO nor standard sign in can work.

   Mozilla Firefox (Windows)

   The following configuration permits Firefox to properly pass the Kerberos ticket with IWA, but Firefox still warns the user about the transition from an HTTPS page to an HTTP page. To resolve this issue, deploy IWA in HTTPS mode.

   1. In the Firefox address bar enter: about:config

      Note: In Firefox version 3.x and later, a warning message displays. Click the button to clear the message and proceed.

   2. When the configuration page loads, enter the following in the Search field:

      network.negotiate-auth.trusted-uris

   3. In this field list the host name of the IWA server(s), separating multiple values with a comma  ','  if two or more IWA instances are deployed.

      Okta recommends that you enter the fully qualified domain name (FQDNA fully qualified domain name (FQDN) is the complete domain name for a specific computer, or host, on the internet.) of your IWA host servers. If you do not, you will also need to toggle the following values to TRUE:

      Note: If you enter more than one host name, the order does not matter.

      network.automatic-ntlm-auth.allow-non-fqdn

      network.negotiate-auth.allow-non-fqdn

   4. Right click the Value column for each of the above and toggle the value to True.
   5. Click OK.

   Google Chrome (Windows)

   IWA is automatically enabled on Chrome for Windows and the capability is whitelist-driven. If your browser is asked by a site to provide the Kerberos ticket, the browser only supplies the ticket to the site if the site is on a whitelist.

   The whitelist is provided to the browser at startup using this command-line parameter:

   --auth-server-whitelist=

   For example:

   --auth-server-whitelist="*hostname.companyname.com"

   This tells Chrome that any URL ending in hostname.companyname.com is in the permitted list.  Without the '*' prefix, the URL has to match exactly.

   Note: The hostname.companyname.com value refers to the server hosting the Okta IWA Web agent.

   If the '--auth-server-whitelist' command-line parameter is not specified at startup, the permitted list includes the servers in the Local Machine or Local Intranet security zone. This behavior is consistent with Internet Explorer.

   To start Chrome on Windows and supply this command-line parameter:

   1. Right click your desktop Chrome icon or select Start > All Programs > Google Chrome and right click Google Chrome, and then select Properties.
   2. In the Target field, move the cursor to the end of the existing value and add the text of your new command-line parameter.
   3. Click OK.

Configure browsers for SSO on Mac

Recommendation: Although IWA SSO may work if you choose not to configure your browser as described in this section, Okta strongly recommends that you review the relevant information for your browser type and then configure your browser as described if appropriate for your environment.

Setting up IWA is different for each browser. See the appropriate section below for the setup instructions for your browser.

Google Chrome (Mac)

IWA capability is enabled automatically in Chrome on OS/X, and just like on Windows, the capability is governed by a whitelist. If a site asks your browser to provide the Kerberos ticket, the browser only provides the ticket if the site is on the whitelist.

1. Launch the Terminal application.
2. Create a Kerberos ticket for the account:

   kinit username@example.com

   . . . replacing username@example.com with your actual username and domain. Enter your password when prompted.

3. Configure the Chrome whitelist:

   $ defaults write com.google.Chrome AuthServerWhitelist "*.example.com"

   $ defaults write com.google.Chrome AuthNegotiateDelegateWhitelist "*.example.com"

   . . . replacing example.com with your actual domain.

Activate the IWA Web agent

After you have configured all the settings appropriate to your environment and tested Desktop SSO, do the following:

1. Return to Security > Delegated Authentications > Desktop Single Sign-On.
2. Click Edit and select On.
3. Click Save.

Configure SSL

To ensure a secure connection between your Okta IWA Web agent agent and cloud apps, configure Secure Socket Layer (SSL). This is important for security, but it is also a hard requirement to enable some applications to successfully authenticate (in particular, Windows 10 Universal Applications such as OneNote, Mail and more). For more information, see https://support.okta.com/help/Documentation/Knowledge_Article/Cannot-sign-into-an-Office-2016-application-on-Windows-10.

Note: If your IWA Web agent is installed on a server running Windows 2008 R2, you may need to Enable TLS 1.2 on Windows Server 2008 R2.

Acquire an SSL certificate

We strongly recommend acquiring an SSL certificate from a third-party certificate authority such as GoDaddy, Verisign or Digicert. If you are unfamiliar with creating a certificate signing request and installing an SSL certificate, refer to the documentation provided by your chosen Certificate Authority. The following guides from DigiCert are useful references:

Certificate Signing Request (CSR) Generation Instructions

How to install an SSL Certificate in Microsoft IIS 7.0

Certificate creation notes and considerations

• We strongly recommend acquiring a certificate that has one or more Subject Alternate Names (SANs). If the certificate does not contain a SAN, Firefox and Chrome users will encounter an error when their browser attempts to connect to the Desktop SSO web site.
• The IWA Redirect URL(see step 4 of Enable SSL) must match what is entered in the CN or SAN. For example:
  • If you plan to use the server’s host name as the IWA Redirect URL (for example, https://IWAserver/IWA), the CN or SAN values would be “IWAServer”.
  • If you plan to use the server’s FQDN as the IWA Redirect URL (e.g. https://IWAserver.mycompany.com/IWA), the CN or SAN values would be “IWAserver.mycompany.com”.
  • If your certificate’s CN or SAN value is IWAserver, an attempt to connect to https://IWAserver.mycompany.com will fail because the URL will not match what is specified in the certificate..
• If you plan on installing Desktop SSO on multiple servers to provide fail over, we strongly recommend acquiring a wild card certificate (for example: *.mycompany.com) OR a certificate that contains SAN entries for each server’s URL (for example:  https://IWA1.mycompany.com, https://IWA2.mycompany.com, etc). This will allow you to use the same certificate on each server.

Enable SSL

Once the certificate has been installed:

1. Log in to your Okta orgThe Okta container that represents a real-world organization. and go to Security > Delegated Authentication > Active Directory.
2. Scroll down to Desktop Single Sign On and click Edit.
3. In the IWA Agents section, click the edit icon.

   

4. Change the IWA redirect URL from http to https.
   The IWA Redirect URL must use the same naming convention used in the Common Name field. That is, if the FQDN or host name was used in the Common Name field, it must also be used in the IWA Redirect URL.

   

5. Click Save.
6. Test the configuration as described in Testing Your IWA Web agent.

Configure Routing Rules

All network rules and access rules are configured using Identify Provider Discovery. Ensure your Identity provider has on-prem IWA Desktop SSO. For information on configuring routing rules, see Routing Rule Configuration.

If you turn off IWA DSSO, the IWA Routing Rule will be switched to Inactive. The next Routing Rule will be used to direct your users to the appropriate sign in. When you turn IWA DSSO on again, you must also switch the IWA Routing Rule to Active again.

Test your IWA Web agent

After you download and install your IWA Web agent, test it to make sure the IWA server is working from a client machine. Do the following:

1. From your Administrator Dashboard, go to Security > Delegated Authentication > Active Directory, scroll down to Desktop Single Sign-On.
2. Click Edit.
3. In the IWA Agent section, click the edit icon.
4. Select and copy the IWA redirect URL.
5. Paste the IWA redirect URL in a browser that has been configured for SSO, and then add authenticated.aspx to the end of the URL. For example, if your IWA redirect URL is http://WIN-GTVLLAG671R/IWA/ enter http://WIN-GTVLLAG671R/IWA/authenticated.aspx in your browser.
6. Press Enter on your keyboard.

   If you configured IWA correctly, three rows of results are returned similar to the following:

   

   If the Okta Sign-In page displays instead of the success message, the test failed.

Test Desktop SSO

After you have installed and configured your IWA Web agent and set up your browser, do the following:

1. From your Administrator Dashboard, go to Security > Delegated Authentication > Active Directory, scroll down to Desktop Single Sign-On.
2. Click Edit.
3. Select Test, and then click the provided test URL.

   If you are authenticated successfully, continue to the following step. If you are not authenticated, check any browser configuration changes that you may have made in either Configuring Desktop SSO with IWA for Windows or Configuring Desktop SSO with IWA for Mac.

4. Click Save.

View the status of your IWA Web agents

1. Go to Security > Delegated Authentication > Active Directory.
2. In the Integrated Web Authentication (IWA) Web Applications section, select an IWA Web agent.

The section expands, displaying the status of the selected web agent.

You can also check the system logs for information related to your IWA Web agents. For example, if your primary IWA Web agent goes offline, your system logs report when it happened and the promotion of the backup IWA Web agent. To view the report, go to Reports, and then click Active Directory Agent under System Logs.

---

Optional tasks

---

Related topics

Network Zones and IWA

Configure Agentless Desktop SSO

Configure a custom error page

Install and configure the Okta Active Directory agent

Top