Install and configure the Okta IWAWeb App for Desktop SSO Skip to main content
https://support.okta.com/help/oktaarticledetailpage?childcateg=&id=ka02a0000005udksaq&source=documentation&refurl=http%3a%2f%2fsupport.okta.com%2fhelp%2fdocumentation%2fknowledge_article%2finstall-and-configure-the-okta-iwaweb-app-for-desktop-sso-291155157
How satisfied are you with the Okta Help Center?
Thank you for your feedback!
How satisfied are you with the Okta Help Center?
1
2
3
4
5
Very Dissatisfied
Very satisfied
Enter content less than 200 characters.
Install and configure the Okta IWAWeb App for Desktop SSO
Published: Jan 31, 2018   -   Updated: Jun 22, 2018

 

 

okta-doc-source

Install and configure the Okta IWA Web App for Desktop SSO

Okta IWA is a lightweight Internet Information Services (IIS) web app that enables Desktop SSO on the Okta service. Desktop SSO 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 App 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 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.

IWA Authentication Flow — Diagram 1

IWA_Auth_Flow_Simple_4

IWA Authentication Flow — Diagram 2

IWA flow_large numbers_Sept2017

About IWA and JIT

As you configure IWA in your environment, be aware of the IWA flow works when importing users and how using Just in Time (JIT) authentication.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.

When a user tried to sign in using IWA:

  • 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: Because the user is not in Okta yet, the user profile must be pulled from AD based on the Okta user name format. Okta queries AD using the Okta user name format with the value to be search as the UPN. If the user name format is something other than the UPN, for example, the email address, the SamAccountName will fail to locate the user. Okta can only validate the user by the UPN. In this JIT case, 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 has not been imported into Okta and JIT is off: User sign in will fail.
Summary
  • Install and configure the Okta Integrated Windows Authentication (IWA) Web App
  • Configure your browser (procedures are provided for different browsers on Windows and Mac operating systems)
  • Test your browser to ensure that it works
  • Turn on Desktop SSO
System Requirements
  • 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 App.

    Note: Okta strongly recommends that you enable SSL.

  • Windows Server 2008 R2 and Windows Server 2012 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 App 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.0 (minimum) up to  .NET 4.6.x  and ASP .NET 4.5 (downloaded and installed automatically with the agent if no suitable version is found on the target machine at runtime). This is required for TLS 1.2.
  • 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 App. 
  • If your enterprise has more than one domain, see the topic Configuring UPN Transformation.
  • If your IWA Web App 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


Install the Okta IWA Web App

The Okta Administrative Account that will be used during IWA Agent installation must have Super Admin or Org Admin permissions.

To install the Okta IWA Web App:

  1. From your Administrator Dashboard, go to Security > Delegated Authentication > Active Directory
  2. In the Desktop Single Sign-On section, click the Download the Desktop SSO SSL installer 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 App 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 the 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.
  13. Proceed to Configuring Desktop SSO with IWA.  

Using multiple IWA Web apps

You can install multiple IWA Web Apps on separate servers for high availability purposes. Installing multiple web apps 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.

Updating the IWA SSO agent

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.

Configure Desktop SSO with IWA

To configure the Okta IWA Web App, perform the following procedures as applicable for your environment. 

Note: With Desktop SSO 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 into Okta. To avoid this, you can configure DSSO to send the user to a page that bypasses DSSO. See Customize the Sign-out page.

Recommended procedures

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 the URL of the server that hosts your Desktop SSO IWA Web App to your local intranet 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

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

    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.

Mandatory procedure

Activate the IWA Web App

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

  1. Return to Desktop Single Sign-On and select On.
  2. Click Save.

Procedures that may be applicable to your environment

Enable SSO for managed mobile and tablet devices

Important: Do not select this option if you have not deployed a Mobile Device Management (MDM) solution to enable IWA for your mobile and tablet devices.

If you have deployed a Mobile Device Management solution (such as Okta Mobility Management) and you want managed device users to be able to SSO into their Okta-hosted apps from their devices, perform these steps:

  1. From your Administrator Dashboard, go to Security > Delegated Authentication > Active Directory, and scroll down to Desktop Single Sign-On.
  2. Click Edit.
  3. Select Redirect mobile and tablet devices.
  4. Click Save.
Customize the Sign-out page

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.

Configure fail over settings

Fail over settings determine what users experience if your primary IWA application goes offline. You can check your System Log to see when a fail over occurred and the backup IWA Web App 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.
    • Manual failover (default)

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

    • Automatic failover

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

    • Global redirect 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.
Configure SSL

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

Note: We strongly recommend against utilizing a self-signed certificate, as this will result in client-side issues when the certificate is not trusted. The best option is to generate a certificate from a Certificate Authority (CA) server on your domain, as detailed in steps 1-5 below. If you do not have a CA server, we recommend generating a certificate from Let's Encrypt or a third-party such as GoDaddy. Configuring SSL helps prevent untrusted actors from accessing your data.

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

