okta: Update documentation #17993

Activity

1. kcreddy

   added

   Integration:oktaOktaOkta

   Category: Integration qualityCategory: Quality used for SI planningCategory: Quality used for SI planning

   Team:SDE-CrestCrest developers on the Security Integrations team [elastic/sit-crest-contractors]Crest developers on the Security Integrations team [elastic/sit-crest-contractors]

   Team:Security-Service IntegrationsSecurity Service Integrations team [elastic/security-service-integrations]Security Service Integrations team [elastic/security-service-integrations]

   on Mar 24, 2026
2. elasticmachine commented on Mar 24, 2026

   

   elasticmachine

   on Mar 24, 2026

   More actions

   Pinging @elastic/security-service-integrations (Team:Security-Service Integrations)
3. github-actions commented on Mar 24, 2026

   

   github-actionsBot

   on Mar 24, 2026 – with GitHub Actions

   Contributor

   More 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.