Enforce Okta Device Trust for managed Windows computers

Okta Device Trust for Windows allows you to prevent unmanaged Windows computers from accessing corporate SAML and WS-Fed cloud apps. It works with any browser or native app that can access the certificate store when performing the federated authentication flow to Okta. This includes Edge, Internet Explorer, Chrome, and Microsoft Office clients that support Modern Authentication.

The image illustrates how Okta Device Trust is enforced for managed Windows devices.

Okta Device Trust for Windows provides these key benefits:

  • Ensures that only end users on domain-joined Windows computers can seamlessly SSO into SAML and WS-Fed cloud apps
  • Protects enterprise data even when there is no defined network boundary
  • Provides a frictionless end user experience by utilizing the Okta Certificate Authority
  • Support for Device Trust enrollment in multi-forest environments.

Prerequisites

Client workstations

  • Active Directory domain-joined Windows computer(s) running Microsoft Windows 7, Windows 8.1, or Windows 10.
  • .NET Framework version 4.5.2 and later. The Device Registration Task checks whether a supported version of .NET Framework is present, and if not, installs a supported version automatically. See Known Issues.

Active Directory and IWA servers

See Manage your Active Directory integration and IWA agent documentation.

IWA agent

Device Trust-capable version of the Okta IWA web agent. For installation details, see IWA documentation. Note: Device Trust enrollment in multi-forest environments requires IWA web app version 1.12.2+. An IWA web app running in one forest can detect and assess the trust posture of Windows desktop devices located in another trusted forest and then allow these devices to enroll in Device Trust for Windows.

Supported browsers

  • Microsoft Internet Explorer versions 10 and 11
  • Microsoft Edge (current and previous release)
  • Google Chrome (current and previous release)

Before you begin

  • Web view must have access to the device certificate store: Okta Device Trust for Windows computers works with any SAML/WS-Fed-enabled app that supports authentication through a webview. The web view in which authentication is performed must have access to the certificate store on the device. This includes Microsoft Office clients that support Modern Authentication, among others. See the Microsoft article Updated Office 365 modern authentication.
  • Device + end user authentication requires a network connection: For the IWA web app to authenticate end users and devices, end users must be logged-in to your company's network at the time the Device Registration Task runs. See IWA web app.
  • Device Trust enrollment is not supported when Okta is in read-only mode: Devices cannot be enrolled in Device Trust if the cell in which your Okta org resides is in read-only mode.
  • Support for proxy server environments: To ensure that this device trust solution works in environments that implement a proxy server, you must install Device Registration Task version 1.2.1 or higher through a command line and append the appropriate HttpProxy parameter to the installation command. See Install the Registration Task.
  • Make sure that certificates are installed on targeted computers: Before you configure the Trusted option for apps in App Sign On Policy rules, you must make sure that certificates are installed in the certificate store on the domain-joined computers you have targeted for this Device Trust solution. If certificates are not installed and the Trusted setting is enabled, users are denied access to the app and are redirected to a security message advising them to contact their administrator. (You can configure the message to include a Learn more link to more information. See Enable the global Device Trust setting for your org). To verify certificate enrollment, Okta recommends that you use your management tool to parse the Windows Event Viewer, or use a command line to query the user certificate store directly. Look for Okta MTLS certificate.
  • Take care when disabling the Windows Device Trust setting: Don't disable the Windows Device Trust setting on the Security > Device Trust page if you have also configured an app sign-on policy that allows trusted Windows devices. Otherwise, your Device Trust configuration will be in an inconsistent state and users with untrusted devices won't be shown the security message advising them to contact their administrator, nor the Learn more link to more information (if configured; see Enable the global Device Trust setting for your org).
  • Before asking Okta Support to disable Okta Device Trust for Windows: First make sure to change the Device Trust setting in the app sign-on policy rules to Any (Applications > app > Sign On). If you do not make this change and then later have Okta Support re-enable Device Trust capability for your org, the Device Trust setting in app sign-on policy rules will take effect immediately, which you may not have expected.

  • To verify installation of the Registration Task, use an appropriate detection setting: After installing the Device Registration Task on your managed Windows computers, SCCM runs a script to verify that installation was successful. Make sure to specify either File System or Registry in your Detection Rule. Don't use the Windows Installer setting type to detect the installation, as SCCM cannot detect the Device Registration Task using that setting.

  • Ensure clients can complete the MTLS handshake: If your org implements proxy servers/proxy clients or endpoint protection software, make sure to configure them in a way that doesn't block the Mutual TLS certificate exchange (handshake) that occurs during this Device Trust flow. See Troubleshooting.
  • Shared-terminal scenarios not supported: Okta Device Trust for Windows doesn't support shared-terminal scenarios in which multiple end users log in to the same domain-joined workstation.
  • Apps secured by Device Trust are shown as locked on the Okta End-User Dashboard. A lock icon is shown beside apps secured by Device Trust under these conditions:

    •  The end users accessed the dashboard in a desktop or mobile browser (not in Okta Mobile).
    • Device Trust is enabled for the org.
    • The device is not trusted.
    • The end user tried to access any Device Trust-secured app from their dashboard.

Procedures

These procedures have three main steps:

Step 1. Enable the global Device Trust setting for your org

