Configure Agentless Desktop SSO with Registry Keys (deprecated)

Info

Note

This topic applies to orgs that implemented the Early Access version of agentless Desktop Single Sign-on (DSSO) prior to the 2019.09.0 release (August 30th, 2019 or earlier). If you are implementing this feature for the first time after September 1, 2019 (after 2019.09.0), see Configure a new Agentless Desktop Single Sign-on implementation.

With Desktop Single Sign-on (DSSO), your users are automatically authenticated by Okta when they sign in to your Windows network. Following authentication, users can access applications through Okta without entering additional usernames or passwords. DSSO improves the user experience because users only need to sign in a single time and don’t need separate credentials for each application they access through Okta.

Traditionally, enabling Desktop SSO required deploying IWA agents. Agentless desktop SSO eliminates the need to deploy IWA agents across Active Directory domains to enable DSSO. This reduces your maintenance overhead and provides High Availability as Okta handles the Kerberos validation. ClosedDiagram

Prerequisites

  • You have an Active Directory domain (or multiple domains) integrated with your Okta org.

  • You have permissions in Active Directory to configure a Service Principal Name (SPN). For more info on permissions, see Delegating Authority to Modify SPNs at the following URL: https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2012-R2-and-2012/cc731241(v=ws.11).

  • You will need to create a service account, as described below. For this service account:
    • A domain user account is recommended, for the Okta tenant Kerberos service, instead of a domain admin account as a security best practice.
    • To further lock down the account, the logon to restriction can be turned on with a fictitious host name, and the account can be marked as Account is sensitive and cannot be delegated. This is also for security reasons.
  • Custom URL

    If you are using a custom URL:

    • Agents – Use the actual domain (example.okta.com) and not the custom domain (example.customname.com).
    • IWA SSO – Modify the web.config file to include the custom url.

      <oktaSSOConfigGroup>

      <oktaSSOConfig orgOktaAuthenticationURL="https://example.customname.com/login/sso_iwa_auth"

      orgBackupOktaAuthenticationURL="https://example.customname.com/login/default"

      oktaSSOWebAppVersion="1.11.5.0">

    • Agentless DSSO – Make sure that all sign-in flows and browser bookmarks use the correct URL.
  • Using AES128 or AES256 encryption — If you want to use AES128/256 with Agentless Desktop SSO or MS App silent activation, you must enable AES for both the AD domain as well as the service account for Okta DSSO. If it isn't enabled for the AD domain you will see a Kerberos error KDC_ERR_ETYPE_NOTSUPP in the Kerberos events.

    For details on how to enable each of these, refer to Windows Configurations for Kerberos Supported Encryption Type.

Known issues

  • Agentless DSSO will not work if a single user has memberships to more than 600 security groups — If an end user tries to go through the Agentless DSSO flow and has more than 600 security groups, they will see a 400 response and be redirected to the regular sign in page.
  • The following browsers are not supported:
    • Firefox on Windows
    • Chrome on macOS.
    • MS Edge
  • If you are using Windows functional level 2008 or below, be aware that it uses a less secure encryption RC4. We recommend that you upgrade to at least Windows functional level 2008 or above to use the most secure encryption algorithm.

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.

Create a service account and configure a Service Principal Name

In order for Okta to negotiate Kerberos authentication for Agentless DSSO, you need to create a new service account and set a Service Principal Name (SPN) for that service account.

  1. Sign in to a server from which you can access Active Directory Users and Computers.
  2. Create a new account with the following properties. The service account itself does not need admin permissions, but you will need specific permissions to set an SPN as mentioned in Delegating Authority to Modify SPNs

    User logon name: <username>
    User logon name (pre-Windows 2000) :  <username>
    where <username> is any username of your choice.

  3. Select a password and set to Password never expires.

  4. In a command window configure an SPN for the service account using the following syntax:

    Setspn -S HTTP/<myorg>.okta.com <username>

    Where HTTP/<myorg>.okta.com is the SPN and <username> are the values specified in step 2. For example,
    Setspn -S HTTP/atko.okta.com atkospnadmin

Configure browsers for SSO on Windows

Agentless DSSO is supported on Windows using Chrome, Chromium versions of Microsoft Edge, and Internet Explorer. Firefox and previous versions of Microsoft Edge are not supported.

There are three main steps involved in configuring the browsers on Windows:

  • Enabling IWA on the browsers.
  • Adding Okta as a trusted site to the Local Intranet Zone in Internet Explorer (IE).
  • Creating a GPO to apply these setting across all our client machines.
  1. Enable IWA on the browsers:
    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.

  2. Configure the Local Intranet Zone to trust Okta:
    1. In IE, open Options > Security.
    2. Click Local Intranet > Sites > Advanced and add the URL for your Okta org as configured in earlier steps. For example, https://<myorg>.okta.com.
    3. Click Close and OK on the other configuration options.
  3. Create a GPO to roll this out to all client machines that will use Agentless DSSO.

Configure browsers for SSO on Mac

Agentless DSSO is supported on Macs using Safari and Firefox. Chrome is not supported.

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

