Manage device connection requirements using Terraform

Require users to authenticate only with phones and computers that meet your org's requirements.

Learning outcomes

Improve device security, resource management, and consistency with Okta device assurance policies.
Review device compliance in the Okta Admin Console.
Create Okta device assurance policies in Terraform.
Enforce device requirements during Okta user authentication.

What you need

Familiarity with Terraform terms: configuration, resources, state, and commands. See the Terraform overview.
An Okta organization.
A Terraform configuration that can access your Okta org.
An Okta pricing plan that enables Device Assurance in your organization.
An Okta user account with the super admin role.
A list of your org's requirements for user devices.

Overview

Using a device's attributes to control access to your org requires configuring two sets of policies. Device assurance policies configure device requirements, such as a minimum OS version. Authentication policies include rules that use the assurance policies to authorize a connection.

You can manage both types of policies with Terraform.

These are the benefits of device assurance policies:

Improve security by checking that devices meet minimum requirements, such as the latest OS updates.
Improve device configuration consistency, which reduces support burden and vulnerability risks.
Simplify resource management, policy adjustments, security audits, and policy enforcement by displaying device compliance on one dashboard.

Okta supports device assurance for Android, iOS, macOS, Windows, and ChromeOS platforms. Each platform requires a minimum OS to support the device assurance feature. For more information, see the minimum supported OS versions (opens new window).

For user instructions on how to check device compliance, see the main Okta article for device assurance (opens new window).

Confirm your org supports Device Assurance

Some of the steps in this article require that your Okta org and pricing plan support device assurance.

Sign in to your Okta org (opens new window) with an admin account.
Open the Admin menu.
Go to Security > Authentication Policies.

Note: Ignore the Security > Device Assurance Policies navigation item for this test.
Click a policy, whether it's default or one you've already created.
Click Add rule.
Set AND Device state is to Registered.
Search for a field with the content:
```
AND Device assurance policy is
```
If the field exists then you can create device assurance policies and reference them in authentication policies. Otherwise, contact Okta Support about feature availability.
Click Cancel to exit the policy editor.

Grant API scopes to your API service application

To manage device assurance policies, your Terraform integration must have the following API scopes:

okta.deviceAssurance.manage
okta.policies.manage

For more information on granting scopes, see Manage your list of API scopes.

Add a device assurance policy

A different Okta Terraform provider resource represents each device platform as their attributes vary. For example, only mobile devices include an attribute to check for a jailbroken device.

Add code to your configuration for the desired devices and policies. Okta recommends grouping the files for your Terraform scripts into group-related resources. For example, use a file called devices.tf for all the code to configure the device assurance resources. For more information, see Manage your list of API scopes.

Design policies based on which attributes to allow and which to deny. For example, you can deny access to any jailbroken mobile device by setting the jailbreak attribute to false. Similarly, you can set the os_version attribute to 10.0 to allow all Windows devices running that version of the OS or higher.

The following code adds device assurance policies for each platform that checks for a minimum OS:

resource okta_policy_device_assurance_android device_android {
  name = "Android minimum standards"
  os_version = "12"
}

resource okta_policy_device_assurance_ios device_ios {
   name = "iOS minimum standards"
   os_version = "17.4.1"
}

resource okta_policy_device_assurance_macos device_macos {
   name = "macOS minimum standards"
   os_version = "14.1.1"
}

resource okta_policy_device_assurance_windows device_windows {
   name = "Windows minimum standards"
   os_version = "11.0.0"
}

resource okta_policy_device_assurance_chromeos device_chromeos {
  name = "ChromeOS minimum standards"
  tpsp_os_version = "10.0.19041.1110"
}

Here are extended examples for each platform.

Android

Create an Android device assurance policy:

Add the okta_policy_device_assurance_android resource to your configuration.
Set its name argument to a user-visible name for this policy.
Set arguments for different signals. The following are the most commonly checked signals. For the complete signal list, see this resource's provider documentation (opens new window).

os_version: The minimum operating system for a device.
disk_encryption_type: The set of required encryption settings for the device. The available options are FULL (full disk encryption) and USER (OS-level device-created key for profiles (user) encryption).
jailbreak: Specifies if rooted (jailbroken) Android devices are allowed. To forbid rooted devices, set it to false and use it in an authentication rule that checks for this device assurance policy and allows authentication. Setting it to true means that this device assurance policy requires the device to be rooted, which you could use with an authentication rule that explicitly denies access in this case.
secure_hardware_present: Specifies if hardware security is required. This refers to a hardware-based trusted execution environment (also called a trusted processing module) for storing sensitive key material.
screenlock_type: A set of required screen lock actions and behaviors. The supported options are BIOMETRIC (biometric locking), PASSCODE (passcode), and NONE (no requirements).