Do not disable the Windows Device Trust setting on the Security > Device Trust page if you have also configured an app sign-on policy that allows trusted Windows devices. Otherwise, your Device Trust configuration will be in an inconsistent state and users with untrusted devices won't be shown the security message advising them to contact their administrator, nor the Learn more link to more information (if configured; see Enable the global Device Trust setting for your org).

  1. In the Admin Console, go to Security > Device Trust.
  2. In the Windows Device Trust section, click Edit.
  3. Select Enable Windows Device Trust.
  4. Optional. In the Learn more link field, you can enter an externally-accessible redirect URL where end users with untrusted devices can find more information. The security message shown to these end users will include a Learn more link that redirects to your specified URL.

    If you choose not to specify a URL in this optional field, these end users are shown the same message but without the Learn more link.

  5. Click Save.
  6. Proceed to Step 2.

Step 2. Enroll the Device Trust certificate on domain-joined Windows computers

Perform the four sub-procedures in this section to ensure that the Device Trust certificate is installed successfully on domain-joined Windows computers.

2.1 Install a Device Trust-supported version of the Okta IWA web app in your AD domain

Okta Device Trust for Windows uses the IWA web app to confirm the security posture of Windows computers and users by validating that both are joined to your Active Directory domain. (Enrollment is also supported in multi-forest environments. See Prerequisites.) Okta then issues a certificate to the Windows computer enabling Device Trust flows to Okta-federated apps. Private keys associated with the Okta certificate never leave the Windows computer. Certificates are renewed automatically once a year, approximately 30 days before they expire.

The role of the IWA web app is limited to the certificate enrollment and renewal process. Once the certificate is installed, the Device Registration Task no longer needs to communicate with the IWA web app in order for end users to access apps. Desktop SSO doesn't need to be On in Security > Delegated Authentication for Okta Device Trust for Windows desktop to function.

  1. To download the IWA web app, configure a link as follows:
  2. https://<org>.<okta/oktapreview>.com/static/agents/iwa/OktaSsoIwa-x.x.x.exe

    Where:

    • <org> is the name of your org
    • <okta/oktapreview> denotes either your Okta Production or Preview environment.
    • oktaSsoIwa-x.x.x.exe is the version of the IWA web app that supports Device Trust for Windows. For the current Device Trust-capable version, see SSO IWA Web App Version History.

    For example, a link for downloading version 1.11.0 to the org example.oktapreview.com would look like this:

    https://example.oktapreview.com/static/agents/iwa/OktaSsoIwa-1.11.0.exe

  3. Install the Okta IWA web app as detailed in Install and Configure the Okta IWA Web App for Desktop SSO.
  4. To make sure that the IWA web agent is operational, test it as described in the guide.
  5. If you use HTTPS for IWA, you must modify the IWA web.config file as follows:
    1. On the server running the IWA web agent, access the file C:\inetpub\wwwroot\IWA\web.config
    2. Locate the section <system.serviceModel> and replace it with the following:
      Copy
      <system.serviceModel>
      <bindings>
      <webHttpBinding>
      <binding name = "SecureBindingForDeviceTrust">
      <security mode="Transport">
      <transport clientCredentialType = "Windows" proxyCredentialType="Windows"/>
      </security>
      </binding>
      <binding name = "HttpBindingForDeviceTrust">
      <security mode="TransportCredentialOnly">
      <transport clientCredentialType = "Windows" proxyCredentialType="Windows"/>
      </security>
      </binding>
      </webHttpBinding>
      </bindings>
      <services>
      <service name="OktaSSO.DeviceTrust" behaviorConfiguration="OktaSSO.DeviceTrustBehavior">
      <endpoint binding="webHttpBinding" bindingConfiguration="SecureBindingForDeviceTrust" contract="OktaSSO.IDeviceTrust" behaviorConfiguration="webHttp"/>
      </service>
      </services>
      <behaviors>
      <endpointBehaviors>
      <behavior name="webHttp">
      <webHttp/>
      </behavior>
      </endpointBehaviors>
      <serviceBehaviors>
      <behavior name="OktaSSO.DeviceTrustBehavior">
      <!-- To avoid disclosing metadata information, set the value below to false before deployment -->
      <serviceMetadata httpGetEnabled="false"/>
      <!-- To receive exception details in faults for debugging purposes, set the value below to true.  Set to false before deployment to avoid disclosing exception information -->
      <serviceDebug includeExceptionDetailInFaults="false"/>
      <serviceCredentials>
      <windowsAuthentication allowAnonymousLogons="False" includeWindowsGroups="True"/>
      </serviceCredentials>
      </behavior>
      </serviceBehaviors>
      </behaviors>
      </system.serviceModel>

      Here's a detailed look at the values that configure HTTP or HTTPS binding:

      HTTPS binding configured:

      Copy
      <services>
      <service name="OktaSSO.DeviceTrust" behaviorConfiguration="OktaSSO.DeviceTrustBehavior">
      <endpoint binding="webHttpBinding" bindingConfiguration="SecureBindingForDeviceTrust" contract="OktaSSO.IDeviceTrust" behaviorConfiguration="webHttp"/>
      </service>
      </service

      HTTP binding configured:

      Copy
      <services>
      <service name="OktaSSO.DeviceTrust" behaviorConfiguration="OktaSSO.DeviceTrustBehavior">
      <endpoint binding="webHttpBinding" bindingConfiguration="HttpBindingForDeviceTrust" contract="OktaSSO.IDeviceTrust" behaviorConfiguration="webHttp"/>
      <endpoint address="mex" binding="mexHttpBinding" contract="IMetadataExchange" />
      </service>
      </services>
    3. Save and close the web.config file.
    4. From your Windows command prompt, restart Internet Information Services (IIS) by issuing the following commands:

      iisreset /stop

      iisreset /start

    5. Before proceeding, retest the IWA web app as described in Install and Configure the IWA Web App for Desktop SSO.
    6. If you haven't already, install the Device Registration Task as described in Obtain and install the Device Registration Task.

