Install and configure the Okta IWA Web agent for Desktop SSO

When you have only one forest it doesn't matter to which IWA agent requests are routed. When you have multiple forests, you need to start taking network configuration into consideration. You need to ensure that user A on machine A only redirects to IWA agents that are in forest A, and user B on machine B only redirects to agents that are in forest B. The suggested way of doing that is redirecting the traffic from Okta to a global redirect URL, and then setting up your on-prem DNS to do the correct routing for that endpoint. You may also need to set up on-prem load balancing and the ability to detect which agents are online and offline into your load balancer.

• 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, please 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 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

  
  

Okta strongly recommends that you transition to using Secure Sockets Layer (SSL) with the on-premises agent. This is important to provide the utmost security, but it is also a hard requirement for some applications to successfully authenticate (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.

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.

To install the Okta IWA Web agent:

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.

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 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. 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.

OS/X Safari

IWA is enabled automatically in Safari on OS/X. Make sure that the OS/X host is a Windows domain member. For how to add your Macintosh OS/X host to a Windows domain, see the article OS X Mountain Lion: Join your Mac to a network account server.

Mozilla Firefox (Mac)

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: Firefox3.x and later displays a warning message requesting that you proceed with caution.

2. After 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.

   Note: The order does not matter if you enter more than one host name.

   We recommend that you enter the fully qualified domain name (FQDN) of your IWA host servers. If you do not, you will also need to toggle the following values to TRUE:

   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 (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.

To manage the Chrome 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.

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.

To ensure a secure connection between your Okta IWA Web 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.

STEP A: 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, please 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 (e.g. https://IWAserver/IWA), the CN or SAN values would simply 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.

STEP B: 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.

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.

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.

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.

1. Go to Security > Delegated Authentication > Active Directory.
2. In the Integrated Web Authentication (IWA) Web Applications section, select the desired 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.

As you configure Desktop SSO (on prem or agentless) in your environment, be aware of how the Desktop SSO flow works when importing users and how Just in Time (JIT) authentication will occur.

• If using on-prem DSSO IWA always sends Okta the Universal Principal Name (UPN). This is the only data Okta uses to look up a user. Okta does not perform authentication for users because Kerberos validation is already done on the IIS side.

• If using Agentless Desktop SSO, your web browser sends the Kerberos ticket to Okta, and relies on the AD agent to look up the UPN. The Kerberos validation is now done in the cloud in Okta.

When a user tries to sign in using Desktop SSO:

• If the user 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 AD and the user signs in.
• If the user is imported but not yet active in Okta: Okta uses the UPN to look up the user. If Okta finds the user, the profile loads from AD, is activated and the user signs in.
• If the user has not been imported into Okta and JIT is on: 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 turned on. If the user name format is something other than the UPN, for example the email address or SamAccountName, the search will fail to locate the user.
• If the user has not been imported into Okta and JIT is off: User sign in will fail.

You can install multiple IWA Web agents on separate servers for high availability purposes. Installing multiple web agents in close geographical proximity to your users may improve performance when combined with regional load balancing technologies. One example is having DNS netmask ordering enabled.

Updated agent releases can be found under Settings > Downloads.

You do not need to uninstall existing agents prior to upgrading to a new agent. The installer keeps copies of all previous configurations, renaming existing Web.config file with a time stamp suffix (for example, web.config.636531690091372202).

After updating the agent you must port any previous custom edits to the new config file.

During the upgrade process the agent will not be able to handle requests. Users will see a 404 or 500 error page when IWA agent is being upgraded.In environments with multiple IWA servers, we recommend you manually fail over to a secondary IWA server while the primary is undergoing an upgrade.

With Desktop SSO (DSSO) enabled, users are redirected to the Sign In page when they sign out of their account. When this occurs, DSSO recognizes that a user has landed on the Sign In page and the user is automatically signed back in to Okta. To avoid this, you can configure DSSO to send the user to a page that bypasses DSSO. Perform these steps:

1. From your Administrator Dashboard, go to Settings > Customization> Sign-Out Page.
2. Click Edit.
3. Select Use a custom sign out page.
4. Enter the URL of your Okta tenant, followed by /login/default. For example: https://MyCompany.okta.com/login/default

The default log on address bypasses DSSO and will present the standard log on page to the user.

Fail over settings determine what users experience if your primary IWA agent goes offline. You can check your System Log to see when a fail over occurred and the backup IWA Web agent was promoted.

1. Go to Security > Delegated Authentication > Active Directory.
2. Click Edit in the Desktop Single Sign-On section.
3. Under Failover, select the fail over setting appropriate for your environment.
   • Only redirect to primary IWA agent (default)

     When selected, if the primary IWA agent goes offline, users are redirected back to the primary IWA agent when it is brought back online. You would typically select this option if you have not configured a backup IWA Web agent or you do not want to redirect users to a global redirect URL.

   • Redirect to backup IWA if primary goes offline

     When selected, Okta automatically switches to a healthy IWA Web agent if your primary IWA Web agent goes offline. Your AD Agent checks the health of each IWA Web agent that you have set up.

   • Only redirect to the following URL

     When selected, users are redirected to a URL that you specify. This is typically used to direct to a load balancer.

4. Click Save.

Your IWA Web agent may go offline and your AD Agent may report an error(The request was aborted: Could not create SSL/TLS secure channel) if your IWA Web agent is:

• Installed on a server running Windows Server 2008 R2 SP1, and
• Configured to use HTTPS, and
• Configured for Automatic Fail over.

If your IWA Web agent is installed on a server running Windows Server 2008 R2 SP1 and you want to use SSO IWA over secured connections (HTTPS), you must first enable the TLS 1.2 protocol for incoming (e.g. IIS) connections. This is necessary because the AD agent, which tries to use TLS 1.2 whenever possible, may lose connectivity with IWA Web agents installed on Windows Server 2008 R2 SP1 servers that are not enabled for TLS 1.2 incoming connections. Windows Server 2008 R2 SP1 supports TLS 1.2 protocol outgoing connections by default. However, support for incoming connections is disabled by default. Okta strongly recommends enabling this setting.

To enable TLS 1.2 incoming connections, edit the registry as follows:

1. On the same Windows 2008 R2 server that hosts your IWA Web agent, add the following values to the registry:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Client\DisabledByDefault : 0 (DWORD)

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Client\Enabled : 1 (DWORD)

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Server\DisabledByDefault : 0 (DWORD)

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Server\Enabled : 1 (DWORD)

2. Restart the server.

More information is available online here and here.

You can configure a custom error page to which end usersIn Okta literature, we generally refer to "end users" as the people who have their own Okta home page (My Applications), using chiclets to authenticate into all of their apps. End users do not have any administrative control. When we refer to "users" we are generally referring to the individual(s) who have administrative control. are redirected if Okta fails to process their IWA token. This option is useful if you embed Okta into your solution and you want to control end-to-end branding to enhance the end user experience. The custom error page you specify applies to all IWA users in your organization.

Note: The custom error page setting does not apply to sign in failures caused by an unknown user or a JIT failure. In these cases, users are redirected to their Okta sign-in page.

Note: This applies only to enterprises with more than one domain, and requires IWA Web agent Version 1.8.1 or later.

Use case

In Windows Active Directory, the Universal Principal Name (UPN) is the name of a system user presented in an email format. You need to configure UPN transformation on your IWA Web agents if the following applies to your enterprise:

1. Your company has more than one domain.

. . . and

2. The domain that your users specify when they log in to work is different from the domain that your Okta org is built upon.
   
   For example:

— Your users log in to work using username@abc.com.

. . . and

— Your Okta org contains user names such as username@xyz.com.

In this case, the authenticated user names that your company sends to Okta will not match the user names in your Okta org. Instead of being signed in to their Okta dashboards automatically, your users will be prompted to enter their credentials. To fix this, add a rule in the web.config file to transform the authenticated user names that your company sends to your Okta org.

Procedure

1. Navigate to C:\inetpub\wwwroot\IWA and open the file web.config.

2. Insert the following rule inside the <upnTransformation> element (a child of the <oktaSSOConfigGroup> element). The rule will convert all user names from the domain
   abc.com to the domain xyz.com:

<upnTransformation> <rule match="(.+)@abc\.com" replace="${1}@xyz.com" /> </upnTransformation>

The same logic can be applied to other common use cases such as transforming company.local to company.com, or company.com to company.okta.com

How the UPN Transformation code works

The match attribute specifies a regular expression that the IWA Web agent uses to check UPNs. If a UPN matches a UPN transformation rule, the IWA Web agent uses the expression specified by the replace attribute to compute a transformed UPN. For more information, see:

• match syntax: https://msdn.microsoft.com/en-us/library/az24scfc(v=vs.110).aspx
• replace syntax: https://msdn.microsoft.com/en-us/library/ewy2t5e0(v=vs.110).aspx

The IWA Web agent checks all rules consecutively in the order that they are specified in the configuration file and applies the first rule that matches the UPN. If no rule matches the UPN, the IWA Web agent sends the original UPN to Okta.

Administrators can use the /IWA/authenticated.aspx page to verify and debug the transformation rules.

You can configure how long the agent tries to automatically sign users in to apps before redirecting them to the Okta Sign-In page. This is useful for extending the 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. authentication timeout period in environments with slower networks.

1. On the same server that hosts the IWA Web agent, navigate to C:\inetpub\wwwroot\IWA and open the file web.config.
2. Search for the element <iwaDetection timeout="1000" /> and modify the timeout attribute (given in milliseconds).

   Increase the attribute value if you want to give the agent more time to detect IWA SSO capability before redirecting the user back to the Okta Sign-In page.

3. Save and close the web.config file.

Note: For more about this functionality, as well as other ways to improve security and usability for your end-users, see the blog Tips and Tricks with Okta's Desktop SSO (DSSO) Agent. You may be prompted to sign in to the Okta Support site to view content.

By default, the IWA Web agent attempts IWA SSO for all clients that try to access Okta-protected apps. You can change the default by creating an IIS rewrite rule that automatically redirects specified clients to the Okta Sign-In page without attempting IWA SSO. Your rule uses pattern matching to detect non-IWA SSO-capable clients and then performs the configured action.

Note: The following procedure requires Okta IWA Web agent version 1.9.1 or higher.

1. Download the Microsoft URL Rewrite 2.0 module from http://www.iis.net/downloads/microsoft/url-rewrite.
2. Install the rewrite module on the same server that hosts your IWA Web agent.
3. Open Internet Information Services (IIS) Manager on the same server that hosts your IWA Web agent.
4. Under Connections (on the left side), expand Sites > Default Web Site and select IWA.

   

5. Double-click the URL Rewrite icon in the center pane.
6. See Microsoft documentation for detailed instructions on creating rules for the URL Rewrite Module. You can also refer to the example URL rewrite rules that are provided in the web.config file (C:\inetpub\wwwroot\IWA\web.config).

   You can configure these rules:

• To attempt IWA authentication for specified clients, configure this action:

action type="Rewrite" url="iwa.aspx?action=iwa"

• To skip IWA authentication for specified clients and redirect users to the Okta Sign-In page, configure this action:

action type="Rewrite" url="iwa.aspx?action=okta"

7. Under Actions (on the right side), click Apply.
8. Restart Internet Information Services (IIS) Manager.

1. Install and configure the IWA Web agent as described in PROCEDURE.
2. On the same server that hosts your Okta IWA Web agent, open the Internet Information Services (IIS) Manager.
3. Right click on Sites and select Add Web Site.
4. Enter a name for the site, and then click Select.
5. In Application pool, make sure DefaultAppPool is selected, then click OK. This puts the new site into its own application pool that defaults to Integrated mode using .NET 2.0 for the site.
6. In the Physical path field, make sure the site points to the location of the main IIS site files: ?:\inetpub\wwwroot.
7. Click OK.

   The site is created and the directories display under it, including the IWA directory.

8. Expand the site that you created at the beginning of this procedure.
9. Right click IWA and select convert to web application.
10. Name the web app IWA.
11. In Application pool, select OktaIWA application pool.

    Note: Do not assign this application pool to any other web app. Use it only for Okta.

    The IWA icon changes from a folder to a web app icon to indicate that the conversion was successful.

12. In the Connections pane, click on the site you created (Tip: click the globe icon).



13. In the center pane, double click Authentication. Check that only Anonymous Authentication is enabled.
14. In the Connections pane, click IWA under the site you created, and then double click Authentication. The status of the items should match the following:

    Anonymous – Enabled

    ASP .NET Impersonation – Enabled

    Forms Authentication – Disabled

    Windows Authentication – Enabled

15. Restart IIS.

Network Zones and IWA

Configure Agentless Desktop SSO

Configure a custom error page

Install and configure the Okta Active Directory (AD) agent

If you are experiencing issues with Desktop SSO/IWA not working, check the following:

• Ensure the host name of the server is resolvable from within the client network.
• IWA must be turned on in both the IIS authentication configuration and in the client.

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.

Tip: If you have installed the Okta IWA SSO agent and used the same Okta Service account that was used to install the Okta AD agent, then you must also change the Okta Service account password in the IIS Server Manager dashboard > Tools > Internet Information Services (IIS) Manager when you change the OktaService account password in AD.

The OktaIWA service is installed under the Application Pools menu. Under Advanced Settings you can change the Okta Service password to match the new password. Due to caching, the IWA service may not stop immediately. When the cache does reset, IWA will stop working if the OktaService password has not been updated here to match the password you reset in the Active Directory Users and Computers tool and the Services console on the server the agent is installed upon.

IWA not functioning after a server restart or Group Policy changes

The Okta IWA service account requires Logon as a Batch Job and Log on as a Service permissions. Ensure the service account has these permissions.