From 5eea345c28379d808d467f4b8b0604f16b10b87f Mon Sep 17 00:00:00 2001 From: Carolina Roncaglia Date: Fri, 28 Aug 2026 16:33:57 -0300 Subject: [PATCH] docs: correct how the OAuth private key is supplied The connector form's Okta Private Key field holds a single line, so a pasted multi-line PEM loses its line breaks and the connector fails to parse it. The page told readers to paste the PEM and stated that no conversion was needed. Rewrite the private key format note to lead with that constraint, give the single-line escaped form with a worked example and a conversion command, and carry the error string readers actually see. Note that the self-hosted paths take the multi-line PEM unchanged, so the constraint is not mistaken for a connector limitation. In the README, the OAuth example passed a filename where the key contents belong; that value is never read as a path. Co-Authored-By: Claude Opus 5 (1M context) --- README.md | 5 +++-- docs/connector.mdx | 20 ++++++++++++++++++-- 2 files changed, 21 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index d3698860..ad44d0a9 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ Or auth using a public/private keypair (OAuth 2.0 client credentials with `priva ``` BATON_AUTH_METHOD=private-key-group \ BATON_OKTA_CLIENT_ID=appClientID \ -BATON_OKTA_PRIVATE_KEY='auth.key' \ +BATON_OKTA_PRIVATE_KEY="$(cat auth.key)" \ BATON_OKTA_PRIVATE_KEY_ID=appKID \ BATON_DOMAIN=domain-1234.okta.com baton-okta baton resources @@ -37,7 +37,8 @@ baton resources Notes for OAuth setup: - `BATON_AUTH_METHOD=private-key-group` is required when authenticating via OAuth — without it the CLI defaults to the API Token field group and refuses to start with `field api-token of type string is marked as required but it has a zero-value`. -- The private key must be a PEM-encoded **RSA** key. Both **PKCS#1** (`-----BEGIN RSA PRIVATE KEY-----`) and **PKCS#8** (`-----BEGIN PRIVATE KEY-----`, what `openssl genrsa` produces by default) are accepted, so no conversion step is needed. Elliptic-curve keys are rejected — Okta's DPoP implementation requires RSA. +- `BATON_OKTA_PRIVATE_KEY` takes the key **contents**, not a path to the key file — hence `"$(cat auth.key)"` above. The private key must be a PEM-encoded **RSA** key. Both **PKCS#1** (`-----BEGIN RSA PRIVATE KEY-----`) and **PKCS#8** (`-----BEGIN PRIVATE KEY-----`, what `openssl genrsa` produces by default) are accepted, so converting between them is not necessary. Elliptic-curve keys are rejected — Okta's DPoP implementation requires RSA. +- Configuring through the C1 connector form instead of the CLI? The **Okta Private Key** field holds a single line, so the key goes in with each line break written as a literal `\n`; a pasted multi-line PEM fails with `no PEM block found`. See [`docs/connector.mdx`](docs/connector.mdx). The multi-line PEM above applies to the CLI and environment-variable paths only. - **DPoP is supported** and needs no Okta-side change: leave the app's **Proof of Possession** setting at Okta's default. Earlier revisions of this file and of `docs/connector.mdx` told you to disable DPoP; that instruction described the pre-DPoP connector and was removed in CXH-2198. - The API Services app **must be assigned an admin role** on its **Admin Roles** tab. Granting OAuth scopes is not sufficient. Without a role, most endpoints return `403`, but `GET /api/v1/users` returns `200` with an empty list — so the sync succeeds and finds zero accounts. - See [`docs/connector.mdx`](docs/connector.mdx) for the complete Okta-side setup and [`docs/docs-info.md`](docs/docs-info.md) for the internal detail on key handling, DPoP, and scopes. diff --git a/docs/connector.mdx b/docs/connector.mdx index 459bc170..4ce8e724 100644 --- a/docs/connector.mdx +++ b/docs/connector.mdx @@ -370,7 +370,23 @@ If a sync finishes cleanly with no accounts, check the app's **Admin Roles** tab You'll need the **Client ID**, **Private Key**, and **Private Key ID** when configuring the connector. -**Private key format.** The connector accepts a PEM-encoded **RSA** private key in either format, so no conversion is needed: +**Private key format.** The **Okta Private Key** field in the C1 connector form holds a single line. Pasting a multi-line PEM into it replaces the line breaks with spaces, and the connector rejects the result with `oktaauth: parse private key: no PEM block found`. + +Enter the key on one line, writing each line break as a literal `\n`: + +``` +-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASC...\n-----END PRIVATE KEY----- +``` + +Convert a PEM file to that form with: + +```bash +awk 'BEGIN{ORS="\\n"} {print}' key.pem | sed 's/\\n$//' +``` + +Running the connector self-hosted, pass the key unchanged: `BATON_OKTA_PRIVATE_KEY` and `--okta-private-key` accept the multi-line PEM as it is. The single-line form is a property of the connector form, not of the connector. + +Either PEM encoding works, and converting between them is not necessary: - **PKCS#1** — header line `-----BEGIN RSA PRIVATE KEY-----` - **PKCS#8** — header line `-----BEGIN PRIVATE KEY-----` (what OpenSSL 3.0+ produces by default) @@ -428,7 +444,7 @@ Enter your Okta domain hostname, e.g. `.okta.com`, into the **Okta Enter your credentials: - For **API Token**: paste your API token into the **API token** field. - - For **OAuth 2.0 Private Key**: enter your **Okta Client ID**, **Okta Private Key ID**, and paste the **Okta Private Key** (PEM-encoded). + - For **OAuth 2.0 Private Key**: enter your **Okta Client ID** and **Okta Private Key ID**, then enter your RSA private key into **Okta Private Key** on a single line, with each line break written as `\n`. See **Private key format** above. **Optional.** If desired, click the checkbox to **Sync custom roles**.