2.2 Obtain and install the Device Registration Task

Important to know before you begin

Trusted Platform Module (TPM)

To leverage the security benefits of TPM, see Enhance Windows Device Trust security with Trusted Platform Module (TPM).

Schedule the Registration Task to run when end users are on the corporate network

Once installed on domain-joined computers, the Registration Task runs:

  • Immediately after it is installed
  • Whenever the user logs on to the computer
  • Once every 24 hours, starting with the time that the Registration Task first ran.

It is important that you configure your management tool to schedule the Registration Task to run when end users are on the corporate network. When the Registration Task runs, it triggers the certificate enrollment flow and creates a Scheduled Task that will run every 24 hours and whenever the user logs on to the computer. This retry behavior helps both certificate enrollment and renewal scenarios.

Automatic certificate renewal can only occur when end users are on the corporate network

Certificates are valid for one year and are renewed automatically sometime within 30 days before expiration. In order for automatic renewal to succeed, end users must be logged on to the domain-joined computer and connected to your corporate network.

Manually force certificate renewal

You can manually force certificate renewal to try to fix the following problems (requires Device Registration Task 1.3.1 or later):

  • An end user's certificate was incorrectly or accidentally revoked by the admin through the Admin Console (see Revoke).
  • The certificate was corrupted on the client due to accidental deletion, file corruption, or loss of the private key.

See Force certificate renewal in some circumstances.

Automatic certificate selection

By default, the Registration Task configures registry keys on domain-joined Windows computers to allow supported Chrome, Edge, and IE browsers to automatically select the Device Trust certificate that will be presented to Okta. If appropriate for your environment, you can disable this behavior by adding the flag SkipBrowserSetup=true to the installation command.

See Obtain the registration task. For example, this would be necessary if you want to configure automatic certificate selection using a Group Policy Object (GPO) tool.

If you opt not to configure automatic certificate selection — either through the Registration Task or a GPO — end users are prompted to select the certificate when accessing the app. In that case, to make the selection easier for end users, only the Okta Device Trust certificate will be shown to them.

Proxy server environment

If your organization routes internet traffic through a proxy server, note the following:

  • You must install Device Registration Task version 1.2.1 or higher through a command line and append the appropriate HttpProxy parameter to the installation command.

    See Install the Registration Task.

  • If your org implements proxy servers/proxy clients or endpoint protection software, make sure to configure them in a way that doesn't block the Mutual TLS certificate exchange (handshake) that occurs during this Device Trust flow.

    See Troubleshooting.

Certificate revocation

You may need to revoke an end user's Device Trust certificate(s) from the Okta Certificate Authority. This is recommended if the computer is lost or stolen. To re-secure an end user's computer with Device Trust after revoking their certificate(s), you need to remove the Device Trust certificate from their computer before you enroll a new certificate. Certificate revocation doesn't remove existing certificates from managed Windows computers.

See Revoke and remove Device Trust certificates.

Use an appropriate Setting Type in SCCM to verify Device Registration Task installation

After installing the Device Trust client on your managed Windows computers, SCCM runs a script to verify that installation was successful. Make sure to specify either File System or Registry in your Detection Rule. Do not use the Windows Installer setting type to detect the installation, as SCCM cannot detect the Device Trust client using that setting.

Obtain the Registration Task

To leverage the security benefits of the Trusted Platform Module (TPM), see Enhance Windows Device Trust security with Trusted Platform Module (TPM).

To obtain an Early Access (EA) version of the Registration Task

Unlike the GA version, EA versions of the Device Registration Task are not available from the Downloads page in the Okta Admin Console. To obtain an EA version, you must configure a link as follows:

https://<org>.<okta/oktapreview>.com/static/devicetrust/OktaDeviceRegistrationTaskSetup-x.x.x.<msi/exe>

Where:

  • <org> is the name of your org

  • <okta/oktapreview> denotes either your Okta Production or Preview environment.

  • OktaDeviceRegistrationTaskSetup-x.x.x is the version of the Registration Task. For the latest version of the Registration Task, see Device Trust for Windows Desktop Registration Task Version History.

  • <msi/exe> is the file type of the Registration Task, either .msi or .exe.

For example, a link for downloading .msi Registration Task version 1.4.0 to example.oktapreview.com would look like this:

https://example.oktapreview.com/static/devicetrust/OktaDeviceRegistrationTaskSetup-1.4.0.msi

For version history, see Okta Device Trust for Windows Desktop Registration Task Version History.

To obtain a Generally Available (GA) version of the Registration Task

The latest GA version of the Registration Task is available from the Downloads page in .msi and .exe formats. For version history, see Okta Device Trust for Windows Desktop Registration Task Version History.

  1. In the Admin Console, go to Settings > Downloads.
  2. Scroll to Okta Device Trust for Windows Agents and then click Download Latest for the type of installer you want (.msi or .exe).

Install the Registration Task

Install the Registration Task using either of the following methods:

Method 1: Distribute the Registration Task using a management tool (SCCM)

Follow your organization's procedure for distributing software to domain-joined workstations. If your organization uses SCCM, you may want to refer to the Microsoft article How to Deploy Applications in Configuration Manager. Execute the appropriate command for *.exe or *.msi installation.

About the Device Registration Task and proxy servers

If your organization routes internet traffic through a proxy server, you must do the following:

Use a command line to install the Device Registration Task and include parameters

Install Device Registration Task version 1.2.2+ through a command line and append the appropriate HttpProxy parameter to the installation command. This is necessary because the Registration Task installer installs these two scheduled tasks:

  • A user task that runs as the logged-in user.
  • A device task that runs as a network service. If you set up your proxy server(s) as part of your Internet Explorer (IE) configuration, the device task does not detect your IE settings unless you specify that behavior through a command line as shown in the following examples.