Deploy registry keys to client machines

Now that you’ve configured your SPN, and browsers, you will create a Group Policy Object to deploy registry keys.

Okta uses CNAME alias' to resolve to the Okta org. So when you make a request to <myorg>.okta.com, that subdomain is an alias to various load balancers. This is a modern Cloud infrastructure pattern to eliminate maintenance overhead. To support this architecture registry keys need to be deployed to tell any apps that rely on Kerberos to use CNAME and not ANAME.

You will need to add a registry key entry for each app that depends on Kerberos authentication for Agentless DSSO. This includes the Chrome and Internet Explorer browsers and any other thick clients that you may have. You can decide which apps to include based on whether you want Agentless DSSO functionality enabled for them. For example, if you have four native apps: MSWord, Excel, PowerPoint, and GoToMeeting and you only want Agentless DSSO on the GoToMeeting app then you'd need to add a registry key for the GoToMeeting app.

Important: Wildcards are NOT recommended as they could have unexpected consequences on other applications that rely on DNS.

By deploying these registry keys, the behavior of all web apps that depend on Kerberos for authentication will change to resolve to CNAME rather than ANAME

You need to check the SPN set for these applications and see whether that SPN is an ANAME or a CNAME and decide:

  • If the SPN is an A name, change the SPN to a CNAME.
  • If the SPN is a CNAME, leave it as is.

Okta recommends that you test the Agentless DSSO changes in a limited scope before rolling out widespread changes to your org. This includes deploying the registry key changes on a small but representative selection of machines in your domain. For details, see Test Agentless DSSO

Deploy registry keys

This section describes the deploying the registry keys on individual machines for test purposes and through Group Policy Objects when you are ready for production.

Deploy registry keys on a single machine

Before rolling out the registry key changes to all machines, you can test the implementation by applying the changes to individual machines.

To apply this on a single machine, create a .reg file on the machine with the following content inside of it:

Windows Registry Editor Version 5.00
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Internet
Explorer\MAIN\FeatureControl\FEATURE_USE_CNAME_FOR_SPN_KB911149]
"iexplore.exe"=dword:00000001
[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Internet
Explorer\MAIN\FeatureControl\FEATURE_USE_CNAME_FOR_SPN_KB911149]
"iexplore.exe"=dword:00000001
[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Google\Chrome]
"DisableAuthNegotiateCnameLookup"=dword:00000001

Deploy registry keys through Group Policy

To deploy the registry key changes across your org, you will use Group Policies.

In order to create a group policy to apply broadly, do the following as a domain administrator from your domain controller:

  1. Launch Active Directory Users and Computers.
  2. Right click in the navigation structure and select New > Organizational Unit (OU).
  3. Name the OU. This will be the computers OU used for this change
  4. From a domain controller run the command gpedit.msc to open the Group Policy Editor.
  5. In the Group Policy Management console, right-click Group Policy Objects.
  6. Select New, to create a new group policy object (GPO).
  7. Name the GPO and leave Source Starter GPO set to (none).
  8. Right-click the new GPO and select Edit
  9. Navigate to Computer Configuration > Preferences> Windows Settings > Registry
  10. Right-click Registry and select New Item, enter the following items values. Repeat the process for all of the below registry entries.
    • For Internet Explorer:

      Action

      Create
      HiveHKEY_LOCAL_MACHINE
      KeypathSOFTWARE\Microsoft\Internet Explorer\MAIN\FeatureControl\FEATURE_USE_CNAME_FOR_SPN_KB911149
      Value Nameiexplore.exe
      Value TypeREG_DWORD
      Value Data1
      ActionCreate
      HiveHKEY_LOCAL_MACHINE
      KeypathSOFTWARE\Wow6432Node\Microsoft\Internet Explorer\MAIN\FeatureControl\FEATURE_USE_CNAME_FOR_SPN_KB911149
      Value Nameiexplore.exe
      Value TypeREG_DWORD
      Value Data1
    • For Chrome:
      ActionCreate
      HiveHKEY_LOCAL_MACHINE
      KeypathSOFTWARE\Policies\Google\Chrome
      Value NameDisableAuthNegotiateCnameLookup
      Value TypeREG_DWORD
      Value Data1
  11. Once all entries have been created, locate the OU created in step 3.
  12. Right-click the OU and select Link an Existing GPO
  13. Select the appropriate GPO.

Enable Agentless DSSO