The following code shows a typical Android device assurance policy:

resource okta_policy_device_assurance_android example{
  name = "Android example"
  os_version = "12"
  disk_encryption_type = toset(["FULL", "USER"])
  jailbreak = false
  secure_hardware_present = true
  screenlock_type = toset(["BIOMETRIC"])
}

iOS

Create an iOS device assurance policy:

Add the okta_policy_device_assurance_ios resource to your configuration.
Set its name argument to a user-visible name for this policy.
Set arguments for different signals. The following are the most commonly checked signals. For the complete list of signals, see the Terraform provider documentation for this resource (opens new window)
- os_version: The minimum operating system for a device.
- jailbreak: Specifies if jailbreak devices are allowed. To forbid jailbroken devices, set this to false and use it in an authentication rule that checks for this device assurance policy. Set the rule to allow authentication. Setting it to true means that this device assurance policy requires jailbreaking, which you could use with an authentication rule that explicitly denies access.
- screenlock_type: A set of required screen lock actions and behaviors. The supported options are BIOMETRIC (biometric locking) and PASSCODE (passcode locking).

The following code shows a typical iOS device assurance policy:

resource okta_policy_device_assurance_ios ios_example {
  name = "iOS example"
  os_version = "12.4.5"
  jailbreak = false
  screenlock_type = toset(["BIOMETRIC"])
}

macOS

Create a macOS device assurance policy:

Add the okta_policy_device_assurance_macos resource to your configuration.
Set the name argument to a user-visible name for this policy.
Set arguments for different signals. The following are the most commonly checked signals. For the complete list of signals, see the Terraform provider documentation for this resource (opens new window).
- os_version: The minimum operating system version for a device.
- disk_encryption_type: The set of required encryption settings for the device. The only option is ALL_INTERNAL_VOLUMES ( all internal volumes are encrypted).
- screenlock_type: A set of required screen lock actions and behaviors. The supported options are BIOMETRIC (biometric locking) and PASSCODE (passcode locking).

Your policy can also check signals on devices from a supported third-party signal provider, such as the Google Chrome Device Trust Connector in the Chrome browser. Specify its device signals in your Terraform code with the fields with the prefix tpsp_. For example, tpsp_os_version instead of os_version. Okta for device assurance for ChromeOS requires using Workforce Identity Adaptive Multi-factor Authentication (AMFA) (opens new window). Developer Edition orgs don't support the Google Chrome Device Trust Connector by default. If you're a paying customer, contact Okta developer support to enable third-party signal support on a Developer Edition org.

The following code shows a typical macOS device assurance policy:

resource okta_policy_device_assurance_macos macos_example {
  name = "macOS example"
  os_version = "12.4.6"
  disk_encryption_type = toset(["ALL_INTERNAL_VOLUMES"])
  secure_hardware_present = true
  screenlock_type = toset(["BIOMETRIC", "PASSCODE"])
}

Windows

Create a Windows device assurance policy:

Add the okta_policy_device_assurance_windows resource to your configuration.
Set its name argument to a user-visible name for this policy.
Set arguments for different signals. The following are the most commonly checked signals. For the complete signal list, see the provider documentation for this resource (opens new window).
- os_version: The minimum operating system for a device.
- disk_encryption_type: The set of required encryption settings for the device. The only option is ALL_INTERNAL_VOLUMES (all internal volumes are encrypted).
- screenlock_type: A set of required screen lock actions and behaviors. The supported options are BIOMETRIC (biometric locking) and PASSCODE (passcode locking).

The following code shows a typical Windows device assurance policy:

resource okta_policy_device_assurance_windows windows_example {
  name = "Windows example"
  os_version = "12.4.6"
  disk_encryption_type = toset(["ALL_INTERNAL_VOLUMES"])
  secure_hardware_present = true
  screenlock_type = toset(["BIOMETRIC", "PASSCODE"])
}

ChromeOS

Some Okta device assurance policies support ChromeOS configurations. Okta for device assurance for ChromeOS requires using Workforce Identity Adaptive Multi-factor Authentication (AMFA) (opens new window). Developer Edition orgs don't support the Google Chrome Device Trust Connector by default. If you're a paying customer, contact Okta developer support to enable ChromeOS support on a Developer Edition org.