Include the parameter appropriate for your environment:

Proxy server environments

HttpProxy=http://<your proxy http url>:<port number>

For example, the installation command that includes the proxy server parameter would look similar to this for:

MSI installation:

msiexec /i OktaDeviceRegistrationTaskSetup-1.x.x-xxxxxxx INSTALLDIR="c:\Program Files\Okta\DeviceTrust" EXEOPTIONS="/q2 OktaURL=https://<your Okta org>/ HttpProxy=http://<your proxy http url>:<port number>"

EXE installation:

OktaDeviceRegistrationTaskSetup-1.0.0-XXXX.exe /q2 OktaURL=https://<your-okta-org-url>.com HttpProxy=http://<your proxy http url>:<port number>

Make sure to add a space if you are also adding the parameter to disable automatic certificate handling.

Proxy Auto-Configuration (PAC) environments

A. Specify the PAC location

HttpProxyPacLocation=http://mypacfile.url.location

For example, the installation command that includes the PAC location parameter would look similar to this for:

MSI installation:

msiexec /i OktaDeviceRegistrationTaskSetup-1.x.x-xxxxxxx INSTALLDIR="c:\Program Files\Okta\DeviceTrust" EXEOPTIONS="/q2 OktaURL=https://<your Okta org>/ HttpProxyPacLocation=http://mypacfile.url.location"

EXE installation:

OktaDeviceRegistrationTaskSetup-1.0.0-XXXX.exe /q2 OktaURL=https://<your-okta-org-url>.com HttpProxyPacLocation=http://mypacfile.url.location

Make sure to add a space if you are also adding the parameter to disable automatic certificate handling.

B. Optional. Allow your Okta org

If you implement a PAC file in your proxy environment, consider allowing your Okta org by adding an exception to the PAC file like this:

if(localHostOrDomainIs(host,"*.okta.com"))

{ return "DIRECT"; }



Ensure clients can complete the MTLS handshake

The Mutual TLS certificate exchange (handshake) in this Device Trust flow occurs on Okta URLs that are separate from your Okta org URL (indicated by the wildcard character (*) in the following example). Make sure to configure proxy servers/proxy clients, as well as any endpoint protection software you may implement, in a way that does not block your clients from completing the certificate exchange with Okta. For example, if your organization uses an allowlist to limit outbound traffic, add these exact URLs to the allowlist, including the wildcard character (*):

*.okta.com

*.okta-emea.com

*.okta-gov.com

With automatic certificate challenge handling: MSI installation msiexec /i OktaDeviceRegistrationTaskSetup-1.x.x-xxxxxxx INSTALLDIR="c:\Program Files\Okta\DeviceTrust" EXEOPTIONS="/q2 OktaURL=https://<your Okta org>"

EXE installation OktaDeviceRegistrationTaskSetup-1.0.0-XXXX.exe /q2 OktaURL=https://<your-okta-org-url>.com

Without automatic certificate challenge handling: MSI installation msiexec /i OktaDeviceRegistrationTaskSetup-1.x.x-xxxxxxx INSTALLDIR="c:\Program Files\Okta\DeviceTrust" EXEOPTIONS="/q2 OktaURL=https://<your Okta org>/ SkipBrowserSetup=true"

EXE installation

OktaDeviceRegistrationTaskSetup-1.0.0-XXXX.exe /q2 OktaURL=https://<your-okta-org-url>.com/ SkipBrowserSetup=true

Method 2: Manually install the Registration Task

This procedure is provided in case you want to install the Registration Task manually during the testing or Proof of Concept phase of your implementation.

  1. Copy the Registration Task to the domain-joined Windows computer.
  2. Run the command prompt as an Administrator.
    1. Click Start.
    2. In the search box, enter cmd, and then press CTRL+SHIFT+ENTER.
  3. Change directories to the location of the file.
  4. Issue the command appropriate for the file type, either *.msi or *.exe. For installation and proxy server details, see the previous section Distribute the Registration Task using a management tool (SCCM).

2.3 Verify certificate enrollment before you configure the Trusted option in app sign-on policy rules

Before you configure the Trusted option for apps in app sign-on policy rules, you must make sure that certificates are installed in the certificate store on the domain-joined computers you have targeted for this Device Trust solution. If certificates are not installed and the Trusted setting is enabled, users are denied access to the app and are redirected to a security message advising them to contact their administrator. (You can configure the message to include a Learn more link to more information. See Enable the global Device Trust setting for your org). To verify certificate enrollment, Okta recommends that you use your management tool to parse the Windows Event Viewer, or use a command line to query the user certificate store directly. Look for Okta MTLS certificate.

If an end user is deactivated, all Device Trust certificates installed on their domain-joined Windows computer(s) are revoked (but not removed) automatically. To remove revoked certificates, see Revoke and remove Device Trust certificates.

Though you'll probably use a management tool to verify that certificates are installed on multiple domain-joined computers, here are two ways to check enrollment on a single computer:

Verify with Windows Event Viewer

  1. Go to Start and enter event in the search field.
  2. When Event Viewer appears at the top of the Start menu, press Enter to open it.
  3. Expand Applications and Services Logs.
  4. Click Okta Device Trust and find Event ID 1000.

Verify with Microsoft Management Console

  1. Go to Start and enter mmc in the search field to open the console.
  2. Go to File and click Add/Remove Snap-in.
  3. Select Certificates and then click Add.
  4. In the Certificates snap-in dialog box, select My user account.
  5. Click Finish.
  6. Click OK.
  7. Under Console Root, expand Certificates - Current User.
  8. Expand the Personal folder, click Certificates and see the Okta MTLS certificate.