You can enable Agentless Desktop SSO for testing or for production.

  • Test — allows you to test by signing in using the direct Agentless DSSO endpoint URL:
    https://<myorg>.okta.com/login/agentlessDsso
  • On — allows end users to sign in from the default sign in endpoint, routing through the Agentless DSSO sign in endpoint. The end user doesn't need to explicitly type in the DSSO URL.
  1. In the Okta Admin dashboard, navigate to Security > Delegated Authentication.
  2. Scroll to Agentless Desktop SSO.
  3. Click Edit and select a Desktop SSO mode:
    • Off
    • Test — For testing in your Preview environment.
    • On — For enabling SSO in Production.
  4. For Allowed network zones, add the zones that are associated with the machines from which you will be implementing Agentless SSO.

    Note: If IdP Discovery is turned on, the network zone options will not be available. When IdP Discovery and Agentless DSSO are both on, Agentless DSSO network zones are controlled through the IdP Routing Rules. You will update the default IdP routing rule in Create Identity Provider routing rule .

  5. In AD Instances, select the Active Directory instance on which you configured the SPN.
  6. Configure Agentless Desktop SSO for this Active Directory domain with the following information and then Save.
    • Desktop SSO — Select Enable or Disabled depending on whether you are enabling for production or testing.

    • Service account username — This is the AD sign-on name that you created in Create a service account and configure a Service Principal Name above, without any domain suffix or Netbios name prefix. It can be the sAMAccountName or the username part of the UPN. These two may be the same string unless the Org admin chose to use different values.

    • Service account password — Password for the account that you created in AD.

    • Validate service account credential on Save — (Optional) Validates the service account credentials as an optional step in saving the Kerberos realm configuration. If it's checked, the service account will be authenticated by the AD agent. If the credentials cannot be validated, an error message appears. If you don't want to validate or can't because the AD agent isn't responsive, the box can be unchecked to skip the validation.

Once a domain has been configured and enabled users will be able to sign in with Agentless DSSO.

Create Identity Provider routing rule

To complete this step you must already have an Identity Provider configuration.

After you turn on Desktop SSO, a default DSSO routing rule is created. You must configure the network information for this rule.

  1. On the Okta Admin Console, click Security > Identity Providers > Routing Rules.
  2. Select the Default Route to AgentlessDSSO rule. By default the network information is not configured and the rule is Inactive.
  3. Indicate your routing specifications.
  • User's IP is: Select Anywhere to apply the rule to any user location, select In zone to apply the rule to a specific zone, or select Not in zone to apply the rule to users outside of a specific zone. For information on zones, see IP Zones.
  • User's device platform is: Select Any device to apply the rule to users with any device type, or to apply the rule to users with specific devices, select Any of these devices and select specific devices.
  • User is accessing: Select Any application to apply the rule when a user accesses any application, or to apply the rule when a user accesses specific applications, select Any of the following applications and enter an application name.
  • User matches: Select the criteria to apply the rule to users with specific attributes such as log in, first name, or last name.
  • Use this identity provider Select the identity provider to use when all rule criteria are met.
  1. Activate the rule.

Validate Agentless DSSO

After configuring Agentless DSSO, you can verify that everything is correctly configured by doing the following:

  1. Sign in to a domain-joined, on-network device that is joined to the Active Directory environment on which you have enabled Agentless Desktop SSO. Ensure that you are logged in as a user that is already active in Okta.
  2. If you haven’t already, add your Okta environment to your Local Intranet settings.
    1. In a browser, open Options > Security.
    2. Click Local Intranet > Sites > Advanced and add the URL for your Okta org as configured in earlier steps. For example, https://<myorg>.okta.com.
    3. Click Close and OK on the other configuration options.
  3. On a Windows machine, sign into your Okta org. If Agentless DSSO is configured correctly, you will be automatically redirected to your end user apps dashboard without entering any credentials.
  4. Verify in the system log that the user authenticated through Agentless Desktop SSO. In your Okta org, you will see an entry for Authenticate user via IWA with no entries referring to an on-prem IWA server.

Optional procedures

Test Agentless DSSO

Okta recommends that you test the Agentless DSSO changes in a limited scope before implementing widespread changes to your org.

  1. Create a service account and configure a Service Principal Name
  2. Configure browsers for SSO on Windows or Configure browsers for SSO on Mac.
  3. Enable Agentless DSSO in test mode
  4. Optional. Enable Kerberos event logging. For more information, see https://support.microsoft.com/en-us/help/262177/how-to-enable-kerberos-event-logging.
  5. Validate Agentless DSSO by signing in using the direct Agentless DSSO endpoint URL:
    https://<myorg>.okta.com/login/agentlessDsso

If Agentless DSSO is configured correctly, you will be able to sign in without being prompted for credentials. If you experience problems signing in, ensure you have completed all the steps listed above. You can check the Configure Agentless Desktop SSO with Registry Keys (deprecated) section for additional help.

Configure DSSO fail over

You may want to have a back up plan in the event that Agentless DSSO fails. There are two fail over options:

  • Okta will automatically fail over to the default sign-in page.
  • You can use on-prem IWA DSSO as a backup.

Choosing to fail over to on-prem IWA DSSO, requires you to install and configure the on-prem IWA DSSO. If on-prem IWA DSSO is configured and enabled, it will automatically take over if Agentless DSSO stops working. For details, see Install and configure the Okta IWA Web agent for Desktop Single Sign-on.

Revert Registry Key changes

If you have trouble after enabling the registry changes you can roll back the registry key changes you've made.

To roll back the registry settings using the GPO, edit the previously added registry keys changing the action item from Create to Delete.