Migrate your Agentless Desktop Single Sign-on configuration

Info

Note

The information in this topic applies only to orgs that implemented the Early Access version of this feature before August 30th, 2019. If you are implementing this feature for the first time after September 1, 2019, see Configure a new Agentless Desktop Single Sign-on implementation

You need to complete this procedure if:

  • You implemented the Early Access version of Agentless DSSO prior to release 2019.09.0.
  • You are using Agentless DSSO with Kerberos settings in Okta.

  • Desktop SSO mode is on and a message indicates that you need to perform the migration. To determine if this is applicable to you, open your Okta instance and then click Security > Delegated Authentication. Scroll to Agentless Desktop SSO and confirm that On is selected for Desktop SSO mode and the migration message appears. Your screen should appear similar to this:

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 information about 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 have an AD service account.
  • You have Okta Super Administrator permissions to update the DelAuth page. App administrators may also have sufficient permissions if granted access to manage AD.
  • Your AD service account includes:
    • A domain user account for the Okta tenant Kerberos service instead of a domain admin account. This is a security best practice.
    • The logon to restriction is turned on with a fictitious host name and the account marked as Account is sensitive and cannot be delegated. This is a security best practice.

Known issues

  • Agentless DSSO will not work if a single user has memberships to more than 600 security groups. If an end user with more than 600 security groups attempts the Agentless DSSO migration, a 400 response appears and they are 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. Okta recommends upgrading to Windows functional level 2008 or above to make sure you are using the most secure encryption algorithm.
  • Agentless DSSO does not work when delegated authentication is disabled and Don't create Okta password is selected. To learn more about delegated authentication, see Delegated authentication.

Set the SPN

Domain administrator privileges are required to set the SPN.

  1. Open a command prompt as an administrator in your AD environment and run this command to add an SPN:

    setspn -S HTTP/<myorg>.kerberos.<okta|oktapreview|okta-emea>.com <ServiceAccountName>

    HTTP/<myorg>.kerberos.okta.com is the SPN. <ServiceAccountName> is the value you used when configuring the Early Access version of Agentless DSSO and <oktaorg> is your Okta org (either oktapreview, okta-emea or okta). For example, setspn -S HTTP/atko.kerberos.oktapreview.com atkospnadmin.

    This command does not create a new AD user account and SPN. Instead, it adds a new SPN to the existing AD user account.
    SPNs are unique across a forest so you only need to do this once in each forest. If you have multiple forests, repeat step 1 for each forest. This command is applicable to all orgs, including those that are using a custom URL.

  2. Add https://<myorg>.kerberos.<oktaorg>.com to the Intranet Site list in your Internet Settings for all the devices that you want using Agentless DSSO.
  3. Open your Okta Admin Console, navigate to Security > Delegated Authentication > Agentless DSSO > Edit
    1. Under the AD instances, click Edit.
    2. If the service account username is in the old format (for example:  HTTP/<myorg>.<oktaorg>.com), change it to the UPN of the service account for which the SPN was set.
    3. Select Validate service account credential on save.
    4. Click Save.

    This initiates the creation of a new DNS record for your org.

  4. Use command line tools such as dig or nslookup to make sure your new Kerberos URL can be reached. For example:

    $ dig <yourOrg>.kerberos.<oktaorg>.com

    $ nslookup <yourOrg>.kerberos.<oktaorg>.com

    To determine if the command was successful, refer to your Linux or Windows command reference documentation for explanations of the output messages. If the Kerberos URL can be reached, complete the remaining procedures. If you do not see output indicating success, run the command again in five minutes or contact Okta support for assistance.

Configure browsers for SSO on Windows

Configuring changes on Internet Explorer (IE) will be enough as Chrome will recognize these settings.

Note: Firefox and Edge are not supported.

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

  • Enabling Integrated Windows Authentication (IWA) on the browsers.
  • Adding Okta as a trusted site to the Local Intranet Zone in Internet Explorer (IE). The Okta URLs must include https://<myorg>.kerberos.<oktaorg>.com.
  • Creating a Group Policy Object (GPO) to apply the setting on all your client machines.
  1. Enable IWA on the browsers:
    1. In Internet Explorer, select Tools > Internet options.
    2. Click the Advanced tab, scroll down to Security, and select Enable Integrated Windows Authentication.
    3. Click OK.

    Note: Make sure that IE 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. Open IE and click Tools> Internet options and click the Security tab.
    2. Click Local Intranet > Sites > Advanced and add the URL for your Okta org you configured in Add the SPN. For example: https://<myorg>.kerberos.<oktaorg>.com.
    3. Click Close and OK on the other configuration options.
  3. Create a GPO to apply the settings to all client machines using Agentless DSSO.

Test the DSSO settings

  1. Open the Okta Admin Console, navigate to Security > Delegated Authentication > Agentless DSSO.
  2. Scroll to Agentless Desktop SSO and confirm that On is selected for Desktop SSO mode.
  3. Log in to an active Okta Windows account that uses Agentless DSSO.
  4. Open an internet browser, enter https://<myorg>.okta.com/login/agentlessDssoMigrationReadiness in the address bar, and press Enter.
  5. If you cannot access the URL, contact Okta support.

    If the DSSO settings are correct and the org is ready, the user home page appears.

    If you created a custom URL, you are redirected to the URL location.

    If your org is not ready, the IWA flow is followed (if configured). If the IWA flow is not configured, the custom log in error page appears (if configured) or the default log in screen appears (https://<org>.okta.com/login/default).

    Your org will be migrated to the new functionality in a few days. No other changes are required and everything will continue to work.

    After you receive your confirmation from Okta, you will no longer need to make registry key changes for new users.

    If you need to make additional changes or adjustments to your settings, review the Agentless DSSO documentation.