>2.4. Optional. Use GPO to configure browsers to select the certificate automatically.

If appropriate for your environment, you can use a Group Policy Object (GPO) tool instead of the default capability of the Device Registration Task to configure browsers to automatically select the Device Trust certificate. If you use a GPO tool, make sure that you have added the flag SkipBrowserSetup=true to the Registration Task installation command. See Install a Device Trust-supported version of the Okta IWA web app in your AD domain.

If you don't configure automatic certificate selection — either through the Registration Task or a GPO — end users are prompted to select the certificate when accessing the app. To make the selection easier for end users, only the Okta Device Trust certificate will be shown to them in this case.

Depending on the refresh interval, changes you make using GPO may not be seen immediately on Windows client computers. For more information, see the Microsoft article Group Policy refresh interval for computers.

To configure Chrome to select the Device Trust certificate automatically
  1. Download policy templates.
  2. Extract the zip file to the Desktop of the Active Directory Domain Controller.
  3. Copy files to folders:
  4. Copy:

    C:\end users\Administrator\Desktop\policy_templates\windows\admx\en-US\chrome.adml

    To:

    C:\Windows\PolicyDefinitions\en-US\

    Copy:

    C:\end users\Administrator\Desktop\policy_templates\windows\admx\chrome.admx

    To:

    C:\Windows\PolicyDefinitions\

  5. Open the Group Policy Management Console (GMPC).
    1. In the Start menu type Run.
    2. In Run, enter gpmc.msc.
  6. Expand to the appropriate domain, navigate to Group Policy Objects, right-click Default Domain Policy, and then click Edit.
  7. Navigate to Computer Configuration > Policies > Administrative Templates: Policy definitions (ADMX files) retrieved from the local computer > Google Chrome > Content Settings.
  8. In the right pane click Automatically select client certificate for these sites, and then under Content Settings, click Edit policy setting.
  9. In the dialog box that opens, click Enabled.
  10. Under Options, click Show.
  11. In the Show Contents dialog box, enter a value that specifies the subdomain of your org and indicates whether it applies to your Preview or Production org.
  12. For example:

    If your Okta Preview org URL is https://[*.]oktapreview.com, you would enter the following value:

    {"pattern":"https://[*.]oktapreview.com","filter":{"ISSUER":{"CN":"MTLS Certificate Authority"}}}

    If your Okta Production org URL is https://[*.]okta.com, you would enter the following value:

    {"pattern":"https://[*.]okta.com","filter":{"ISSUER":{"CN":"MTLS Certificate Authority"}}}

  13. Click OK.
  14. Confirm that auto certificate settings are configured:
    1. Refresh GPO, either by waiting for the next GPO refresh interval, or by issuing the gpupdate command.
    2. In Chrome, enter chrome://policy in the address bar, and then press Enter.
    3. Click Show value and verify that the policy AutoSelectCertificateForUrls displays this value:
    4. {"pattern":"https://[*.]oktapreview.com","filter":{"ISSUER":{"CN":"MTLS Certificate Authority"}}}

    You can also confirm settings through the Windows Registry Editor:

    1. Go to Start and enter regedit in the search field
    2. In Registry Editor, navigate to:
    3. >HKEY_LOCAL_MACHINE > SOFTWARE > Policies > Google > Chrome > AutoSelectCertificateForUrls

To configure IE to select the Device Trust certificate automatically
  1. From the Active Directory Domain Controller, open the Group Policy Management Console (GMPC).
    1. In the Start menu type Run.
    2. In Run, enter gpmc.msc and then press Enter.
  2. Expand to the appropriate domain, navigate to Group Policy Objects, right-click Default Domain Policy, and then click Edit.
  3. Navigate to Computer Configuration > Policies > Administrative Templates: Policy definitions (ADMX files) retrieved from the local computer > Windows Components > Internet Explorer > Internet Control Panel > Security Page > Trusted Sites Zone.
  4. In the right pane under Settings, double-click Don't prompt for client certificate selection when no certificates or only one certificate exists.
  5. In the dialog box that opens, click Enabled.
  6. Close open windows.
  7. Navigate to Computer Configuration > Policies > Administrative Templates: Policy definitions (ADMX files) retrieved from the local computer > Windows Components > Internet Explorer > Internet Control Panel > Security Page.
  8. In the right pane under Settings, double click Site to Zone Assignment List.
  9. In the dialog box that opens, click Enabled.
  10. Under Options, next to Enter the zone assignments here, click Show.
  11. Enter the following in the Show Contents dialog box:
    1. In the Value name column, enter either https://*.okta.com or https://*.oktapreview.com depending on whether you are deploying this feature in your Okta Production or Preview org.
    2. In the Value column, enter 2. This value corresponds to the security zone setting Trusted sites zone that you configured in Step 3.

  12. Click OK to close open windows.
  13. Confirm that the GPO settings are configured:
    1. Refresh GPO, either by waiting for the next GPO refresh interval, or by issuing the gpupdate command in a command line.
    2. In the Start menu type Run.
    3. In Run, enter gpedit.msc and then press Enter.
    4. Navigate to Computer Configuration > Policies > Administrative Templates: Policy definitions (ADMX files) retrieved from the local computer > Windows Components > Internet Explorer > Internet Control Panel > Security Page > Internet Zone.
    5. In the right pane under Settings, double-click Don't prompt for client certificate selection when no certificates or only one certificate exists.
    6. In the dialog box that opens, confirm that the setting is Enabled.

