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. 

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.

    NoteOkta 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 OktaOkta 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 OktaOkta 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 enabledOkta 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.

    Google Chrome (Windows)

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

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

    --auth-server-whitelist=

    For example:

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

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

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

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

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

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

Configure browsers for SSO on Mac

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

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

Google Chrome (Mac)

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

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

    kinit username@example.com

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

  3. Configure the Chrome whitelist:

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

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

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

Activate the IWA Web agent

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

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

Configure SSL

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

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

Acquire an SSL certificate

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

Certificate Signing Request (CSR) Generation Instructions

How to install an SSL Certificate in Microsoft IIS 7.0

Certificate creation notes and considerations

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

Enable SSL

Once the certificate has been installed:

  1. Log in to your Okta 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


Related topics

Network Zones and IWA

Configure Agentless Desktop SSO

Configure a custom error page

Install and configure the Okta Active Directory agent