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