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

Info

Note

Okta recommends using Agentless Desktop SSO to implement Desktop Single Sign-on (DSSO). Agentless DSSO requires less maintenance and has a simplified configuration process.

To determine which type of Desktop SSO you have implemented, see Identify your Desktop Single Sign-on type.

Okta IWA is a lightweight Internet Information Services (IIS) web agent 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. 

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.

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 (IDP) routing rules must be manually reactivated.

Prerequisites

  • You must have installed and configured the Okta AD agent and Delegated Authentication 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\Client] "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 domain, 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 Kerberos 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 uses the UPN to validate users. If the Okta user name format is not a UPN and another format such as an email address or SamAccountName is used, this setting is ignored and the UPN is used for validation.
  • 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 admin 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 admin 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.

    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.

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

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.

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.

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

    User-added image

  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.

    User-added image

  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:

    2013-02-13_11-47-45.jpg

    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

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

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

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

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

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

    User-added image

  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"

  1. Under Actions (on the right side), click Apply.
  2. Restart Internet Information Services (IIS) Manager.
  1. Install and configure the IWA Web agent as described in Install the Okta IWA Web agent.
  2. On the same server that hosts your Okta IWA Web agent, open the Internet Information Services (IIS) Manager.
  3. Right-click 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.

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

  2. In the center pane, double click Authentication. Check that only Anonymous Authentication is enabled.
  3. 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

  1. Restart IIS.

Related topics

Network Zones and IWA

Configure Agentless Desktop SSO

Configure a custom error page

Install and configure the Okta Active Directory agent