Updated Okta conditional access guide.

[getvictor]

Related issue: Resolves #37652

Summary by CodeRabbit

Release Notes

• Documentation
  • Expanded Okta conditional access integration guide with comprehensive step-by-step setup instructions
  • Added detailed configuration steps for mTLS reverse proxy, DNS subdomain setup, and certificate deployment
  • Included guidance for both Fleet-hosted and self-hosted deployment environments
  • Added concrete commands and examples for policy management and integration teardown

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[getvictor]

Adding @rfairburn to review the infra/prerequisites section.

Adding @dantecatalfamo to "test" the guide in his dev environment.

[rfairburn]

Should we also include a reference to https://github.com/fleetdm/fleet-terraform/tree/main/addons/okta-conditional-access if you use our fleet-terraform modules for your on-prem (AWS) hosting solution?

[getvictor]

Should we also include a reference to https://github.com/fleetdm/fleet-terraform/tree/main/addons/okta-conditional-access if you use our fleet-terraform modules for your on-prem (AWS) hosting solution?

@rfairburn Yes, I added. Does the fleet-terraform guide need to mention setting up DNS for domain with okta. prefix?

[getvictor]

@coderabbitai full review

[coderabbitai]

✅ Actions performed

Full review triggered.

[coderabbitai]

Walkthrough

The Okta conditional access integration guide is significantly expanded from a minimal placeholder into a comprehensive, step-by-step tutorial. The documentation now includes infrastructure prerequisites, mTLS proxy configuration, detailed Okta setup instructions, and procedures for enabling and disabling conditional access across both Fleet-hosted and self-hosted deployments.

Changes

Cohort / File(s)

Summary

Okta conditional access guide expansion articles/okta-conditional-access-integration.md

Restructures guide from placeholder to full tutorial with new sections on: mTLS reverse proxy prerequisites (including DNS subdomain and Caddyfile example), IdP certificate download procedures, Okta IdP configuration with explicit metadata/SSO/destination URLs, Fleet IdP authenticator setup in Okta, authentication policy configuration, macOS-specific conditional access policy targeting, and regression-safe disablement steps with concrete Okta-side commands.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• #37078: Adds frontend download flow and API method for fetching the Okta IdP signing certificate, which directly enables the IdP certificate download steps now documented in this guide.

Suggested reviewers

• dantecatalfamo
• rachaelshaw

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The PR description only contains the related issue reference. The template requires a checklist covering changes files, testing, database migrations, and other items, which are all missing or unchecked.	Complete the PR description template by checking/filling relevant sections. Since this is a documentation-only change, ensure documentation-related items are appropriately addressed.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: updating the Okta conditional access integration guide with expanded content.
Linked Issues check	✅ Passed	The PR content addresses all key requirements from issue #37652: infrastructure prerequisites with mTLS setup, steps to disconnect Okta, certificate download instructions, example IdP URLs, Fleet authenticator configuration, authentication policy setup, and macOS scoping.
Out of Scope Changes check	✅ Passed	All changes are within scope—the PR exclusively updates the Okta conditional access guide documentation to address the missing information listed in issue #37652.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch victor/37652-okta-guide

---

📜 Recent review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 18261d9 and 46d11c8.

📒 Files selected for processing (1)

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

🧰 Additional context used

🧠 Learnings (4)

📓 Common learnings

Learnt from: getvictor
Repo: fleetdm/fleet PR: 34566
File: server/service/integration_core_test.go:7500-7511
Timestamp: 2025-10-21T16:04:18.069Z
Learning: Okta conditional access app config in Fleet is Premium-gated and supported both on-prem and in Fleet Cloud; the Cloud-only enforcement applies to the Microsoft compliance partner endpoints, not to the Okta settings.

📚 Learning: 2025-10-21T16:04:18.069Z

Learnt from: getvictor
Repo: fleetdm/fleet PR: 34566
File: server/service/integration_core_test.go:7500-7511
Timestamp: 2025-10-21T16:04:18.069Z
Learning: Okta conditional access app config in Fleet is Premium-gated and supported both on-prem and in Fleet Cloud; the Cloud-only enforcement applies to the Microsoft compliance partner endpoints, not to the Okta settings.

Applied to files:

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

