fleet/articles/okta-conditional-access-integration.md

Conditional access: Okta

With Fleet, you can integrate with Okta to enforce conditional access on macOS hosts.

When a host fails a policy in Fleet, IT and Security teams can block access to third-party apps until the issue is resolved.

Prerequisites

Conditional access with Okta requires an mTLS reverse proxy on a separate subdomain (e.g., okta.fleet.example.com). All other Fleet traffic continues to use your existing Fleet server URL. If you're a managed-cloud customer, please reach out to Fleet to set up the mTLS infrastructure for you.

If you would like to set up a testing environment, see the Okta conditional access testing guide.

If you use fleet-terraform modules for AWS hosting, see the okta-conditional-access addon for streamlined mTLS proxy setup.

Otherwise, you'll need to:

1. Get the mTLS CA certificate: Download the CA certificate from Fleet's SCEP endpoint at /api/fleet/conditional_access/scep?operation=GetCACert. This is the certificate that signs the client certificates deployed to your hosts.

Note: The certificate is provided in DER format. If your mTLS termination solution requires PEM format, you can convert it using the following command:

openssl x509 -inform der -in fleet-scep-ca.cer -out fleet-scep-ca.pem

Replace fleet-scep-ca.crt with the filename you used when downloading the certificate.

2. Create a DNS record: Set up a subdomain with an okta prefix pointing to your mTLS proxy server (e.g., okta.fleet.example.com).

3. Configure an mTLS reverse proxy: Set up a reverse proxy that:

   • Requires client certificate authentication using your CA certificate
   • Forwards the X-Client-Cert-Serial header to your Fleet backend

4. Redirect the SSO endpoint: Configure your main Fleet server to redirect /api/fleet/conditional_access/idp/sso to the mTLS proxy (e.g., https://okta.fleet.example.com/api/fleet/conditional_access/idp/sso). This ensures all authentication requests go through mTLS verification.

Example Caddy configuration

Here's an example Caddyfile for setting up the mTLS proxy:

okta.fleet.example.com {
  # Enable TLS with mTLS (client certificate authentication)
  tls {
    client_auth {
      mode require_and_verify
      trusted_ca_cert_file /etc/caddy/fleet-scep-ca.crt
    }
  }

  # Reverse proxy to your Fleet server
  reverse_proxy https://fleet.example.com {
    # Forward client certificate serial number to Fleet
    header_up X-Client-Cert-Serial {http.request.tls.client.serial}
  }
}

Important: Caddy sends the certificate serial number in decimal format, while AWS ALB sends it in hexadecimal format. When using Caddy, you must configure Fleet to parse the serial number in decimal format by setting conditional_access.cert_serial_format to decimal.

Replace:

• okta.fleet.example.com with your mTLS subdomain
• /etc/caddy/fleet-scep-ca.crt with the path to your SCEP CA certificate
• https://fleet.example.com with your Fleet server URL

Step 1: Download IdP signature certificate from Fleet

1. In Fleet, go to Settings > Integrations > Conditional access > Okta and click Connect.
2. In the modal, go to Identity provider (IdP) signature certificate. Click Download certificate.

Step 2: Deploy user scope profile

1. In Fleet, go to Settings > Integrations > Conditional access > Okta and click Connect.
2. In the modal, find the read-only User scope profile.
3. Copy the profile to a new .mobileconfig file and save.
4. Follow the instructions in the Custom OS settings guide to deploy the profile to the hosts where you want conditional access to apply.

Step 3: Create IdP in Okta

1. In the Okta Admin Console, go to Security > Identity Providers.
2. Click Add Identity Provider.
3. Select SAML 2.0 IdP.
4. Set Name to "Fleet".
5. Set IdP Usage to Factor only
6. Set the following values (replace fleet.example.com with your Fleet server domain):
   • IdP Issuer URI: https://fleet.example.com/api/fleet/conditional_access/idp/metadata
   • IdP Single Sign-On URL: https://okta.fleet.example.com/api/fleet/conditional_access/idp/sso (note the okta. prefix)
   • Destination: https://okta.fleet.example.com/api/fleet/conditional_access/idp/sso (note the okta. prefix)