Step 3. Configure app sign-on policy rules in Okta

About app sign-on policy rules

By default, all Client options in the App Sign On Rule dialog box are pre-selected. To configure more granular access to the app, create rules that reflect:

  • Who users are, or the groups to which they belong
  • Whether they are on or off network, or within a defined network zone
  • The type of client running on their device (Office 365 apps only)
  • The platform of their mobile or desktop device
  • Whether or not their devices are Trusted

Taking an allow-list approach to sign-on policy rules

    1. Create one or more Allow rules to support the scenarios that will allow access to the app, then assign those rules the highest priority.
    2. Create a Deny catch-all rule that will apply to users who don't match the permissive scenarios you created in Step 1. Assign the Deny catch-all rule the lowest priority, just above the default rule. In the allow-list approach described here, the default rule is never reached because it is effectively negated by the Deny catch-all rule.

    For important security information about creating app sign-on policy rules, see About app sign-on policies.

Procedure

  1. In the Admin Console, go to Applications > Applications, and then click the SAML or WS-enabled app that you want to protect with Device Trust.
  2. Click the Sign On tab.
  3. Scroll down to the Sign On Policy, and click Add Rule.
  4. Configure one or more rules using the following example as a guide.

This example shows Device Trust rules for managing access to Office 365. For other apps, note that the section If the user's client is any of these isn't present.

Example Allowlist

Example Rule 1: Exchange ActiveSync or Legacy Auth; All platforms; Any Trust; Allow access

  1. Enter a descriptive rule name.

Conditions:

  1. Under PEOPLE, specify whether to apply the rule to individuals only or to individuals and groups. The option you select must be the same for all the rules you create for this example.
  2. Under LOCATION, specify the user location to which the rule will apply. The option you select must be the same for all the rules you create for this example.
  3. Under CLIENT, configure the following settings:
  4. Web browser unselected.

    Modern Auth client unselected.

    Exchange ActiveSync client or Legacy Auth client is selected.

    Mobile

    iOS is selected.

    Android is selected.

    Other mobile (e.g. BlackBerry) is selected.

    Desktop

    Windows is selected.

    macOS is selected.

    Other desktop (e.g. Linux) is selected

  5. Under DEVICE TRUST, configure the following:
  6. Trusted and Not trusted options in the Device Trust section are selectable only when all of the following options in the Client section are not selected:

    • Exchange ActiveSync or Legacy Auth client
    • Other mobile (for example, BlackBerry)
    • Other desktop (for example, Linux)

    Any is selected.

    Trusted is unselected.

    Not trusted is unselected.

Actions:

  1. Configure Access.
  2. Allowed is selected.

  3. Click Save.
  4. Create Rule 2.

Example Rule 2: Web browser or Modern Auth; Windows; Trusted; Allow access + MFA

  1. Enter a descriptive name for the rule.

Conditions:

  1. Under PEOPLE, select the same People option that you selected in Rule 1. The People option needs to be the same for all rules in this example.
  2. Under LOCATION, select the same Location option that you selected in Rule 1. The Location option needs to be the same for all rules in this example.
  3. Under CLIENT, configure the following settings:
  4. Web browser selected.

    Modern Auth client selected.

    Exchange ActiveSync client is unselected.

    Mobile

    iOS is unselected.

    Android is unselected.

    Other mobile (e.g. BlackBerry) is unselected.

    Desktop

    Windows is selected.

    macOS is unselected.

    Other desktop (e.g. Linux) is unselected.

  5. Under DEVICE TRUST, configure the following:
  6. Trusted and Not trusted options in the Device Trust section are selectable only when all of the following options in the Client section are not selected:

    • Exchange ActiveSync or Legacy Auth client
    • Other mobile (for example, BlackBerry)
    • Other desktop (for example, Linux)

    Any is unselected.

    Trusted is selected.

    Not trusted is unselected.

Actions:

  1. Configure Access:
  2. Allowed is selected.

    Prompt for factor is selected.

  3. Click Save.
  4. Create Rule 3.

Example Rule 3: Web browser or Modern Auth; All platforms except Windows; Any Trust, Allow access + MFA

  1. Enter a descriptive name for the rule.

Conditions:

  1. Under PEOPLE, select the same People option that you selected in Rule 1. The option must be the same for all rules in this example.
  2. Under LOCATION, select the same Location option that you selected in Rule 1. The option must be the same for all rules in this example.
  3. Under CLIENT, configure the following settings:
  4. Web browser selected.

    Modern Auth client selected.

    Exchange ActiveSync client is unselected.

    Mobile

    iOS is selected.

    Android is selected.

    Other mobile (e.g. BlackBerry) is selected.

    Desktop

    Windows is selected

    macOS is selected

    Other desktop (e.g. Linux) is selected

  5. Under DEVICE TRUST, configure the following:
  6. Trusted and Not trusted options in the Device Trust section are selectable only when all of the following options in the Client section are not selected:

    • Exchange ActiveSync or Legacy Auth client
    • Other mobile (for example, BlackBerry)
    • Other desktop (for example, Linux)

    Any is selected.

    Trusted is unselected.

    Not trusted is unselected.

Actions:

  1. Configure Access.
  2. Allowed is selected.

    Prompt for factor is selected.

  3. Click Save.
  4. Create Rule 4.

Example Rule 4: Any client; All platforms; Any Trust; Deny access

  1. Enter a descriptive name for the rule.