Add the okta_policy_device_assurance_chromeos resource to your configuration.
Set its name argument to a user-visible name for this policy.
Set arguments for different signals. The following are the most commonly checked signals. For the complete signal list, see the Terraform provider documentation for this resource (opens new window). The fields for signals have the prefix tpsp_, which stands for third-party signal provider.
- tpsp_os_version: The minimum operating system for a device.
- tpsp_disk_encrypted: Checks if the disk is encrypted.
- tpsp_screen_lock_secured: Specifies if the screen lock is secured.

The following code shows a typical ChromOS device assurance policy:

resource okta_policy_device_assurance_chromeos example{
  name = "example chromeos"
  tpsp_allow_screen_lock = true
  tpsp_browser_version = "15393.27.0"
  tpsp_builtin_dns_client_enabled = true
  tpsp_chrome_remote_desktop_app_blocked = true
  tpsp_disk_encrypted = true
  tpsp_os_firewall = true
  tpsp_os_version = "10.0.19041.1110"
  tpsp_realtime_url_check_mode = true
  tpsp_screen_lock_secured = true
}

Use device assurance for authentication

To use device assurance, add one or more device assurance policies to an authentication policy.

There are two approaches to defining an authentication policy:

Use the default authentication policy representing your Okta app, such as an OAuth web app. In this case, use a Terraform data source to find the ID for the default authentication policy and then add a rule referencing that policy. For an example, see this policy rule example in the Terraform git repository (opens new window).
Create an authentication policy for your app and set the policy ID in a field in your app resource in Terraform.

The high-level steps to enforce device minimum standards:

Create device assurance policies for your supported platforms.
If you don't already have one, create an app for which you want access control, such as an OAuth web app. See the provider for resources with the name okta_app_<type_name>.
Create an authentication policy resource of type okta_app_signon_policy (opens new window).
Create an authentication policy rule of type okta_app_signon_policy_rule (opens new window) that specifies your device assurance policies. Each rule references its associated policy in its argument policy_id. One rule can reference multiple device assurance policies using a list of their IDs.
Attach the authentication policy to your app by setting the policy ID in the authentication_policy field.

The following example creates an OAuth app using an okta_app_oauth resource and then adds an authentication policy (a sign-on policy) that contains two policy rules:

One policy rule references the device assurance policy as a matching criterion for authentication.
A second policy rule denies all connections that failed the first rule.

Some resource types have a priority field, which includes policies and rules. When your Terraform code includes more than one of these types of resources, you must define their creation order. This is done using a combination of two fields:

Add a priority field and assign a number starting with 1 for the highest priority.
Rules with lower priorities must use the Terraform special attribute depends_on. Set the value to the priority of the rules that must be created before the current one.

This example shows an authentication policy with two device assurance rules that use priority and depends_on. The rule with the lower priority, my_signin_policy_denyall, depends on the one with higher priority:

resource "okta_app_oauth" "OAuthFakeApp" {
  label                      = "OAuthFakeApp"
  type                       = "web"

  authentication_policy      = okta_app_signon_policy.my_signin_policy.id

  # Your other app fields go here

}

# AUTHENTICATION POLICIES AND RULES

resource "okta_app_signon_policy" "my_signin_policy" {
  name        = "My App Sign-On Policy"
  description = "Authentication Policy to be used on my app."
}

resource "okta_app_signon_policy_rule" "my_signin_policy_deviceassurance" {
  policy_id  = okta_app_signon_policy.my_signin_policy.id
  name        = "my_signin_policy_deviceassurance"
  factor_mode = "1FA"
  priority = 1
  access = "ALLOW"  # the default

  device_assurances_included = [
    okta_policy_device_assurance_android.device_android.id,
    okta_policy_device_assurance_ios.device_ios.id,
    okta_policy_device_assurance_macos.device_macos.id,
    okta_policy_device_assurance_windows.device_windows.id
  ]
  constraints = [
    jsonencode({
      "knowledge" : {
        "types" : ["password"]
      },
    })
  ]
}

resource "okta_app_signon_policy_rule" "my_signin_policy_denyall" {
  policy_id  = okta_app_signon_policy.my_signin_policy.id
  name        = "my_signin_policy_denyall"
  factor_mode = "1FA"
  priority = 2
  access = "DENY"

  depends_on = [ okta_app_signon_policy_rule.my_signin_policy_deviceassurance ]
}

Remove a device assurance policy or authentication rules

To remove a device assurance policy from your Terraform configuration:

Remove the resource from your Terraform configuration file.
Remove any references from authentication policies or elsewhere.

When you run terraform apply, Terraform removes the old policies from your Okta org.

Edit This Page On GitHub

On this page