okta: Update documentation

[kcreddy]

Update Okta documentation to match with new doc template.

[elasticmachine]

Pinging @elastic/security-service-integrations (Team:Security-Service Integrations)

[github-actions]

tl;dr: I recommend updating packages/okta/_dev/build/docs/README.md to the current integration doc template structure (Data streams / Requirements / Setup / Troubleshooting / Logs reference), then regenerating packages/okta/docs/README.md with elastic-package build.

Recommendation

Use the same template migration pattern used in CrowdStrike (#15972 -> PR #15927), but scoped to Okta.

Specifically:

1. Edit source template: packages/okta/_dev/build/docs/README.md.
2. Reorganize current content from Agentless Enabled Integration, Logs, and Types Of Authentication into guideline-aligned sections.
3. Keep generated blocks ({{event "system"}}, {{fields "system"}}) in the source template.
4. Run elastic-package build to regenerate packages/okta/docs/README.md.

Findings

• Issue asks to align Okta docs with new template: #17993.
• Repo guidance says README source is _dev/build/docs/README.md, generated output is docs/README.md:
  • docs/extend/finishing-touches.md:49-53,61-67
  • docs/extend/tips-for-building.md:207
• Current Okta structure is older/custom and missing common template sections:
  • packages/okta/_dev/build/docs/README.md:5 (## Agentless Enabled Integration)
  • packages/okta/_dev/build/docs/README.md:10 (## Logs)
  • packages/okta/_dev/build/docs/README.md:16 (## Types Of Authentication)
• Newer packages show expected structure:
  • packages/wiz/docs/README.md:7,21,38,101,112 (Data streams, Requirements, Setup, Troubleshooting, Logs reference)
  • packages/canva/docs/README.md:13,19,25,76
  • packages/openai/docs/README.md:11,26,32
• Direct precedent in this repo:
  • Issue #15972 (“Update ... README.md as per documentation guidelines”)
  • Merged PR #15927 implemented that migration for CrowdStrike.

Verification

I ran local checks to confirm source-vs-generated behavior and heading mismatch:

$ grep -n '^## ' packages/okta/_dev/build/docs/README.md
5:## Agentless Enabled Integration
10:## Logs
16:## Types Of Authentication

$ grep -n '^## ' packages/wiz/docs/README.md | head -n 12
7:## Data streams
21:## Requirements
25:## Elastic Agent
32:## Agentless-enabled integration
38:## Setup
112:## Logs reference

$ grep -nE '\{\{(event|fields|inputDocs)' packages/okta/_dev/build/docs/README.md
55:{{event "system"}}
57:{{fields "system"}}

$ grep -nE '\{\{(event|fields|inputDocs)' packages/okta/docs/README.md
# no matches (as expected; generated output)

Detailed Action Plan

1. Update packages/okta/_dev/build/docs/README.md heading structure:
   • Add/rename to ## Data streams, ## Requirements, ## Setup, optional ## Troubleshooting, ## Logs reference.
2. Move existing authentication guidance under ## Setup with clear subsections:
   • API key auth
   • OAuth2 auth
   • OIN auth
3. Keep agentless notes under ## Requirements or a dedicated ## Agentless-enabled integration subsection (matching current guideline style).
4. Ensure logs section uses standard format:
   • dataset subsection (### System)
   • example event block
   • exported fields block
   • preserve template functions at end ({{event "system"}}, {{fields "system"}}).
5. Regenerate docs:
   • cd packages/okta && elastic-package build
6. Validate output and consistency:
   • check regenerated packages/okta/docs/README.md
   • verify no unresolved template markers in generated file.

Related Items

Type	Link	Relevance
Issue	#17993	Current request (Okta docs update to template)
Issue	#15972	Prior package-specific docs-template migration request
PR	#15927	Merged implementation of #15972 (CrowdStrike docs/layout update)
File	packages/okta/_dev/build/docs/README.md	Editable README source for Okta
File	packages/okta/docs/README.md	Generated README output
File	docs/extend/finishing-touches.md:49-67	Source/build README workflow + required sections
File	docs/extend/tips-for-building.md:207	Confirms generated README flow
File	packages/wiz/docs/README.md	Good in-repo template reference
File	packages/canva/docs/README.md	Good in-repo template reference
File	packages/openai/docs/README.md	Good in-repo template reference

---

What is this? | From workflow: Issue Triage

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.