Conditions:

  1. Under PEOPLE, select the same People option that you selected in Rule 1. The option must be the same for all the rules you create for this example.
  2. Under LOCATION, select the same Location option that you selected in Rule 1. The option must be the same for all the rules you create for this example.
  3. Under CLIENT, configure the following settings:
  4. Web browser selected.

    Modern Auth client selected.

    Exchange ActiveSync client is selected.

    Mobile

    iOS is selected.

    Android is selected.

    Other mobile (e.g. BlackBerry) is selected.

    Desktop

    Windows is selected.

    macOS is selected.

    Other desktop (e.g. Linux) is selected.

  5. Under DEVICE TRUST, configure the following:
  6. Trusted and Not trusted options in the Device Trust section are selectable only when all of the following options in the Client section are not selected:

    • Exchange ActiveSync or Legacy Auth client
    • Other mobile (for example, BlackBerry)
    • Other desktop (for example, Linux)

    Any is selected.

    Trusted is unselected.

    Not trusted is unselected.

Actions:

  1. Configure Access.
  2. Denied is selected.

  3. Click Save.

Example Rule 5: Default sign on rule – Any client; All platforms; Any Trust; Allow access

The Default sign-on rule is already created and cannot be edited. Note that in this allowlist example, the Default rule is never reached because it is effectively negated by Rule 4.

Revoke and remove Device Trust certificates

You may need to revoke an end user's Device Trust certificate(s) from the Okta Certificate Authority. This is recommended if the computer is lost or stolen, or if the end user is deactivated. To re-secure an end user's computer with Device Trust after revoking their Device Trust certificate(s), you need to remove the revoked certificate from their computer before enrolling a new certificate.

Be aware of the following:

  • Steps 1 - 4 of this procedure revoke all Device Trust certificates from the Okta Certificate Authority that were issued to the end user. Certificate revocation does not remove existing certificates from managed Windows computers. In order to re-secure a Windows computer with Device Trust after revoking certificates, you must first remove any existing Device Trust certificate from the computer and then re-enroll the computer with a new certificate as detailed in Step 5. The Device Registration Task will not enroll a new certificate if another certificate (whether revoked or not) is present on the computer.
  • Deactivating an end user in Okta also revokes their Device Trust certificate from the Okta Certificate Authority (but does not remove the certificate from their computer).
  1. In the Admin Console, go to Directory >People.
  2. Click the end user whose Device Trust certificate you want to revoke.

  3. In the More Actions menu, click Revoke Trust Certificate.

  4. Read the message that displays, and then click Revoke Trust Certificate.

  5. Optional. If you want to re-secure the end user's computer with Device Trust, first remove any existing Device Trust certificate from the computer.

    • To remove a certificate from a single computer (such as during testing or the Proof of Concept phase of your implementation), use a third-party management tool such as Certificate Manager Tool (Certmgr.exe) to remove the certificate issued by the Okta MTLS Certificate Authority.

    • To remove certificates from multiple computers, use a third-party management tool such as GPO or SCCM to remove the certificate issued by the Okta MTLS Certificate Authority.

Troubleshooting

Okta Device Trust for Windows generates a certificate on domain-joined Windows devices and presents it to Okta when a Device Trust-secured WS-Fed or SAML app is launched. The two problems that you are most likely to encounter are:

  • Trusted devices are unable to access Device Trust-secured apps.
  • Untrusted devices are able to access Device Trust-secured apps.

If you encounter either problem, try to correct it by performing Basic Troubleshooting. If the problem persists, perform Advanced Troubleshooting.

Basic Troubleshooting

To perform basic troubleshooting, review the following areas:

IWA web app installation and setup

Verify the following:

If the problem persists, proceed to Advanced Troubleshooting.

Enablement

Verify that you have enabled the global Device Trust setting in Security > Device Trust.

Registration task

Verify that you have distributed the Device Registration Task to Windows domain-joined workstations.

Proxy server environments: For the Registration Task installation to succeed in environments that implement a proxy server, you must install Device Registration Task version 1.2.1 or later using a command line and append the appropriate HttpProxy parameter to the installation command.

See Install the Registration Task.

Certificate

Verify that the certificate is installed

  1. Open Microsoft Management Console. See Verify with Microsoft Management Console.
  2. Open the end user's personal store (not the Local computer store).
  3. Verify that a single certificate appears under Personal > Certificates issued by MTLS Certificate Authority.
  4. If no certificate appears, see Advanced Troubleshooting.
Known Issue – Auth failure caused by blocked Mutual TLS certificate exchange

The Mutual TLS certificate exchange (handshake) in this Device Trust flow occurs on Okta URLs that are separate from your Okta org URL (indicated by the wildcard character (*) in the following example). Make sure to configure proxy servers/proxy clients, as well as any endpoint protection software you may implement, in a way that does not block your clients from completing the certificate exchange with Okta. For example, if your organization uses an allowlist to limit outbound traffic, add these exact URLs to the allowlist, including the wildcard character (*):

*.okta.com

*.okta-emea.com

*.okta-gov.com

Sign-on policy

Verify the following:

You have configured a sign-on policy that:

  • Is applied to the WS-Fed or SAML app that you want to secure with Device Trust.
  • Is applied to the correct user(s) and/or groups.
  • Includes, at minimum, an Active rule that denies access to untrusted devices.

System Log

Review the System Log to verify the following Device Trust System Log events:

Authentication

  • DisplayMessage: Authentication of device through a certificate
  • EventType: user.authentication.authenticate

Enrollment

  • DisplayMessage: Device Trust certificate enrollment
  • EventType: user.credential.enroll

Issuance

  • DisplayMessage: Device Trust certificate issuance
  • EventType: pki.cert.issue

Revocation

  • DisplayMessage: Device Trust certificate revocation
  • EventType: pki.cert.revoke