7. For IdP Signature Certificate, upload the IdP signature certificate downloaded from Fleet.
8. Click Finish.

Step 4: Configure Okta settings in Fleet

Once you've created the identity provider in Okta, click on the Fleet identity provider to view its settings. You'll need to copy these values into Fleet.

1. In Fleet, go to Settings > Integrations > Conditional access > Okta and click Connect.
2. Copy the IdP ID from Okta to the IdP ID field.
3. Copy the Assertion Consumer Service URL from Okta to the Assertion consumer service URL field.
4. Copy the Audience URI from Okta to the Audience URI field.
5. In the Okta Admin Console, go to Security > Identity Providers, select Actions for the Fleet identity provider and choose Download certificate.
6. In Fleet, for Okta certificate, upload the certificate downloaded from Okta.

Step 5: Add Fleet IdP authenticator in Okta

1. In the Okta Admin Console, go to Security > Authenticators.
2. Click Add authenticator.
3. Find IdP Authenticator and click Add.
4. In the Identity Provider dropdown, select Fleet.
5. For the logo, download the Fleet logo and upload it.
6. Click Add.

Step 6: Add Fleet to an authentication policy

Create an authentication policy rule that requires Fleet verification for macOS hosts:

1. In the Okta Admin Console, go to Security > Authentication policies.
2. Select the policy you want to modify (or create a new one).
3. Click Add rule.
4. Set a Rule name (e.g., "Require Fleet for macOS").
5. Under AND Device platform is, select One of the following platforms and macOS to ensure this rule only applies to macOS hosts.
6. Under AND User must authenticate with, select Authentication method chain (recommended) and add the Fleet IdP authenticator created in Step 5 as one of the authentication methods.
7. Click Save.

To apply this policy to specific apps, go to Applications > select an app > Sign On tab > Authentication policy and assign the policy.

Step 7: Configure conditional access policies in Fleet

Once Okta is configured in settings, head to Policies. Select the fleet that you want to enable conditional access for.

1. Go to Manage automations > Conditional access and enable conditional access.
2. Select the policies you want to block login via Okta.
3. Save.

Once enabled, if a user tries to log in to an app that requires Fleet as a factor and their host is failing a selected policy, they will be blocked from logging in. To regain access, the user must fix the issue on their host and then click Refetch on the My device page to verify the policy is now passing.

Disabling Okta conditional access

Warning: You must disable conditional access on the Okta side first. If you only disable it on the Fleet side, users may be unable to log in to apps that still require Fleet as an authentication factor.

To disable conditional access on the Okta side:

1. In the Okta Admin Console, go to Security > Authentication policies.
2. Either delete the authentication policy rule that requires Fleet, or remove the policy from all apps by going to Applications > select an app > Sign On tab > Authentication policy and assigning a different policy.

Once disabled on the Okta side, you can delete the conditional access configuration on Fleet's side from Settings > Integrations > Conditional access > Okta and clicking the delete button.

Bypassing conditional access

End users can temporarily bypass conditional access from their My device page if their host is not failing any critical policies. To trigger a bypass, click a non-critical failing policy labeled Action required, select Resolve later, and confirm in the following modal. The bypass allows the user to complete a single login even with failing policies and is consumed immediately upon successful login.

If a host is failing multiple conditional access policies, the bypass option is only available if no failing policy is marked critical. If any one of the failing policies is marked critical, the end user will not see the option to bypass and must resolve the issue to regain access. (You can update a policy's critical setting on the Edit policy page.)

This feature is enabled by default, but can be disabled by checking the Disable bypass checkbox in Settings > Integrations > Conditional access.

Per-policy bypass

Experimental feature. The per-policy bypass setting is experimental, and will be replaced with a reference to the policy's critical setting in Fleet 4.83.0. To ensure a seamless upgrade, please avoid enabling bypass for policies marked critical.

By default, all conditional access policies allow bypassing. You can control which policies allow bypass individually in Manage automations > Conditional access. Each policy with conditional access enabled has an additional checkbox to allow or disallow bypass.

If a host is failing multiple conditional access policies, the bypass option is only available if every failing policy allows bypass. If any one of the failing policies does not allow bypass, the end user will not see the option to bypass and must resolve the issue to regain access.