If using a Certificate Authority on your domain:

  1. On the same server that hosts your Okta IWA Web App, open Internet Information Services (IIS) Manager and select the server under Connections.

    Desktop_SSO_7

  2. In the center pane of the IIS Manager, double-click the Server Certificates icon.
  3. Under Actions (on the right side), click Create Domain Certificate.

    Desktop_SSO_8

  4. Enter information in the Distinguished Name Properties dialog box, and then click Next.
    Common Name: The name entered here specifies the server the certificate is issued to, and therefore must consider what the planned URL will be.
    For example, if the server's name is IWAServer and the server's Fully Qualified Domain Name (FQDN) will be used for IWA (for example, https://IWAServer.company.com/iwa), the Common Name entered should be IWAServer.company.com.
    If the host name is going to be used as the URL (https://IWAServer/IWA), IWAServer would be entered instead.
    If you plan to export and use the same certificate on multiple DSSO primary and backup servers in the same domain, a wild card can be entered in the Common Name field (for example: *.company.com), but this would then require using the FQDN in later steps.
  5. In the Online Certification Authority dialog box, do the following:
    1. Click Select, select a certificate authority, and then click OK
    2. Enter a name in the Friendly name field, and then click Finish. The Friendly Name is the certificate's name that appears when displaying or choosing certificates, and does not need to match the Common Name.
  6. Under Connections, expand Sites, and then select Default Web Site.

    Desktop_SSO_9

  7. Under Actions, click Bindings.

    Desktop_SSO_10

  8. In the Site Bindings dialog box, click Add.
  9. In the Add Site Binding dialog box, do the following:
    1. Select https in the Type drop-down menu.
    2. In the SSL certificate menu, select the friendly name that you specified previously.
    3. Click OK.

      Desktop_SSO_11

  10. Close the Site Bindings dialog box.
  11. Under Connections, expand Sites > Default Web Site, and then select IWA.
  12. In the center pane of the IIS Manager, double-click the SSL Settings icon.
  13. On the SSL Settings page, select Require SSL. You can leave the Client certificates option as Ignore.
  14. Under Actions, click Apply.
  15. Log in to your Okta org and go to Security > Delegated Authentication > Active Directory.
  16. Scroll down to Desktop Single Sign On and click Edit.
  17. In the Integrated Web Authentication (IWA) Web Applications section, click the down arrow to expand the section.

    Desktop_SSO_12_500x28

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

    Desktop_SSO_13_500x237

  19. Click Save.
  20. Test the configuration as described in Testing Your IWA Web App.
Enabling TLS 1.2 on Windows Server 2008 R2

Your IWA Web App 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 App 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 App 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 Apps 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 App, 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)
  3. Restart the server.

More information is available online here and here.

Configuring a custom error page in case of failed IWA sign in

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.

Configure UPN transformation (in multiple-domain environments)

Note: This applies only to enterprises with more than one domain, and requires IWA Web App 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 Apps 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 App uses to check UPNs. If a UPN matches a UPN transformation rule, the IWA Web App uses the expression specified by the replace attribute to compute a transformed UPN. For more information, see:

The IWA Web App 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 App sends the original UPN to Okta.

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

Change the IWA detection timeout period

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 App, 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.
Skip IWA authentication for specified clients

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.

By default, the IWA Web App 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 App 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 App.
  3. Open Internet Information Services (IIS) Manager on the same server that hosts your IWA Web App.
  4. Under Connections (on the left side), expand Sites > Default Web Site and select IWA.

    Desktop_SSO_14

  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.
If your IWA Web App is installed on a virtual machine with other web apps.
  1. Install and configure the IWA Web App.
  2. On the same server that hosts your Okta IWA Web App, 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\wwroot.
  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 on the site you created (Tip: click the globe icon).
  2. IWA_IIS_Manager

  3. In the center pane, double click Authentication. Check that only Anonymous Authentication is enabled.
  4. 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.
Test your IWA Web App

After you download and install your IWA Web App, 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 Integrated Windows Authentication (IWA) Web Applications section, click the down arrow to expand the section.

    Desktop_SSO_4

  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.

    Desktop_SSO_5

  6. Press Enter on your keyboard.

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

    Desktop_SSO_6_500x143

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

    Desktop_SSO_6b_500x70

    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. If you have deployed a Mobile Device Management (MDM) solution to enable IWA for your mobile and tablet devices and you want your users to be able to authenticate their mobile devices via IWA, select Redirect mobile and tablet devices.

    Important: Do not select this option if you have not deployed a Mobile Device Management (MDM) solution to enable IWA for your mobile and tablet devices.

  5. Click Save.
View the status of your IWA Web apps
  1. Go to Security > Delegated Authentication > Active Directory.
  2. In the Integrated Web Authentication (IWA) Web Applications section, select the desired IWA Web App.

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

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

Troubleshooting

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.

Top