Renewal

  • DisplayMessage: Device Trust certificate renewal
  • EventType: pki.cert.renew

View unique device IDs in DebugContext

DebugData shows the unique ID of the devices associated with Device Trust events and is useful for debugging purposes. This information can also help you verify thatDevice Trust is being enforced on devices in your device inventory, which may be useful prior to rolling out the feature to a large group of users.

The information contained in debugContext.debugData is intended to add context when troubleshooting customer platform issues. Note that key names and values are subject to change without notice and should be used primarily as a debugging aid, not as a data contract. See DebugContext Object in Okta Developer documentation.

  1. In the Admin Console, go to Reports > System Log.
  2. Search for the Device Trust Event (date) that you’re interested in, then navigate to:

    Event > AuthenticationContext > System > DebugContext > DebugData

Advanced Troubleshooting

If Basic Troubleshooting didn't resolve the problem you are experiencing, and the certificate isn't installed on the Windows workstation, check in the following locations:

In the Okta Admin Console

Verify the following:

  • The org has an active Active Directory (AD) integration (Directory > Directory Integrations)
  • The end user of the domain-joined Windows computer is:
    • Present in Directory > People
    • Activated
    • A member of the Active Directory domain
  • The IWA web app is:
    • Primary
    • Enabled
  • A Device Trust-capable version

(Security > Delegated Authentication > IWA Agents)

On the IWA server

Check IIS settings for the IWA web app

  1. Click Start.
  2. In the search box, enter IIS.
  3. Right click Internet Information Services Manager and select Run as administrator.
  4. If the IWA web app is configured for SSL, open SSL settings and make sure the option Require SSL is selected.
  5. Open the Authentication feature and make sure Windows Authentication is Enabled.

Check for errors in the web.config file

  1. Go to C:\Inetpub\wwwroot\IWA\web.config.
  2. Use a validation tool to make sure the web.config file contains valid XML syntax.
  3. If HTTPS was enabled in IIS on the site, make sure that the web.config file enables SecureBindingForDeviceTrust.

Check for errors in Windows Logs > Applications and Services Logs > Okta Single Sign On

  1. Click Start.
  2. In the search box, enter Event Viewer.
  3. Expand Application and Services Logs.
  4. Check for errors in Okta Single Sign On.

On the domain-joined Windows computer

Make sure Okta Device Trust Tasks were installed and successful:

  1. Click Start.
  2. In the search box, enter Task Scheduler.
  3. Right click Task Scheduler and select Run as administrator.
  4. Make sure the okta-devicetrust-devicetask and okta-devicestrust-usertask tasks appear and have completed successfully.

Check for errors in Windows Logs > Applications and Services Logs > Okta Device Trust:

  1. Click Start.
  2. In the search box, enter Event Viewer.
  3. Expand Application and Services Logs.
  4. Click Okta Device Trust.

Force certificate renewal in some circumstances

Certificates are valid for one year and are renewed automatically sometime within 30 days before expiration. In order for automatic renewal to succeed, end users must be logged on to the domain-joined computer and connected to your corporate network.

You can manually force certificate renewal to try to fix the following problems (requires Device Registration Task 1.3.1 or later):

  • An end user's certificate was incorrectly or accidentally revoked by the admin through the Admin Console (see Revoke).
  • The certificate was corrupted on the client due to accidental deletion, file corruption, or loss of the private key.

Open a command prompt and issue the following command:

"C:\Program Files\Okta\DeviceTrust\OktaDeviceReg.exe" --user --forceRenewal

Run the task in debug mode as the logged-on user

  1. Make sure the IWA server is reachable when the task is run (either directly over the internet or through a VPN).
  2. Open a command prompt and issue the following command:

    "C:\Program Files\Okta\DeviceTrust\OktaDeviceReg.exe" --user --debug

  3. If the Device Trustcertificate isn't generated on the device, the task executes the following actions:
    • Contacts Okta at the registry value pointed to by HKLM\Software\Okta\DeviceTrust\OktaOrgUrl and gets the location of the IWA server for the org.
    • Contacts the IWA server to generate the device token for the device.
    • Contacts the IWA server to generate a user token based on the device token.
    • Contacts Okta with the generated user token to generate the certificate.
    • Installs the certificate in the user's personal store.

The user token is a set of JWT claims signed by the IWA server. You may be asked to copy the token and provide it to Okta Support for analysis.

Known issues

  • Multiple apps opening simultaneously: If multiple apps secured by Device Trust are configured to open automatically when end users sign in to their Okta dashboard from IE or Edge browsers, only one of the apps completes the Device Trust flow. Access to the remaining apps fails and end users are presented a message advising them to contact their administrator. (See Enable the global Device Trust setting for your org.)
  • Okta Device Trust for Windows + certificate-based IWA for SSO: Configuring this Device Trust solution may cause an incompatibility issue if your org is configured with certificate-based IWA to support SSO for iOS and Android mobile devices. In that case, end users signing in to Okta using IWA from Windows computers with a Device Trust certificate and an IWA certificate installed may be presented with a certificate picker containing both certificates during the Desktop SSO flow, which may cause confusion. If end users select the Device Trust certificate, they will get a 403 error during the IWA flow. It may be possible to enable certificate hinting in IIS so that only one certificate is shown to users. See the Microsoft article Schannel SSP Technical Overview.
  • Checking .NET version: The Device Registration Task checks the version of the .NET Framework running on managed Windows computers. If the version isn't 4.5.2 or later, the Registration Task automatically installs version 4.5.2. During installation, progress indicators and other installation dialog boxes appear on the end user screen.