Migrate your Agentless Desktop Single Sign-on configuration
The steps in this topic apply 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 Agentless Desktop Single Sign-on - new implementations
You need to complete this procedure if:
- You implemented the Early AccessEarly Access (EA) features are opt-in features that you can try out in your org by asking Okta Support to enable them. Additionally, the Features page in the Okta Admin Console (Settings > Features) allows Super Admins to enable and disable some EA features themselves. version of Agentless DSSO prior to release 2019.09.0.
You are using Agentless DSSO with KerberosKerberos is a computer-network authentication protocol that works on the basis of tickets to allow nodes communicating over a non-secure network to prove their identity to one another in a secure manner. 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 AuthenticationAuthentication is distinct from authorization, which is the process of giving individuals access to system objects based on their identity. Authentication merely ensures that the individual is who he or she claims to be, but says nothing about the access rights of the individual. Authentication methods and protocols include direct auth, delegated auth, SAML, SWA, WS-Fed, and OpenID Connect.. 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:
The Agentless DSSO migration involves these steps:
- Add a new SPN in Active DirectoryActive Directory (AD) is a directory service that Microsoft developed for the Windows domain networks. It is included in most Windows Server operating systems as a set of processes and services. Initially, Active Directory was only in charge of centralized domain management.. To avoid a service disruption, the existing SPN must remain in place until you've successfully migrated to the new configuration.
- Configure browsers for SSO on Windows.
- Test the DSSO settings.
You have an Active Directory domainA domain is an attribute of an Okta organization. Okta uses a fully-qualified domain name, meaning it always includes the top-level domain (.com, .eu, etc.), but does not include the protocol (https). (or multiple domains) integrated with your Okta orgThe Okta container that represents a real-world organization..
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. AppAn abbreviation of application. Essentially, it is a web-based site used to perform any number of specific tasks, and requires authentication from end users by signing in. 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 adminAn abbreviation of administrator. This is the individual(s) who have access to the Okta Administrator Dashboard. They control the provisioning and deprovisioning of end users, the assigning of apps, the resetting of passwords, and the overall end user experience. Only administrators have the Administration button on the upper right side of the My Applications page. 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.
- Agentless DSSO will not work if a single user has memberships to more than 600 security groupsGroups allow you to organize your end users and the apps they can access. Assigning apps to large sets of end users is made easier with 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.
Set the SPN
Domain administrator privileges are required to set the SPN.
- 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.
- 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.
- Open your Okta Admin Console, navigate to Security > Delegated Authentication > Agentless DSSO > Edit
- Under the AD instances, click Edit.
- 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.
- Select Validate service account credential on save.
- Click Save.
This initiates the creation of a new DNS record for your org.
- 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.
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 clientEssentially, a client is anything that talks to the Okta service. Within the traditional client-server model, Okta is the server. The client might be an agent, an Okta mobile app, or a browser plugin. machines.
- Enable IWA on the browsers:
- In Internet Explorer, select Tools > Internet options.
- Click the Advanced tab, scroll down to Security, and select Enable Integrated Windows Authentication.
- 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.
- Configure the Local Intranet Zone to trust Okta:
- Open IE and click Tools> Internet options and click the Security tab.
- 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.
- Click Close and OK on the other configuration options.
- Create a GPO to apply the settings to all client machines using Agentless DSSO.
Test the DSSO settings
- Open the Okta Admin Console, navigate to Security > Delegated Authentication > Agentless DSSO.
- Scroll to Agentless Desktop SSO and confirm that On is selected for Desktop SSO mode.
- Log in to an active Okta Windows account that uses Agentless DSSO.
- Open an internet browser, enter https://<myorg>.okta.com/login/agentlessDssoMigrationReadiness in the address bar, and press Enter.
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.