docs: Okta OAuth 2.0 setup — DPoP, PKCS#1, BATON_AUTH_METHOD (CXH-1519)#167
Merged
luisina-santos merged 1 commit intoMay 22, 2026
Conversation
A customer following the existing OAuth walkthrough in docs/connector.mdx
hits a sequence of failures before reaching a working sync because:
- Okta now defaults Require-DPoP to on for new API Services apps, and the
connector does not implement DPoP ("The DPoP proof JWT header is missing")
- OpenSSL 3.0+ produces PKCS#8 private keys by default, but the v2 Okta Go
SDK rejects anything other than PKCS#1 ("RSA private key is of the wrong
type")
- The CLI requires BATON_AUTH_METHOD=private-key-group to use OAuth, which
the README example does not include
This change is docs-only: it documents the current required workarounds in
docs/connector.mdx and README.md. The underlying connector defects (DPoP
support, PKCS#8 acceptance, --auth-method help text) are tracked separately.
Parent: CXH-1333
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Contributor
Connector PR Review: docs: Okta OAuth 2.0 setup — DPoP, PKCS#1, BATON_AUTH_METHOD (CXH-1519)Blocking Issues: 0 | Suggestions: 0 | Threads Resolved: 0 Review SummaryDocs-only change adding three critical workaround steps to the OAuth 2.0 setup walkthrough in Security IssuesNone found. Correctness IssuesNone found. SuggestionsNone. |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
manuel-ts-14
requested review from
FeliLucero1,
al-conductorone,
luisina-santos,
mateoHernandez123 and
sergiocorral-conductorone
luisina-santos
approved these changes
May 21, 2026
gontzess
approved these changes
May 22, 2026
luisina-santos
deleted the
manueltraversarosasia/cxh-1519-baton-okta-oauth-20-setup-docs-missing-dpop-pkcs1-and-auth
branch
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
BATON_AUTH_METHOD=private-key-groupwhen using OAuth from the CLI.Why this is needed
Reproduced live on 2026-05-20 against
integrator-9077615.okta.com: a customer following the existing OAuth walkthrough verbatim hits this sequence of failures before reaching a working sync. The highest-impact gap is DPoP — Okta now defaults "Require Demonstrating Proof of Possession" to on for new API Services apps, and the connector does not implement DPoP. The customer-visible error ("The DPoP proof JWT header is missing") comes from Okta and gives no indication the connector is the limiting factor, so customers debug the wrong side of the integration.Full diagnosis, reproduction transcript, and the related connector-side defects (separate tickets) are in CXH-1519.
Scope
In scope here:
docs/connector.mdx: one new<Step>(disable DPoP), one new<Warning>callout (PKCS#1 format), three inline<Note>blocks (JWK save gotcha, scope verification, admin role 403).README.md: OAuth env-var example updated withBATON_AUTH_METHOD=private-key-group, plus PKCS#1 and DPoP notes pointing intodocs/connector.mdx.Out of scope — tracked separately:
--auth-methodflag inpkg/config/config.go.Refs:
🤖 Generated with Claude Code