📚 Learning: 2025-11-26T18:58:18.865Z

Learnt from: getvictor
Repo: fleetdm/fleet PR: 36139
File: android/app/src/main/java/com/fleetdm/agent/scep/ScepClientImpl.kt:75-76
Timestamp: 2025-11-26T18:58:18.865Z
Learning: In Fleet's Android MDM agent SCEP implementation (android/app/src/main/java/com/fleetdm/agent/scep/ScepClientImpl.kt), OptimisticCertificateVerifier is intentionally used because: (1) SCEP URL is provided by authenticated MDM server, (2) challenge password authenticates enrollment, (3) enterprise SCEP servers use internal CAs not in system trust stores, (4) enrolled certificate is validated when used.

Applied to files:

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

📚 Learning: 2026-01-02T22:48:09.865Z

Learnt from: getvictor
Repo: fleetdm/fleet PR: 37640
File: android/app/src/main/java/com/fleetdm/agent/ApiClient.kt:518-522
Timestamp: 2026-01-02T22:48:09.865Z
Learning: In the Fleet Android app's SCEP proxy URL format (android/app/src/main/java/com/fleetdm/agent/ApiClient.kt), the `g` prefix before the certificate ID (e.g., `g$id`) is intentional and stands for "Google Android" to differentiate from other platforms like Apple and Windows.

Applied to files:

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

🪛 LanguageTool

articles/okta-conditional-access-integration.md

[style] ~99-~99: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ertion consumer service URL** field. 4. Copy the Audience URI from Okta to the *...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)

---

[style] ~130-~130: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...onal access. 2. Select the policies you want to block login via Okta. 3. Save. Once en...

(REP_WANT_TO_VB)

---

[style] ~133-~133: Consider using a different verb for a more formal wording.
Context: ...ing in. To regain access, the user must fix the issue on their host and then click ...

(FIX_RESOLVE)

🔇 Additional comments (7)

articles/okta-conditional-access-integration.md (7)

119-120: Verify Okta UI text matches documentation.

The instruction references specific UI text: "One of the following platforms" and selecting "macOS". Since Okta's UI may change, consider verifying this matches the current Okta Admin Console interface or adding a note that UI text may vary.

---

137-142: Excellent warning about disabling order.

The warning to disable on the Okta side first is critical for preventing user lockouts. This is well-placed and clearly emphasizes the correct sequence.

---

85-87: IdP endpoint paths are correct and match the Fleet implementation.

The paths documented are confirmed in the codebase:

• IdP Metadata: /api/fleet/conditional_access/idp/metadata (defined in ee/server/service/condaccess/idp.go)
• IdP SSO: /api/fleet/conditional_access/idp/sso (defined in ee/server/service/condaccess/idp.go)

The okta. prefix for the SSO endpoint is also confirmed in the implementation. No changes needed.

---

21-21: No issues found. The SCEP endpoint path /api/fleet/conditional_access/scep?operation=GetCACert is correctly documented and matches Fleet's actual API implementation.

---

37-55: Caddy configuration syntax is correct.

The {http.request.tls.client.serial} placeholder is valid in Caddy v2 for accessing the client TLS certificate serial number and is properly documented in the official Caddy v2 documentation.

---

133-133: Refetch button confirmed to exist in Fleet UI.

The "Refetch" button exists on the "My device" page in Fleet Desktop as a user-facing control (purple button at the top). It triggers a server-side refetch of the host's details via the Fleet REST API. The documentation guidance is accurate and can remain as written.

---

108-108: The Fleet logo URL is correct and accessible in the repository. No changes needed.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[rfairburn]

@rfairburn Yes, I added. Does the fleet-terraform guide need to mention setting up DNS for domain with okta. prefix?

The configuration snippet includes setting up the DNS and ACM certificate, and does mention "a separate subdomain" in the requirements and mentions "By default the module assumes that okta is added as a subdomain to the Fleet primary domain (e.g. fleet.example.com leverages okta.fleet.example.com), but this can be customized." If you think I need to provide additional context, I'm happy to do so.

[mike-j-thomas]

Thanks, @getvictor. It reads well to me. Good to merge as soon as @rfairburn gives it the technical thumbs up.

[rfairburn]

The changes I suggested are in place, approved.